Tooling & CLI

Copyable examples for the installed console entry points and the public Python API, each checked against the repository's own documentation-example gate.

Source · src/hitop/base/ · src/hitop/suffix/

Prepare the repository once before using the examples below. The bootstrap command creates the local Python environment and installs the HiTOP command-line tools with their dependencies:

scripts/bootstrap_hitop_suffix_tools.sh

Generate base-vocabulary codes

Use hitop-codegen to calculate reproducible checksums and complete local HiTOP codes from the maintained base-vocabulary CSV. The command writes a separate generated file, so the curated source data remains unchanged:

Command

.venv/bin/hitop-codegen \
  src/data/hitop_base_vocabulary.csv \
  /tmp/hitop_base_vocabulary.generated.csv

Output

Generated 162 HiTOP code(s): /tmp/hitop_base_vocabulary.generated.csv

Inspect the first rows to confirm that the generated file contains the expected columns and code format. This quick check is useful before the file enters further validation or ontology-generation steps:

Command

sed -n '1,5p' /tmp/hitop_base_vocabulary.generated.csv

Output

Code;Label;Segment;Segment Level;CheckDigit;HiTOP
01;Conversion;C;0;qy;C001qy
02;Somatization;C;0;17;C00217
03;Malaise;C;0;3z;C0033z
04;Head Pain;C;0;16;C00416

The checksum calculation uses HiTOP as a fixed internal input. It is not configurable and is not written to the generated HiTOP column.

Build manifestation identifiers

Start by converting a canonical organization identifier into a deterministic namespace token. The same ROR identifier will always produce the same token, allowing records from that namespace to be recognized consistently:

Command

.venv/bin/hitop-suffix namespace ROR https://ror.org/00tkfw097

Output

{
  "canonical_identifier": "https://ror.org/00tkfw097",
  "namespace_token": "ROR3J2WQSVQFFIKK"
}

Convert a human-readable manifestation label into the normalized slug required by the suffix schema. This removes formatting ambiguity before the label becomes part of an identifier:

Command

.venv/bin/hitop-suffix slug "Chronic worry"

Output

{
  "slug": "CHRONIC_WORRY"
}

Combine the base concept, manifestation type, namespace token, and normalized slug into one complete manifestation code. Use this step only after each component has been chosen and normalized according to the specification:

Command

.venv/bin/hitop-suffix build-code \
  --hitop U0aB2X \
  --manifestation-type AF \
  --namespace-token ROR3J2WQSVQFFIKK \
  --slug CHRONIC_WORRY

Output

{
  "code": "U0aB2X.M-AF-ROR3J2WQSVQFFIKK-CHRONIC_WORRY"
}

Validate a completed code before storing or exchanging it. A successful result confirms that its structure and individual components satisfy the manifestation-suffix grammar:

Command

.venv/bin/hitop-suffix validate-code \
  U0aB2X.M-AF-ROR3J2WQSVQFFIKK-CHRONIC_WORRY

Output

{
  "errors": [],
  "valid": true
}

Use an intentionally invalid example to understand the CLI's machine-readable error response. The trailing shell clause keeps an interactive documentation session running, although the validator correctly returns exit status 1:

Command

.venv/bin/hitop-suffix validate-code U0aB2X.M-AF-CHRONIC_WORRY || true

Output

The output contains valid: false; the command exit status is 1.

{
  "errors": [
    "Invalid manifestation code: 'U0aB2X.M-AF-CHRONIC_WORRY'."
  ],
  "valid": false
}

Generate a deterministic disambiguator when two local records would otherwise receive the same slug. The contextual identifiers make the resulting suffix reproducible without introducing a manually assigned counter:

Command

.venv/bin/hitop-suffix disambiguator \
  --namespace-identifier https://ror.org/00tkfw097 \
  --hitop U0aB2X \
  --manifestation-type AF \
  --study-id study-a \
  --instrument instrument-x \
  --item-id item-17 \
  --base-slug CHRONIC_WORRY

Output

{
  "basis": "https://ror.org/00tkfw097|u0ab2x|m|af|study-a|instrument-x|item-17",
  "disambiguator": "FPQNQM",
  "slug": "CHRONIC_WORRY_FPQNQM"
}

Python API

Call the public Python API when code generation needs to be embedded in another tool or data pipeline. This example calculates the checksum and local HiTOP code for one CSV-like source row:

Example

from hitop.base.hitop import build_hitop_code

row = {"Segment": "C", "Segment Level": "0", "Code": "01"}
check_digit, local_code = build_hitop_code(row, row_number=2)

print(check_digit)
print(local_code)

Output

qy
C001qy

The suffix functions can also be composed directly in Python instead of invoking the CLI. This example generates the namespace and slug before assembling the complete code:

Example

from hitop.suffix import build_code, generate_namespace_token, slugify

namespace = generate_namespace_token("ROR", "https://ror.org/00tkfw097")
slug = slugify("Chronic worry")

print(
    build_code(
        hitop_base_code="U0aB2X",
        manifestation_type="AF",
        namespace_token=namespace,
        slug=slug,
    )
)

Output

U0aB2X.M-AF-ROR3J2WQSVQFFIKK-CHRONIC_WORRY

Parse an existing manifestation code when downstream software needs access to its individual semantic components. The returned object exposes the base code, type, namespace, and slug separately:

Example

from hitop.suffix import parse_code

parsed = parse_code("U0aB2X.M-AF-ROR3J2WQSVQFFIKK-CHRONIC_WORRY")

print(parsed.hitop_base_code)
print(parsed.manifestation_type)
print(parsed.namespace_token)
print(parsed.slug)

Output

U0aB2X
AF
ROR3J2WQSVQFFIKK
CHRONIC_WORRY

See Build & installation for the release gate commands (local quality gate, ontology conversion, Python matrix) that run these same tools as part of a release, and Validation & quality for how CI runs them.