jianglab-name-standard

Lab-wide file/folder naming standard for imaging platforms used in the Jiang Lab.

This package only governs naming — character set, field count, position semantics. Structural rules (folder layout, file pairing, presence of scan data) live in each platform-specific toolkit (e.g. fusion-toolkit, atomx-toolkit).

Install

pip install git+https://github.com/wuwenrui555/jianglab-name-standard.git

Common conventions

• Field charset: [A-Za-z0-9-] (letters, digits, hyphens only).
• Field separator: _ — never appears inside a field.
• Date: 8-digit YYYYMMDD, must be a real calendar date.
• Errors raise NameValidationError with rule_id / message / hint attributes so consumers can convert to their own violation types.

Web validator (no install): https://wuwenrui555.github.io/jianglab-name-standard/

Fusion CODEX

Rules

• R1 — Study folder name: YYYYMMDD_<user>_<project>_<custom> (4 fields, valid date).
• R2 — Experiment / sample folder name: equals the study name, or <study>_<suffix> where <suffix> is one field of [A-Za-z0-9-].
• R3 — Experiment name total length ≤ 60 characters (Windows MAX_PATH guard for .temp sidecar files).
• R4 — .fpr basename (without extension): each _-separated field uses the R3 charset. Presence-only; no pairing.

Usage

from jianglab_name_standard import FusionRunName, FusionFprName, NameValidationError

# A run = a (study_name, experiment_name) pair. Both are required.
n = FusionRunName(
    study_name="20260409_LKP_UKY_SqTMA",
    experiment_name="20260409_LKP_UKY_SqTMA_slide1",
)
n.date      # "20260409"
n.user      # "LKP"
n.project   # "UKY"
n.custom    # "SqTMA"
n.suffix    # "slide1"   (None when experiment_name == study_name)

# 4-field form (no suffix) — experiment dir shares the study's name.
n = FusionRunName(
    study_name="20260409_LKP_UKY_SqTMA",
    experiment_name="20260409_LKP_UKY_SqTMA",
)
n.suffix    # None

# .fpr filename validation (presence-only, no pairing).
fpr = FusionFprName(basename="260414_JLL_CRCLupus_Titration")
FusionFprName.is_valid("bf 20")  # False (contains space)

# Errors carry a rule_id so platform toolkits can convert to their Violation type.
try:
    FusionRunName(
        study_name="20260413_JLL_LupusCRCTitration",  # only 3 fields
        experiment_name="20260413_JLL_LupusCRCTitration",
    )
except NameValidationError as e:
    e.rule_id   # "R1"
    e.hint      # human-readable fix suggestion

CosMx AtoMx SIP

Rules

• R1 — Run folder name: YYYYMMDD_<user>_<project>_<custom>_<atomx_version> (5 fields, valid date). The 5th field is the AtoMx SIP version literal v<MAJOR>-<MINOR>-<PATCH> (digits only). No nested experiment directories. No length cap (CosMx data lands directly on Linux, not Windows MAX_PATH=260).

AtoMx versions like 2.2.1 are encoded as v2-2-1 since . violates the charset and _ would collide with the field separator.

Usage

from jianglab_name_standard import CosmxRunName, NameValidationError

n = CosmxRunName(run_name="20260211_WW_ACLF_run1_v2-2-1")
n.date            # "20260211"
n.user            # "WW"
n.project         # "ACLF"
n.custom          # "run1"
n.atomx_version   # "v2-2-1"

# Errors carry a rule_id.
try:
    CosmxRunName(run_name="20260211_WW_ACLF_run1_v2.2.1")  # dot in version
except NameValidationError as e:
    e.rule_id   # "R1"
    e.hint      # human-readable fix suggestion