rpick is a command line tool that helps you to pick items from a list, using configurable algorithms.

An example use case for this is picking a restaurant. You might want to generally go to restaurants you haven't visited in a while, but you also might not want to use a strict least recently used model and spice things up with some element of chance, with restaurants you've least recently visited getting a boost in their chances.

Install

You can install rpick in Fedora by enabling its module:

$ sudo dnf module enable rpick:latest $ sudo dnf install rpick

If you are not using Fedora, rpick is also available on crates.io. You can install rpick this way by first installing Rust, and then using Rust's cargo tool to install rpick:

$ cargo install rpick

Quick start

rpick keeps its state in a YAML file in your home config directory called rpick.yml. For now, users must create this file by hand, and rpick will manage it from there. To get started with some examples, create ~/.config/rpick.yml like this:

```

prs: model: even choices: - paper - rock - scissors restaurant: model: gaussian choices: - Spirits - Lucky 32 - Centro - Sitti - Cookout ```

Then you can ask rpick to pick a game of paper rock scissors for you:

$ rpick prs Choice is scissors. Accept? (Y/n)

Note that it would be bad to use the Gaussian model for paper rock scissors, because you have a statistical advantage of guessing that model's results. Let's take a look at the Gaussian model:

$ rpick restaurant Choice is Lucky 32. Accept? (Y/n)

If you say yes, it will rewrite the yaml file like this since we used the Gaussian model:

```

prs: model: even choices: - paper - rock - scissors restaurant: model: gaussian stddevscalingfactor: 3.0 choices: - Spirits - Centro - Sitti - Cookout - Lucky 32 ```

Note that we passed prs and then restaurant as arguments when we called rpick - this told rpick to look for those objects in rpick.yml to find out which models to use and which choices were available. This parameter is required, but its possible values are defined by you in your config file.

The model field in the config file defines which mathematical model to use to pick from the given choices. See the Models section below for more information about which models are available and how you can configure them.

It added one setting to your restaurant object that wasn't there originally: stddev_scaling_factor. You can read more about this setting in the Gaussian model documentation below.

Models

rpick is capable of a few different algorithms for picking choices: even, gaussian, lottery, and weighted.

Even

The even distribution model is the simplest available choice model. It will give an even chance to each item in the list of strings to be chosen. It requires two keys:

Example:

convertible_top: model: even choices: - up - down

You might want to consult the weather before using rpick for this use case…

Gaussian

XKCD's Normal Distribution

The gaussian distribution model is more complex. It uses the Gaussian distribution to prefer choices that have been less recently chosen. Things near the top of the list of choices have the highest probability of being chosen, while things at the end of the list have the lowest chance. Once an item has been picked and the user has accepted the choice, the list is saved to disk with the picked item moved to the end of the list. This model accepts three keys:

Example:

album: model: gaussian stddev_scaling_factor: 5.0 choices: - Fountains of Wayne/Fountains Of Wayne - Beck/Odelay - "Townes Van Zandt/High, Low and In Between" - Tori Amos/From The Choirgirl Hotel - Zao/Parade Of Chaos

To show a visual representation of the relative frequencies of this model, here is a graph that was generated by calling the Gaussian model 10,000 times with the choices set to the numbers 0 to 99 sequentially and a default stddev_scaling_factor of 3.0:

Gaussian example

Lottery

The lottery distribution model is a dynamic version of the weighted model. Each of the choices has a certain number of lottery tickets that influence how likely they are to be picked that round. Once an item is picked, it loses all of its lottery tickets and every choice that wasn't picked gains more lottery tickets. It accepts three keys:

Example:

activity: model: lottery choices: - name: exercise - name: read documentation - name: watch tv weight: 1000

LRU

The lru (Least Recently Used) model is a simple ordered FIFO (First In, First Out) list. The least recently chosen item is the first item in the list. On each pick, rpick simply picks the first item in the list that the user says yes to, and then moves that item to the end of the list. It accepts two keys:

Example:

code: model: lru choices: - Add a feature - Fix a bug - Write some docs

Weighted

The weighted distribution model is a more general version of the even model that allows you to express different weights for each of the choices. It accepts two keys:

Example:

cereal: model: weighted choices: - name: generic bran flakes - name: cracklin oat bran weight: 1000

Changelog

See the Changelog.