# Document-Term Matrix Builder

Turn pasted documents into a document-term matrix. Export CSV, TSV, or JSON bag-of-words counts with binary weighting, n-grams, min document frequency, and feature caps.

## Run it

- **CLI:** `gizza tool document-term-matrix "the cat sat
the dog sat
the cat chased the dog"`
- **Web:** https://gizza.ai/tools/document-term-matrix/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/document-term-matrix/tool.json

## Inputs

- `documents` — Documents _(field)_
- `input_format` — Input format _(field)_
- `weighting` — Cell weighting _(field)_
- `case_sensitive` — Case-sensitive terms _(field)_
- `ngram_min` — Minimum n-gram length _(field)_
- `ngram_max` — Maximum n-gram length _(field)_
- `min_df` — Minimum document frequency _(field)_
- `max_features` — Max features (0 = no cap) _(field)_
- `output` — Output format _(field)_
- `include_totals` — Include total kept terms per document _(field)_

## Output

- Matrix (text)

## Query parameters

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

- `documents` — Documents
- `input_format` — Input format
- `weighting` — Cell weighting
- `case_sensitive` — Case-sensitive terms
- `ngram_min` — Minimum n-gram length
- `ngram_max` — Maximum n-gram length
- `min_df` — Minimum document frequency
- `max_features` — Max features (0 = no cap)
- `output` — Output format
- `include_totals` — Include total kept terms per document

Example: `https://gizza.ai/tools/document-term-matrix/?documents=the%20cat%20sat%0Athe%20dog%20sat%0Athe%20cat%20chased%20the%20dog&input_format=auto&weighting=count&case_sensitive=true&ngram_min=1&ngram_max=1&min_df=1&max_features=0&output=csv&include_totals=true`

---

## About this tool

A document-term matrix turns a small text corpus into rows (documents) and columns (terms). Each cell is either a count of how many times a term appears in that document or a binary 0/1 flag that says whether the term is present. This is the classic bag-of-words representation used before clustering, similarity checks, feature inspection, and text-mining experiments.

Paste one document per line, or choose JSON input when your documents contain embedded newlines. The builder tokenizes words locally, lowercases by default, can include adjacent word n-grams, filters rare terms with `min_df`, and caps the vocabulary with `max_features`. Columns are sorted by descending document frequency, then alphabetically for stable copy-paste output.

### Worked example

With these three documents:

```text
the cat sat
the dog sat
the cat chased the dog
```

The default CSV output starts with terms that appear in the most documents, followed by rarer terms:

```csv
document,the,cat,dog,sat,chased,__total_terms
doc_1,1,1,0,1,0,3
doc_2,1,0,1,1,0,3
doc_3,2,1,1,0,1,5
```

Set `weighting` to `binary` when you only need presence/absence. Set `ngram_max` to `2` or `3` to include phrases such as `quick fox` alongside individual words.

### Input notes and limits

The lines format treats each nonblank line as one document. The JSON format requires a JSON array of strings, for example `["first document", "second document"]`. The tool accepts up to 10,000 documents and 5,000 output columns. N-grams are limited to lengths 1 through 3 so the matrix remains browser-friendly.

## FAQ

<details>
<summary>What is the difference between count and binary weighting?</summary>

`count` records term frequency within each document, so repeated words produce values above 1. `binary` records only presence, so every nonzero count becomes 1. Binary matrices are useful for set-style similarity and feature flags.

</details>

<details>
<summary>How are terms tokenized?</summary>

Runs of Unicode letters and digits are words. Apostrophes and hyphens stay inside a word when they are between word characters, so `don't` and `state-of-the-art` remain single terms. Other punctuation separates tokens.

</details>

<details>
<summary>What does min_df do?</summary>

`min_df` is the minimum number of documents a term must appear in to become a column. For example, `min_df = 2` removes words that appear in only one document, which is a quick way to reduce noise in a larger corpus.

</details>

<details>
<summary>Why is there no TF-IDF option?</summary>

This tool focuses on transparent document-term matrices: raw counts and binary presence. TF-IDF changes the scale and interpretation of every cell, so it belongs in a separate weighting-oriented text-vectorizer tool.

</details>

## Related tools

- [Article to EPUB](https://gizza.ai/tools/article-to-epub/): Turn article text or cleaned HTML into a valid EPUB 3 ebook with metadata, chapter splits, and a real table of contents. Runs in your browser.
- [Preview a Bulk File Rename](https://gizza.ai/tools/bulk-file-renamer/): Preview old-to-new filename mappings with find/replace, regex, numbering, case conversion, prefix/suffix, and collision warnings.
- [Citation Generator](https://gizza.ai/tools/citation-generator/): Free APA 7, MLA 9, Chicago and Harvard citation generator — format author, title, year, journal and URL into a correct reference right in your browser.
- [Config Merge Tool](https://gizza.ai/tools/config-merge/): Merge layered JSON, YAML, TOML and .env configuration files with override precedence, array strategy, null deletion and variable substitution.
- [Disk Usage by File Type](https://gizza.ai/tools/disk-usage-by-filetype/): Paste du, find or ls output and get a sorted bar chart of disk usage by file extension or category, with size, share and file count — free and private in your browser.