BioLedger ISA-Tab Guide

bioledger-isatab-schema is a thin but opinionated layer on top of isatools that encodes the requirements BioLedger places on ISA-Tab data beyond what the upstream parser enforces. This guide explains the concepts; for the exact field list on every model, see the API Reference (auto-generated from models.py/manifest.py, so it's always current).

Why a separate repo

ISA-Tab validation in BioLedger is not just a passthrough to isatools. validate_isatab enforces BioLedger-specific requirements: at least one assay with data files, an organism characteristic in sources, assay technology type set, etc. Asset repos must validate against those opinions, or their assets could pass isatools.load and still fail to load in BioLedger.
A standalone package gives asset repos (like bioledger-isatab-library) a way to validate studies without pulling in BioLedger's LLM/application stack.

The manifest companion file

ISA-Tab does not natively support download URLs in data-file columns — the standard expects plain filenames relative to the dataset. To keep the ISA-Tab portable for any standard ISA tool, all download metadata lives in a companion manifest.yaml instead: it is the single source of truth for each file's url and checksum. A user can clone the study, download per the manifest into the study directory, and the ISA-Tab works unchanged. See Manifest / ManifestFile in the API Reference.

At least one of sha256 or md5 is required per file and is verified after download.
md5 exists because large public FASTQ files at ENA/SRA are often published with md5 only.
sra_accession optionally tags a file as originating from an SRA run; when the SRA-Toolkit fast-path is enabled, the downloader uses prefetch + fasterq-dump instead of HTTPS. Because fasterq-dump output differs from ENA's published archive, the manifest md5 is skipped for SRA-fetched files (sha256, if present, is still checked on the fetched bytes).

Downloading remote files

download_manifest() resolves a manifest.yaml into DataFile objects, and download_remote_files() fetches them. Three transport paths:

Segmented HTTPS (default) — parallel Range requests when the server sends Accept-Ranges: bytes; single-stream otherwise. Interrupted downloads resume from the existing partial bytes (re-hashed before appending), with a configurable retry budget.
aria2c — opt-in via BIOLEDGER_USE_ARIA2C=1 for very large files.
SRA-Toolkit — files tagged with sra_accession are fetched with prefetch + fasterq-dump (enabled via the toolkit being on PATH; md5 skipped as noted above).

Checksums and sizes are verified after every download; failures raise with the expected vs actual digest.

Building the study index

python -m bioledger_isatab_schema.index <studies_dir> [output.json]

Walks a library directory, builds an index entry per study, and writes the JSON (stdout when no output path is given) — the same index bioledger study list/download consumes. build_study_index() / write_study_index() are the programmatic equivalents, and manifest_to_datafiles() converts manifest entries to DataFiles.

Loading datasets

load_dataset_from_isatab(path) parses a study directory via isatools into a DataSet of DataFiles. For simple cases there is also load_dataset_from_csv() / parse_csv_samplesheet() — a samplesheet with a sample column (plus organism and file columns whose formats are inferred from extension) becomes a DataSet without authoring full ISA-Tab.

Validation rules

BioLedger validates two things about a study: the ISA-Tab itself (validate_isatab) and, if present, the companion manifest (validate_manifest). Rather than duplicating the exact rule list here, the API Reference renders it straight from each function's docstring, so it can't drift from the code.

Public API

from bioledger_isatab_schema import (
    # validation
    validate_isatab, ISAValidationResult, ISAValidationIssue, Severity,
    # dataset model
    DataSet, DataFile,
    load_dataset_from_isatab, load_dataset_from_csv,
    parse_csv_samplesheet, ParsedCSV,
    # study spec (used by ISAForge agent for generation)
    ISAStudySpec, OntologySourceSpec, SourceSpec, SampleSpec, CharacteristicSpec,
    # manifest (download metadata)
    Manifest, ManifestFile, StudyType, load_manifest, validate_manifest,
    # remote files
    download_remote_files, download_manifest, manifest_to_datafiles,
    # study index
    build_study_index, write_study_index,
)

bioledger-isatab-library (browse) — curated ISA-Tab studies (instances of this schema). CI validates every committed study against validate_isatab/validate_manifest.
bioledger-toolspec-schema (docs) — sibling schema package for tool specs. Independent versioning.
bioledger — the application that consumes both.