COHORTCROSSWALK / FIELD GUIDE / 1.0.0

Keep the source.
Explain the change.

A practical guide to reviewing categories across releases of open aggregate tables. This guide and its fictional practice files are also available as a free pack. The free pack does not include the application.

You decide the meaning. Matching labels do not establish equivalent categories. CohortCrosswalk records your choices; it does not choose a statistical treatment, join people or records, or certify scientific validity. Use it for nonclinical open aggregate datasets.

1. Open the workspace and get a first result

Extract the entire buyer ZIP into a normal folder. Keep its subfolders together. Open app/index.html in Google Chrome. No terminal, server, account, install or network connection is required. Tested here on Linux x86_64 with Google Chrome 152.0.7977.82. Other browsers and operating systems have not been verified.

Actual empty CohortCrosswalk workspace in Chrome with example and file import controls — Actual running product: choose the example or preview a release file. Files stay in the local browser process.

Click Try the parks example. These are fictional municipal park categories, not evidence about real parks.
Go to Decision ledger and set Show to Needs review. The example begins with 5 / 6 codes resolved, 5 / 6 row-concept observations covered, and 1 data row needing review.
For release 2024, source value "UNK", choose Explicit missing. Enter not recorded as the reason. Click Save decision.
Coverage becomes 6 / 6. Under Review & handoff, click Download complete ZIP. Extract that downloaded ZIP and open report.html.

Parks example filtered to its unresolved UNK decision, showing five of six codes resolved — The review filter exposes the one unfinished decision. The complete export is blocked until it is recorded.

The expected result

Release / source	Your decision	Appended value / status
2023 / 01; 2024 / FREE	Map to free	free / mapped
2023 / 02; 2024 / PAID	Map to paid	paid / mapped
2023 / 99; 2024 / UNK	Explicit missing; not recorded	empty / missing

There are six original rows, four mapped and two explicitly missing. They remain in two release files. The first output row is:

park_id,access_code,access__value,access__status,access__reason
A,01,free,mapped,Practice definition: no entry charge

The examples/parks-2023-expected.csv and parks-2024-expected.csv files contain the full expected cells. Comparison is by parsed CSV cells, not original byte layout.

2. Bring your own release files

Enter a unique Release ID such as 2025. Use 1–48 ASCII letters, numbers, hyphens or underscores, starting with a letter or number. This ID becomes part of your output filenames.
Choose comma for CSV or tab for TSV. Both support double-quoted fields, doubled quotes and quoted multiline cells. Use UTF-8 text, optionally with a leading BOM, and LF or CRLF record endings.
Optionally record a source, URL or license note. URLs stay plain text. Choose the file and click Preview file.
Inspect the header, row count and first ten data records, then choose Accept this release. A failed preview changes nothing. Discard preview leaves the workspace unchanged.
Add the other releases, then create a concept such as access. Select one source column for that concept in every release. Use a new concept for each additional categorical result, up to ten.

A concept creates three new columns. The app refuses names that collide with an original column. Concept and release IDs are case-sensitive. Use distinct names that remain clear to colleagues. Source column names and values are not trimmed or normalized.

To replace/rename a release, remove it and import the new file with its chosen ID. Its decisions are discarded. To rename a concept, remove it and add the replacement. Changing a concept's source column discards the decisions for that concept/release. Adding a new release requires completing its column assignments. Exports stay blocked while setup is incomplete.

3. Record a decision for each exact code

The ledger identifies each decision by release, concept, source column and exact source string. The same literal 01 in another release is a different decision. The source value appears as a JSON string: "" is blank, " " is a space, "\t" is a tab and "a\nb" contains a newline. Quotation marks and escapes are display notation; the original cell is unchanged. Distinct Unicode encodings stay distinct.

Unresolved: keep a question open. It blocks complete export.
Map to category: enter a nonempty target category. Use the reason to document the category definition or rationale, and the decision source note for its provenance.
Explicit missing: enter a reason. The appended value is empty, status is missing, and the reason is preserved. No code, including blank, NA or 99, is assumed missing automatically.

Click Save decision after editing. Other editing and export controls temporarily pause until you save the current card, so partially edited fields cannot slip into an export. To abandon an edit, restore its previous field values and save. Changing a target clears its merge acknowledgement; check it again only after reviewing the new target.

If multiple source codes in one release/concept map to the same target, every contributor needs a reason and the information-loss checkbox. Explain what distinction is being discarded. The same target in different releases is not counted as a within-release merge.

Filter by release, source-text substring or Needs review. The table shows 25 decisions per page. Unresolved source rows lists logical data-record numbers starting at 1 after the header, not physical line numbers; quoted multiline cells still belong to one data record.

“Row-concept observations” counts a row once per concept. With two concepts and three source rows, there are six observations. “Data rows needing review” counts each affected row once in its own release. A 100% number means all observed choices have been recorded, not that they are substantively correct.

Use a prior release as a template

Add the new release and assign its columns. Expand Use another release as a template, choose source and destination, then confirm the reset. All destination decisions become unresolved. Matching exact values receive unapproved action/target/reason suggestions; copy a suggestion into the fields only if appropriate and save it as your own decision. No suggestion grants approval. New categories remain unresolved. The included parks-2025.csv adds SEASONAL, whose meaning the example deliberately does not settle.

4. Review and export a handoff

Completed parks review with complete ZIP and saved-project download controls — Once all observed decisions are resolved, download a complete handoff. Draft reports remain separate.

