Skip to main content

ClarID-Tools Documentation

This page is the map for the ClarID-Tools documentation. Use it to decide where to start, which command style applies to your setup, and when to use each ID format.

ClarID-Tools is the reference command-line implementation for encoding and decoding subject and biosample identifiers from structured biomedical metadata.

Before You Start​

Pick the command style that matches your setup.

  • If you cloned this repository, run commands from the repository root with bin/clarid-tools.
  • If you installed ClarID-Tools system-wide or with CPAN, run clarid-tools.
  • You can omit --codebook unless you want to use a custom codebook. The packaged default codebook is used automatically.
  • The qrcode subcommand needs qrencode and zbarimg; the Docker image already includes them.

Start Here​

01QuickstartCopy-paste examples for encoding and decoding.02CLI ReferenceAll commands, options, and output modes.03SpecificationThe exact identifier structure and supported fields.04Use CasesBrowsable GDC-derived subject and biosample examples.

What You Can Do​

  • Encode subject and biosample identifiers from structured metadata.
  • Decode human-readable or stub identifiers back into tabular values.
  • Validate YAML codebooks against the bundled JSON Schema.
  • Run single-record, bulk CSV, QR-code, and preprocessing workflows from the CLI.

Choosing an ID Format​

human

Use this when identifiers will be read directly by people in reports, spreadsheets, filenames, or manual review workflows.

stub

Use this when compactness matters more than readability, for example in QR codes, labels, or constrained downstream systems.

Both formats are generated from the same metadata and codebook, so you can encode and decode between structured metadata and IDs consistently.

What This Repository Implements​

The ClarID paper defines the identifier concept and rationale. This repository provides the reference command-line implementation, the codebook/schema validation workflow, and end-to-end examples for subject and biosample identifiers.