# NymTrace Student User Guide

## 1. Install and orient yourself

On macOS, fully extract `NymTrace-1.0.12-macOS-arm64.zip`, then move `NymTrace.app` to Applications. On Windows, fully extract `NymTrace-1.0.12-Windows-x64.zip`, keep `NymTrace.exe` and the `_internal` folder together, and run the EXE. Do not run the program from inside the ZIP or move the EXE by itself. Compare the package against the matching `.sha256` file or `SHA256SUMS.txt` if you need to verify transfer integrity.

The interface has three pages:

1. **Automatic de-identification**: drop source files or folders, let NymTrace discover the categories present in the actual input, select the output directory, and run.
2. **Correspondence-table restore**: use the local correspondence table to restore NymTrace codes in Agent-produced results or to generate a sensitive field list.
3. **Guide**: review the safe workflow and the boundary between local sensitive data and files that may be submitted to an authorized analysis service.

NymTrace does not provide an Agent and does not call a cloud API. Restoration uses only the correspondence table selected on the local computer; it does not need the original source file or a network connection.

## 2. Automatic de-identification

1. Choose **Add files**, **Add folder**, or drag files and folders into the input list. NymTrace starts a read-only local pre-analysis. The interface does not begin with a fixed checklist.
2. Wait for **Options generated**. The page lists only sensitive categories found in this batch, with field, match, and file counts but without patient values. Deterministic headers and rules are evaluated first. A bundled quantized bilingual NER component is loaded lazily only for natural language that rules cannot settle.
3. All discovered categories are selected by default. Keep them selected unless the approved research protocol explicitly requires retaining a category. If you clear one, NymTrace asks for confirmation because `PASS` then applies only to the selected scope. At least one category must be selected.
4. If a surface cannot be fully enumerated, or no safely classifiable category can be pre-listed, NymTrace enables a conservative full check instead of inventing a preset list. It continues with surfaces it can handle safely. Unsupported or unsafe original content is not copied into the analysis folder; an anonymous exclusion reason is recorded.
5. Use a non-sensitive project label. Do not put a patient name or medical-record number in the project name.
6. Choose an output directory. NymTrace creates it if needed. The output must not sit inside the source folder, and the source must not sit inside the output folder.
7. Choose **Start local automatic de-identification**. The selected categories are bound to the source set and its SHA-256 evidence. If a source changes after pre-analysis, NymTrace stops and re-runs analysis instead of applying stale choices. The progress area reports global 0–100%, current file, and stage. Large workbook updates are coalesced to keep the interface responsive.
8. Do not edit, move, or replace source files during processing. Project name, categories, output directory, source list, and window closing are temporarily locked while the delivery is finalized.
9. Read the final gate:

   - `PASS`: the correspondence table and de-identified data folder were created atomically.
   - `PARTIAL`: safe derivatives were created, while files or surfaces that could not be analyzed, safely de-identified, or cleared by residual scanning were excluded. Read `NYMTRACE_EXCLUSIONS.csv` first.
   - `NEEDS_REVIEW`: a legacy task or exceptional manual-review path remains in the local private area and is not released automatically.
   - `BLOCKED`: no safe deliverable could be formed, or a run-level safety condition failed.

If a parser or worker exits unexpectedly, the application leaves the processing state, unlocks the controls, and writes a local diagnostic JSON that excludes source paths, cell contents, and patient identifiers.

## 3. What PASS or PARTIAL produces

```text
NymTrace_<ProjectID>_<Timestamp>/
├── 1_NymTrace_脱敏对应表_禁止上传.xlsx
└── 2_NymTrace_脱敏后完整数据_可分析/
    ├── data/
    ├── README_FIRST.txt
    ├── AGENT_INSTRUCTIONS.md
    ├── NYMTRACE_MANIFEST.json
    ├── QUALITY_REPORT.html
    ├── TRACE_IDS.csv
    ├── NYMTRACE_EXCLUSIONS.csv  only when PARTIAL or exclusions exist
    └── SHA256SUMS.txt
```

### Sensitive correspondence table

The table contains the sensitive category, original value, replacement value, linked case ID, and linked TraceID. A TraceID distinguishes different source locations that share the same visible replacement. This table remains sensitive medical data:

- Keep it only on an authorized computer or institution-approved controlled storage.
- Never upload it to a cloud model, Agent, drive, email, collaboration service, or public chat.
- Never give the complete top-level `NymTrace_<ProjectID>_<Timestamp>` directory to an Agent because it contains this table.
- Values are written as plain text so spreadsheet formulas are not executed.

### De-identified data folder

