From a74360713e1a5eaf5cd9dc5e4a76831237fe03cc Mon Sep 17 00:00:00 2001 From: Saul Pwanson Date: Fri, 11 Oct 2024 17:20:59 -0700 Subject: [PATCH] [docs] update columns.md; add knownCols #1631 --- docs/columns.md | 60 ++++++++++++++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/docs/columns.md b/docs/columns.md index c55554db9..9366a9625 100644 --- a/docs/columns.md +++ b/docs/columns.md @@ -94,10 +94,10 @@ Some types have an option for their default display formatting. Type Option Default --------- ---------------- -------- -int disp_int_fmt {:.0f} -float disp_float_fmt {:.02f} -currency disp_currency_fmt %0.2f -date disp_date_fmt %Y-%m-%d +int `disp_int_fmt` `{:.0f}` +float `disp_float_fmt` `{:.02f}` +currency `disp_currency_fmt` `%0.2f` +date `disp_date_fmt` `%Y-%m-%d` Ways to adjust the display formatting: @@ -108,8 +108,8 @@ Ways to adjust the display formatting: There are several formatting styles offered: -* Formatting that starts with `'%'` (e.g. *%0.2f*) will use [locale.format_string()](https://docs.python.org/3.6/library/locale.html#locale.format_string). -* Otherwise (e.g. *{:.02f}*), formatting will be passed to Python's [string.format()](https://docs.python.org/3/library/string.html#custom-string-formatting). +* Formatting that starts with `'%'` (e.g. `%0.2f`) will use [locale.format_string()](https://docs.python.org/3.6/library/locale.html#locale.format_string). +* Otherwise (e.g. `{:.02f}`), formatting will be passed to Python's [string.format()](https://docs.python.org/3/library/string.html#custom-string-formatting). * Date fmtstr are passed to [strftime](https://strftime.org/). The default for currency uses `locale.format_string()`. The default for int/float/date use `string.format()`. @@ -119,24 +119,36 @@ The default for currency uses `locale.format_string()`. The default for int/floa 1. Set a column to a numeric type by pressing `#` (int), `%` (float), or `$` (currency). 2. Press `Shift+C` to open the **Columns Sheet**. 3. Move to the row referencing the column whose display you wish to format. Move the cursor to the fmtstr column. -4. Type `e` followed by *{:,.0f}* for an `int` type and *{:,.02f}* for a floating point type. +4. Type `e` followed by `{:,.0f}` for an `int` type and `{:,.02f}` for a floating point type. ###### How to quickly adjust the precision of a float or date? -1. Ensure the column is either typed as a float (`%`), floatsi, currency (`$`), or date (`@`). -2. Press `SPACE` and type the longnames `setcol-precision-more` or `setcol-precision-less` to adjust the precision in the current column. +1. Ensure the column is typed as numeric column: float (`%`), floatsi (`z%`), dirty float (`$`), or date (`@`). +2. Press `Alt+Plus` or `Alt+Minus` to adjust the precision in the current column. +3. Or, press `Space` and use the longname `setcol-precision-more` or `setcol-precision-less`. -[Bind the longnames to keys](https://www.visidata.org/docs/customize/), if using these commands frequently. +###### How to automatically set the type of a particular column -###### How to set all date columns to be **month/day/year**. +When loading sheets repeatedly with the same schema, it can be useful to pre-set the column types (and other metadata) in .visidatarc using the `knownCols` attribute on the Sheet class and its subclasses. -The default can be set in a `~/.visidatarc`. +For example, to set the "timestamp" column in every sheet to the `date` type: + +`Sheet.knownCols.timestamp.type = date` + +Or to hide the `nCols` column on the SheetsSheet by default: + +`SheetsSheet.knownCols.nCols.width = 0` + +###### How to format all date columns as **month/day/year**. + +The above method can be used to explicitly set the default `fmtstr` for specifically-named columns. +However, to use a default fmtstr for all date-typed columns, set the `disp_date_fmt` option. In .visidatarc: ~~~ options.disp_date_fmt = '%m/%d/%Y' ~~~ -or passed through the commandline +or pass as a commandline argument: ~~~ vd --disp-date-fmt='%m/%d/%Y' @@ -145,15 +157,15 @@ vd --disp-date-fmt='%m/%d/%Y' or set in the **Options Sheet**. 1. Press `Shift+O` to open the **Options Sheet**. -2. Move the cursor down to the relevant *disp_date_fmt* option. -3. Type `e` followed by *%m/%d/%Y*. +2. Move the cursor down to the relevant `disp_date_fmt` option. +3. Type `e` followed by `%m/%d/%Y`. --- ###### How to specify a comma decimal separator when typing floating point numbers? 1. Before launching VisiData, set the shell environment variable `LC_NUMERIC` to a locale which interprets commas as decimals. Any European locale should do; an example that works is `en_DK.UTF-8`. -2. Within VisiData, set a column to type `floatlocale` by pressing `Space` followed by *type-floatlocale*. +2. Within VisiData, set a column to type `floatlocale` by pressing `Space` followed by `type-floatlocale`. Note that `type-floatlocale` is significantly slower than `type-float`. However, if you wish to replace the current binding for `type-float` with `type-floatlocale`, add to your `~/.visidatarc`: @@ -183,9 +195,9 @@ uses the commands for column splitting and transformation with [xd/puzzles.tsv]( - `:` adds new columns derived from splitting the current column at positions defined by a *regex pattern*. `options.default_sample_size` (default: 100) rows around the cursor will be used to determine the number of columns that will be created. - `;` adds new columns derived from pulling the contents of the current column which match the *regex within capture groups*. The new columns are named using the capture group index, or if named capture groups are used, the capture group names. This command uses the `options.default_sample_size` (default:100) rows around the cursor as sample rows. -- `*` followed by *regex*`/`*substring* replaces the text which matches the capture groups in *regex* with the contents of *substring*. *substring* may include backreferences (*\1* etc). +- `*` followed by *regex* and then `Tab` followed by the *replacement* replaces the text matching the *regex* with the contents of *replacement*. *replacement* may include backreferences to capture groups in the regex (`\1` etc). -## [How do I substitute text in my column] +## How to substitute text in a column The `*` command can be used to do content transformations of cells. The `g*` variant transforms in-place, instead of creating a new column. @@ -195,11 +207,13 @@ The following example uses [benchmarks.csv](https://raw.githubusercontent.com/sa 1. Move cursor to **SKU** column. 2. Press `gs` to select all rows. -3. Type `g*` followed by *food/nutri*. +3. Press `g*` to replace text in selected rows in current column. +4. Type `food` in the search field. +5. Press `Tab` to go to the replace field, then type `nutri`. +6. Press `Enter` to replace the text. - tests/transform-cols.vd - --- ## [How to expand columns that contain nested data](#expand) {#expand} @@ -250,8 +264,8 @@ These variables and functions are available in the scope of an expression: - **`sheet`**: the current sheet (a TableSheet object) - **`col`**: the current column (as a Column object; use for Column metadata) - **`row`**: the current row (a Python object of the internal rowtype) -- **curcol**: evaluate to the typed value of this row in the column that the cursor was on at the time that the expression column was added. -- **cursorCol**: evaluate to the typed value of this row for the column the cursor is on. Changes as the cursor moves for `=`. Uses the column from the time the calculation was made for `g=`, `gz=`, and `z=`. +- **`curcol`**: evaluate to the typed value of this row in the column that the cursor was on at the time that the expression column was added. +- **`cursorCol`**: evaluate to the typed value of this row for the column the cursor is on. Changes as the cursor moves for `=`. Uses the column from the time the calculation was made for `g=`, `gz=`, and `z=`. Additional attributes can be added to sheets and columns. @@ -295,7 +309,7 @@ When using `=`, and wanting to reference the current column, we recommend using **Question** I have a dataset with **file names**. How do I create a new column with the **file names** lower cased? 1. Move the cursor to **file names** column. -2. Type `=` followed by **curcol.casefold()**. +2. Type `=` followed by `curcol.casefold()`. 3. Move to the newly created column, and rename it with `^`, followed by the desired name. ---