The complete ZIP contains:

File	Purpose
release-ID.harmonized.csv	Original columns and row order, followed by concept__value, concept__status and concept__reason for each concept. No numerical or date coercion.
crosswalk.csv	Exact source values, decisions, targets, reasons, source notes, row counts and merge acknowledgement.
coverage.csv	Resolved/total codes and covered/total row-concept observations per release and concept.
project.json	Versioned reusable recipe and original input identity; no full raw tables.
report.html	Escaped, script-free human review report; open directly in the browser.
manifest.json	Input identity and SHA-256 of each output except the manifest itself; export timestamp.

Download draft report produces only a clearly marked DRAFT HTML report. It never supplies apparently complete harmonized data.

CSV is a data interchange format. Formula-like strings such as =1+1, +SUM(...) or @name remain unchanged. Do not double-click untrusted data into a spreadsheet. Use that spreadsheet's text/CSV import workflow and explicitly select text columns so it does not evaluate formulas, convert dates or remove leading zeros. Exact spreadsheet behavior varies and was not tested here. Python's CSV reader was used for independent cell verification.

Actual exported parks HTML report showing input hashes and a complete decision ledger — The exported report carries the rationale and byte identities with the reviewed result.

5. Save, close and reopen

Save the current card. Click Save project JSON and keep that download with the unchanged original files. There is no autosave or browser storage.
Open a fresh copy of app/index.html and choose Open saved project.
Reselect each listed input. Both the original filename and SHA-256 must match. Renaming, replacing or changing one byte invalidates the binding. There is no override.
When every input says Verified, click Verify all & restore project. Decisions are restored and coverage is recomputed from the actual files.

If your source is intentionally new, import it as a new release instead and review its decisions afresh, optionally using the explicit template workflow. SHA-256 proves matching bytes, not authenticity, quality or scientific validity. Exports from a restored project reproduce the same data and decisions; the export timestamp changes.

6. Supported envelope and exclusions

Inputs	Up to 10 releases; 5 MiB total original bytes; 20,000 total data rows; 200,000 total source cells including headers; 100 columns per release; 16 KiB per UTF-8 cell.
Decisions	Up to 10 concepts and 5,000 total observed decision identities across all releases/concepts. Metadata notes/reasons max 2 KiB. Target categories max 16 KiB. Project JSON max 4 MiB, including its formatted saved form.
Output	25 MiB cumulative generated file bytes (ZIP headers add a small overhead). Long repeated target strings can reach this bound even when the input fits.
Rejections	Invalid UTF-8, NUL, malformed quotes, ragged rows, empty/duplicate headers, bare CR separators, output-column collisions, unsupported project versions/types and exceeded bounds.
Not supported	XLSX, DTA, SAV, databases, remote retrieval, record joins, fuzzy/AI suggestions, category splitting, numerical conversions, statistics, clinical use or semantic certification.

Import and export run as cancellable local operations. Cancel operation terminates the active job and commits no result. The envelope was exercised on the stated Linux/Chrome host, including 20,000 rows with 5,000 distinct decisions, exact 200,000 cells and exact 5 MiB inputs. It is a size limit, not a timing guarantee on other machines. The combined limits all apply simultaneously.

7. Troubleshooting, privacy and removal

Symptom	Next action
All columns appear in one field	Discard the preview and choose the correct comma/tab delimiter. Check that your export is a UTF-8 CSV/TSV file.
Header, quoting or ragged-row error	Repair a separate copy of the source using a text/CSV-aware editor; keep your original. Every record must have the header's field count. Quote embedded separators and newlines.
Complete ZIP stays disabled	Save the edited card, finish concept column selections, filter Needs review, and check missing reasons and every merge acknowledgement.
Too many distinct decisions	Remove unnecessary concepts/releases or prepare a smaller aggregate subset in a separate tool. No silent truncation is performed.
Filename or SHA-256 mismatch	Find the unchanged named original file. If the source really changed, use a new release; do not treat the old approval as valid.
Unsupported project version	Use the matching product version listed by the project. This release supports schema 1 / app 1.0.0 only and does not guess a migration.
Generated output too large	Use shorter appropriate targets/reasons or a smaller project. Originals remain untouched. Save a valid project checkpoint before closing.
Browser blocks local worker / blank page	Extract the entire ZIP, use the tested Chrome browser and keep app files together. Managed browser policy may block local scripts/workers. No hosted fallback is bundled.
Download seems absent	Check the browser's downloads list and download permissions. Exports create new files; the application cannot overwrite original sources.

Privacy: no account, telemetry, network calls or persistent browser cache is used by the app. Inputs exist in browser memory until the tab closes. Projects contain source category strings, notes, filenames and hashes; complete exports contain full data. Review these before sharing. The screenshot data in this guide is entirely fictional.

Keyboard: Tab moves between links and controls; Enter activates buttons; arrow keys operate native selects; Space toggles checkboxes and details. Focus outlines are visible. The layout was checked at 1440px, 1280px and 390px widths. This is not a claim of accessibility certification.

Actual 390-pixel-wide CohortCrosswalk layout with navigation and example controls — A narrow layout is available; a desktop gives more room for extended review.

Uninstall: close the tab and delete the extracted app folder. Delete downloads separately if no longer needed. Your original input files are not changed or removed. There is no service, account or installer to uninstall.

Keep the source.Explain the change.