nushell/docs/commands/histogram.md

# histogram

Creates a new table with a histogram based on the column name passed in.

Syntax: `histogram <column_name>  ...args`

### Parameters

* `<column-name>`: name of the column to graph by
* `args`: column name to give the histogram's frequency column

## Examples

Let's say we have this file `random_numers.csv` which contains 50 random numbers.

**Note**: The input doesn't have to be numbers it works on strings too. Try it out.

```shell
> open random_numbers.csv
━━━━┯━━━━━━━━━━━━━━━
 #  │ random number 
────┼───────────────
  0 │ 87 
  1 │ 46 
  2 │ 39 
  
   ...

 47 │ 94 
 48 │ 61 
 49 │ 67 
━━━━┷━━━━━━━━━━━━━━━
```

If we now want to see how often the different numbers were generated, we can use the `histogram` function:

```shell
> open random_numbers.csv | histogram "random number"
━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 #  │ random number │ frecuency 
────┼───────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
  0 │ 10            │ ************************* 
  1 │ 14            │ ************************************************** 
  2 │ 17            │ ************************* 
  3 │ 22            │ ************************* 
  4 │ 24            │ ************************* 
  5 │ 28            │ ************************* 
  6 │ 29            │ ************************* 
  7 │ 31            │ ************************* 
  8 │ 37            │ ************************* 
  9 │ 38            │ ************************* 
 10 │ 39            │ ************************* 
 11 │ 45            │ ************************* 
 12 │ 46            │ *************************************************************************** 
 13 │ 49            │ ************************* 
 14 │ 5             │ ************************* 
 15 │ 51            │ *************************************************************************** 
 16 │ 52            │ ************************* 
 17 │ 55            │ ************************* 
 18 │ 56            │ ************************************************** 
 19 │ 60            │ ************************* 
 20 │ 61            │ ************************************************** 
 21 │ 64            │ ************************* 
 22 │ 65            │ ************************* 
 23 │ 67            │ ************************************************** 
 24 │ 68            │ ************************* 
 25 │ 73            │ ************************* 
 26 │ 80            │ ************************************************** 
 27 │ 82            │ ************************* 
 28 │ 86            │ **************************************************************************************************** 
 29 │ 87            │ ************************************************** 
 30 │ 88            │ ************************* 
 31 │ 89            │ ************************* 
 32 │ 9             │ ************************* 
 33 │ 92            │ ************************* 
 34 │ 94            │ ************************* 
 35 │ 96            │ ************************* 
 36 │ 99            │ ************************* 
━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

We can also set the name of the second column or sort the table: 

```shell
> open random_numbers.csv | histogram "random number" probability
━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 #  │ random number │ probability 
────┼───────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
  0 │ 10            │ ************************* 
  1 │ 14            │ ************************************************** 
  2 │ 17            │ ************************* 
  3 │ 22            │ ************************* 
  4 │ 24            │ ************************* 
  5 │ 28            │ ************************* 
  6 │ 29            │ ************************* 
  7 │ 31            │ ************************* 
  8 │ 37            │ ************************* 
  9 │ 38            │ ************************* 
 10 │ 39            │ ************************* 
 11 │ 45            │ ************************* 
 12 │ 46            │ *************************************************************************** 
 13 │ 49            │ ************************* 
 14 │ 5             │ ************************* 
 15 │ 51            │ *************************************************************************** 
 16 │ 52            │ ************************* 
 17 │ 55            │ ************************* 
 18 │ 56            │ ************************************************** 
 19 │ 60            │ ************************* 
 20 │ 61            │ ************************************************** 
 21 │ 64            │ ************************* 
 22 │ 65            │ ************************* 
 23 │ 67            │ ************************************************** 
 24 │ 68            │ ************************* 
 25 │ 73            │ ************************* 
 26 │ 80            │ ************************************************** 
 27 │ 82            │ ************************* 
 28 │ 86            │ **************************************************************************************************** 
 29 │ 87            │ ************************************************** 
 30 │ 88            │ ************************* 
 31 │ 89            │ ************************* 
 32 │ 9             │ ************************* 
 33 │ 92            │ ************************* 
 34 │ 94            │ ************************* 
 35 │ 96            │ ************************* 
 36 │ 99            │ ************************* 
━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

```shell
> open random_numbers.csv | histogram "random number" probability | sort-by probability
━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 #  │ random number │ probability
────┼───────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
  0 │ 10            │ ************************* 
  1 │ 17            │ ************************* 
  2 │ 22            │ ************************* 
  3 │ 24            │ ************************* 
  4 │ 28            │ ************************* 
  5 │ 29            │ ************************* 
  6 │ 31            │ ************************* 
  7 │ 37            │ ************************* 
  8 │ 38            │ ************************* 
  9 │ 39            │ ************************* 
 10 │ 45            │ ************************* 
 11 │ 49            │ ************************* 
 12 │ 5             │ ************************* 
 13 │ 52            │ ************************* 
 14 │ 55            │ ************************* 
 15 │ 60            │ ************************* 
 16 │ 64            │ ************************* 
 17 │ 65            │ ************************* 
 18 │ 68            │ ************************* 
 19 │ 73            │ ************************* 
 20 │ 82            │ ************************* 
 21 │ 88            │ ************************* 
 22 │ 89            │ ************************* 
 23 │ 9             │ ************************* 
 24 │ 92            │ ************************* 
 25 │ 94            │ ************************* 
 26 │ 96            │ ************************* 
 27 │ 99            │ ************************* 
 28 │ 14            │ ************************************************** 
 29 │ 56            │ ************************************************** 
 30 │ 61            │ ************************************************** 
 31 │ 67            │ ************************************************** 
 32 │ 80            │ ************************************************** 
 33 │ 87            │ ************************************************** 
 34 │ 46            │ *************************************************************************** 
 35 │ 51            │ *************************************************************************** 
 36 │ 86            │ **************************************************************************************************** 
━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```