# Category Canonicalize

Paste a CSV, TSV, or newline list plus a variant-to-canonical mapping, then rewrite categorical values and review fuzzy suggestions for anything not covered.

## Run it

- **CLI:** `gizza tool category-canonicalize "country,n
USA,1
u.s.a.,2
Canadaa,3
Brazil,4" 'mapping=USA|U.S.A.|us|united states => United States
Canada|CAN => Canada'`
- **Web:** https://gizza.ai/tools/category-canonicalize/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/category-canonicalize/tool.json

## Inputs

- `data` — CSV / TSV table, or one value per line _(field)_
- `mapping` — Variant → canonical mapping _(field)_
- `column` — Column(s) to canonicalize _(field)_
- `delimiter` — Delimiter _(field)_
- `header` — First row is a header _(field)_
- `ignore_case` — Ignore case while matching _(field)_
- `ignore_spacing` — Collapse whitespace while matching _(field)_
- `unmatched` — Unmatched values _(field)_
- `fuzzy_threshold` — Fuzzy threshold _(field)_
- `output` — Output format _(field)_

## Output

- Canonicalized output (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `data` — CSV / TSV table, or one value per line
- `mapping` — Variant → canonical mapping
- `column` — Column(s) to canonicalize
- `delimiter` — Delimiter
- `header` — First row is a header
- `ignore_case` — Ignore case while matching
- `ignore_spacing` — Collapse whitespace while matching
- `unmatched` — Unmatched values
- `fuzzy_threshold` — Fuzzy threshold
- `output` — Output format

Example: `https://gizza.ai/tools/category-canonicalize/?data=country%2Cn%0AUSA%2C1%0Au.s.a.%2C2%0ACanadaa%2C3%0ABrazil%2C4&mapping=USA%7CU.S.A.%7Cus%7Cunited%20states%20%3D%3E%20United%20States%0ACanada%7CCAN%20%3D%3E%20Canada&column=country&delimiter=auto&header=true&ignore_case=true&ignore_spacing=true&unmatched=keep&fuzzy_threshold=85&output=csv`

---

## About this tool

Category Canonicalize cleans categorical columns when the same value appears under several spellings, abbreviations, capitalization styles, or whitespace variants. Paste a CSV/TSV table or a one-value-per-line list, supply a mapping such as `USA|U.S.A.|us => United States`, and the tool rewrites only the selected column(s).

Use the suggestions output as a review pass: it lists values not covered by the mapping, how often they occur, and the closest canonical value. Accept the suggestions you trust by adding them to the mapping, then rerun to produce the final table. All matching is deterministic and based on the vocabulary you provide; this is for controlled normalization, not unsupervised clustering.

### Worked example

Input data:

```csv
country,n
USA,1
u.s.a.,2
Canadaa,3
Brazil,4
```

Mapping:

```text
USA|U.S.A.|us|united states => United States
Canada|CAN => Canada
```

With `column = country`, `header = true`, and `output = csv`, the USA variants become `United States`, canonical `Canada` stays canonical, and uncovered `Canadaa`/`Brazil` remain available for review or fuzzy handling.

## Limits and edge cases

- Input is capped at 2 MB and mapping text at 200 KB so browser runs stay responsive.
- The mapping is explicit: a bare line declares an accepted canonical, while `variant => canonical` rewrites variants to that value.
- Matching can ignore case and collapse whitespace; punctuation is not stripped unless you list that variant.
- Fuzzy matching compares unmatched values to supplied canonicals with an edit-distance ratio. It is a suggestion aid, not a semantic model.
- Header rows are never rewritten. Select multiple columns with comma-separated header names or 1-based indexes.

## FAQ

<details>
<summary>Can it discover clusters without a mapping?</summary>

No. This tool applies a supplied vocabulary and suggests the nearest supplied canonical for uncovered values. Use it when you already know the allowed labels and want an auditable cleanup pass.

</details>

<details>
<summary>How do I review fuzzy matches before changing the table?</summary>

Choose the `suggestions` output. It returns a CSV with each uncovered value, its count, the nearest canonical, and the similarity score. Add accepted rows to your mapping and rerun, or switch unmatched values to `fuzzy` once the threshold is conservative enough.

</details>

<details>
<summary>What mapping separators are accepted?</summary>

Use `=>`, `->`, `=`, a tab, a comma, or a semicolon between variants and canonical values. Use `|` to list several variants for the same canonical, for example `NY|N.Y.|new york => New York`.

</details>

<details>
<summary>What happens to values not covered by the mapping?</summary>

Pick the policy that fits your workflow: keep originals, blank them, stop with an error, or apply the closest fuzzy suggestion when it reaches the threshold.

</details>

## Related tools

- [Absolute value, sign, or negation for a whole column](https://gizza.ai/tools/absolute-value-transformer/): Paste a column of numbers and apply absolute value, sign extraction (-1/0/1), sign flipping, or force-negative to every value at once, with rounding and an audit table.
- [Adjacency Matrix Converter](https://gizza.ai/tools/adjacency-matrix-converter/): Convert a graph between edge list, adjacency matrix, and incidence matrix — directed or undirected, weighted or not. Free, private, runs in your browser.
- [Amazon Order Analyzer](https://gizza.ai/tools/amazon-order-analyzer/): Paste an Amazon order-history CSV export to summarize total spend by month, top items, and category breakdowns. Browser-only, private, with Markdown or JSON output.
- [ARFF Converter](https://gizza.ai/tools/arff-converter/): Convert Weka ARFF datasets to CSV and CSV tables back to ARFF locally — nominal attributes, numeric types, dates, sparse rows, missing values, and type rows.
- [Avro to JSON Converter](https://gizza.ai/tools/avro-to-json/): Decode Apache Avro Object Container Files (.avro / OCF) to JSON, NDJSON, or the embedded schema — no .avsc needed, free and private in your browser.