# Redactor Commands The `dicom-dre redactor` command group provides free-text redaction operations for description fields. It replaces tokens absent from the allowlist with a redaction marker. It redacts dates, times, emails, URLs, and hexadecimal numbers regardless of the allowlist; use `--preserve-dates` to keep date and time values intact, as required for HIPAA limited datasets. See [Text Redaction](../concepts/text-redaction.md) for the underlying model. :::{important} These commands are intended for short, semi-structured description fields such as `SeriesDescription` and `StudyDescription`, where the distinct values are overwhelmingly derived from structured fields in the source PACS and a finite allowlist covers the legitimate vocabulary. Do not use them on paragraphs of text, general clinical notes, report bodies, or other entirely free-form fields with no discernible pattern; the allowlist model cannot reliably de-identify unbounded prose. ::: ```bash dicom-dre redactor [OPTIONS] COMMAND [ARGS]... ``` Commands: - `redact`: Redact free text from an input CSV and write the result. - `quality-check`: Preview redaction of a CSV of free text side by side. - `show-tokens`: Extract and display all unique tokens from an input. - `allow-token`: Add one or more tokens to the allowlist file. ## redact Redact free text from an input CSV and write the result to an output CSV. The command treats every cell of every row as an independent piece of text; it requires no header row, and the column layout does not matter. The output CSV mirrors the input, with tokens absent from the allowlist replaced by a redaction marker. ```bash dicom-dre redactor redact [OPTIONS] ``` **Options:** - `--track-redacted`: Also write the distinct tokens that were redacted. - `--lowercase`: Lowercase tracked redacted tokens so entries differing only by case are not duplicated. Applies to the `_redacted_tokens.csv` output. - `--allowlist TEXT`: Allowlist filename (for example `default.csv`) or absolute path to an allowlist CSV. Default: `default.csv`. - `--preserve-dates`: Keep dates and times in text, for HIPAA limited datasets. - `--input TEXT`: Path to the input CSV file. Default: `input.csv`. - `--output TEXT`: Path to the output CSV file. Default: `output.csv`. **Examples:** Redact using the default allowlist: ```bash dicom-dre redactor redact --input samples.csv --output redacted.csv ``` Also record which tokens were redacted: ```bash dicom-dre redactor redact --input samples.csv --output redacted.csv --track-redacted ``` Record redacted tokens without case-only duplicates: ```bash dicom-dre redactor redact --input samples.csv --output redacted.csv --track-redacted --lowercase ``` Use a custom allowlist: ```bash dicom-dre redactor redact --input samples.csv --allowlist /path/to/custom_list.csv ``` ## quality-check Display original and redacted text side by side for an input CSV. Use it to identify false positives (valid words being redacted) and false negatives (PHI not being redacted) before relying on the allowlist. ```bash dicom-dre redactor quality-check [OPTIONS] INPUT ``` `INPUT` is a CSV file. The command treats every cell of every row as an independent piece of free text; it requires no header row, and the column layout does not matter. **Options:** - `--allowlist TEXT`: Allowlist filename (for example `default.csv`) or absolute path to an allowlist CSV. Default: `default.csv`. - `--preserve-dates`: Keep dates and times in text, for HIPAA limited datasets. - `--redacted-only`: Only display cells that were redacted. - `--simple`: Only print tokens that would be redacted, sorted and de-duplicated. - `--interactive`: Interactively review and add tokens to the allowlist. **Examples:** Show all text with side-by-side comparison: ```bash dicom-dre redactor quality-check samples.csv ``` Show only cells with redactions: ```bash dicom-dre redactor quality-check samples.csv --redacted-only ``` Print a simple list of redacted tokens: ```bash dicom-dre redactor quality-check samples.csv --simple ``` Review and update the allowlist interactively: ```bash dicom-dre redactor quality-check samples.csv --interactive ``` ### Interactive mode With `--interactive`, the command enters a keyboard-driven review mode that displays each redacted token with its context and allows you to queue additions to the allowlist. For each redacted token, the display shows the row number, the original cell text, the redacted version, the current token, and its status. Keyboard shortcuts: - `a`: Add the token to the allowlist (queue for addition). - `s`: Skip the token (no action). - `q`: Quit review early. - `ESC`: Quit review early. After the review reaches the end of the file or you quit, the command displays a summary of queued additions, prompts for confirmation, and atomically updates the allowlist file once you confirm. ## show-tokens Extract and display all unique tokens from an input CSV. The command splits every cell of every row into tokens; it requires no header row, and the column layout does not matter. It prints the distinct tokens sorted, one per line. Use this to discover candidate terms to add to an allowlist. ```bash dicom-dre redactor show-tokens [OPTIONS] ``` **Options:** - `--input TEXT`: Path to the input CSV file. Default: `input.csv`. **Example:** ```bash dicom-dre redactor show-tokens --input samples.csv ``` ## allow-token Add one or more tokens to the allowlist file. The command strips whitespace from tokens and inserts them in sorted order; it skips duplicates. ```bash dicom-dre redactor allow-token [OPTIONS] TOKENS... ``` `TOKENS` is one or more tokens to add to the allowlist. **Options:** - `--allowlist TEXT`: Allowlist filename (for example `default.csv`) or absolute path to an allowlist CSV. Default: `default.csv`. **Examples:** Add a single token: ```bash dicom-dre redactor allow-token bicuspid ``` Add multiple tokens: ```bash dicom-dre redactor allow-token spoonful bicuspid ``` Add a token to a custom allowlist: ```bash dicom-dre redactor allow-token mytoken --allowlist /path/to/custom_list.csv ```