The `data/` directory contains safely generated de-identified derivatives for supported TXT/Markdown, tabular, DOCX, PDF, image, or DICOM inputs. Its neighboring files explain scope, safety checks, provenance, and integrity. Under `PARTIAL`, `NYMTRACE_EXCLUSIONS.csv` contains only anonymous SourceFileID, format, disposition, and reason code—not an original filename, local path, or patient value. Submit only the entire `2_NymTrace_脱敏后完整数据_可分析` folder to an authorized analysis tool.

## 4. Use with Codex, Claude Code, or another analysis tool

NymTrace neither supplies nor invokes an Agent. When students choose an analysis tool:

1. Confirm that the protocol, ethics approval, institutional policy, data authorization, and cross-border requirements allow that tool.
2. Submit only the de-identified data folder—not the correspondence table, original data, or NymTrace private storage.
3. Include `AGENT_INSTRUCTIONS.md` and require the tool to preserve source identifiers without guessing removed identities.
4. Preserve `NymTrace_TraceID` columns, `[TraceID:...]` markers, and `NT_*` codes in outputs. Do not ask the tool to infer or delete them.
5. Aggregated results may be used directly. If original fields must be reattached locally, bring the result back through the restore workflow below.

De-identification does not itself grant permission to upload. Even after `PASS`, the responsible researcher decides whether external transfer is permitted.

## 5. Restore codes locally through the correspondence table

1. Open **Correspondence-table restore** and select `1_NymTrace_脱敏对应表_禁止上传.xlsx` from the original task. Never upload this file to an Agent.
2. Drop the Agent-produced TXT/Markdown/JSON, CSV/TSV, Excel, DOCX, PDF, image, or DICOM results, or drop a result folder.
3. At the top of the Restore page, choose a restore destination. You may type a directory that does not exist yet. NymTrace creates a timestamped sensitive-result folder there and does not overwrite the table or input results.
4. Confirm the sensitive-data warning and run. TXT, tabular, DOCX, and DICOM metadata produce restored copies. Codes that cannot be matched uniquely stay unchanged and appear in the report.
5. Pixels already redacted in PDF, image, or DICOM outputs are never fabricated or “reconstructed.” Recognized codes and their original values are instead listed in `NymTrace_恢复字段清单_含敏感原值.xlsx`.
6. The destination, restored copies, and field list contain real sensitive information. Keep them on an authorized local system and never send them back to an Agent, cloud service, drive, email, or chat.

One visible date code may correspond to different original dates. Automatic restoration occurs only when a linked TraceID is preserved or the entire table has one unique original. Otherwise the code is retained and reported as ambiguous.

## 6. Common gates

- `BILINGUAL_NER_MODEL_UNAVAILABLE`: the bundled local model is missing, damaged, or fails its integrity check; affected files are withheld and explained under `PARTIAL`.
- `UNSUPPORTED_OR_UNSAFE_FORMAT`: the file is not copied, while other files in the batch continue. Convert it to a supported format and retry separately.
- `PDF_EMBEDDED_ATTACHMENTS`: attachments are removed from the image-derived PDF and reported. If authorized and needed, extract them offline and de-identify them separately.
- `DOCX_EMBEDDED_ACTIVE_OBJECTS`: OLE, ActiveX, or other active objects are not copied. Rebuilt body content may continue under `PARTIAL`.
- `DICOM_HEAD_VOLUME_REQUIRES_DEFACING`: head imaging requires a validated medical-imaging defacing workflow.
- `DICOM_PIXEL_DECODE_FAILED`: pixels cannot be decoded safely. Install an appropriate lossless decoder or convert to a trusted uncompressed DICOM before retrying.
- `SOURCE_CHANGED_DURING_PROCESSING`: a source changed during the run. Close the editing program, restore a stable copy, and run again.
- `INDEPENDENT_RESIDUAL_SCAN_FAILED`: the final independent scan still found a potential sensitive entity. The affected derivative is removed while safe files continue.
- `RESIDUAL_ENTITY_IN_UNIT`: suspicious entities remain after the conservative completion limit. The affected file is withheld and explained.
- `LEGACY_WORKBOOK_LIMITED_SURFACE_ENUMERATION`: readable cells from legacy `.xls/.xlsb` may be rebuilt, but comments, macros, external links, or other hidden surfaces that cannot be guaranteed are excluded and reported under `PARTIAL`.

## 7. Safety boundary

NymTrace is a local de-identification/pseudonymization tool. It is not proof of irreversible anonymization, clinical diagnostic software, or a compliance certification. Faces, handwritten signatures, and complex imaging may be handled as redacted regions without a recoverable textual original; the quality report records such treatment. Keep an institutionally controlled backup of original data and do not use NymTrace as the only archive.