Command line

inspect is the one that stands alone: it takes files rather than a pipeline, and there is nothing to write before running it. The other four take the pipeline file as their last argument and default to pipeline.py in the current directory. run, audit and methods all check the pipeline first, so check is never a prerequisite — it is the fast way to ask the question on its own.

Every command exits 0 when all is well, 1 on a finding — a dimension mismatch, a failed step, a step that does not repeat — and 2 when it could not look at all, because a file is missing or a pipeline will not import. The difference between 1 and 2 is what lets ligase inspect a b && … mean what it looks like it means.

ligase inspect

The only command that needs no pipeline, and the one to try first on files you already have. It loads each file, says what kind it read it as, and prints every dimension the loader worked out along with where it read each one from — and, given two or more files, compares them exactly as one step’s inputs are compared and prints the diagnostic. Nothing is executed, nothing is cached, and no pipeline.py has to exist.

ligase inspect FILE [FILE ...]

Arguments

Examples

# say what one file is
ligase inspect refs/genome.fasta
 
# and whether two of them agree
ligase inspect refs/genome.fasta aln/sample01.bam
 
# refuse to start a run over files that disagree
ligase inspect refs/genome.fasta aln/*.bam && snakemake

ligase check

What makes the rest of Ligase worth having, and the command a pipeline lives or dies by. It imports your pipeline file, builds the graph from the step signatures, and compares every connection’s dimensions. No step body runs, nothing is computed, and no tool is invoked — it reads file headers only, so it finishes in milliseconds on a pipeline that would take all night.

ligase check [--cache DIR] [pipeline]

Arguments

Options

Examples

# check `pipeline.py` in the current directory
ligase check
 
# check a pipeline somewhere else
ligase check analysis/variants.py

ligase run

Checks the pipeline, then computes whatever is not already known. A step runs when its code, its parameters, its inputs’ contents or one of its tools’ versions has changed, and not otherwise. Independent steps run at the same time.

ligase run [-j N] [--force] [--cache DIR] [--worker [NAME]] [--lease SECONDS] [--replay | --refresh] [pipeline]

Arguments

Options

Examples

# run what is not already cached
ligase run
 
# run up to eight steps at once
ligase run -j 8
 
# recompute everything, cache or no cache
ligase run --force
 
# keep the cache off your home directory
ligase run --cache /scratch/ligase

ligase audit

Answers the opposite question to the cache: not can this be skipped but does this repeat. It runs one step twice more and compares what came out, both as bytes and as what those bytes mean. A step whose bytes move while its result does not is reproducible — the ordinary case for a tool that writes its own command line into its output.

ligase audit [--sample ID] [-j N] [--cache DIR] step [pipeline]

Arguments

Options

Examples

# run `align` twice more and compare
ligase audit align
 
# audit one sample's node only
ligase audit align --sample SRR8525904

ligase methods

Writes the paragraph you put in a paper: every tool at the version it actually ran at, every parameter as it was hashed, every reference by accession and checksum, and the works to cite. --bundle packages it so somebody else can check the results, and --verify is that check.

ligase methods [--bundle DIR] [--thin] [--verify DIR] [-j N] [--cache DIR] [pipeline]

Arguments

Options

Examples

# print the methods paragraph and the reference list
ligase methods
 
# write a reproducibility bundle
ligase methods --bundle paper/bundle
 
# check a bundle against this machine
ligase methods --verify paper/bundle

ligase store

ligase store {status,push,pull} ...

Ligase keeps step outputs, canonical forms and recorded response bodies in a content-addressed store. A local store is always the first tier; a second one — a bucket, or a directory on a shared mount — can sit behind it, consulted on a miss and written through on a put, so a lab computes something once between them. Name it with LIGASE_STORE or a [store] table in ligase.toml.

ligase store status

ligase store status [--cache DIR]

Print the store this project is configured to use, where that setting was read from, whether this build of Ligase can open it at all, and how much the local tier holds that the remote does not. The last number is a difference between two stores, so it is exact up to a bound and sampled above it; the output says which it is.

Options

ligase store push

ligase store push [--cache DIR]

Write every object and index row in the local tier that the remote does not hold. A run writes through as it goes, so this is for making up a push that did not happen — a run with the store unreachable, or a store configured after the fact.

Options

ligase store pull

ligase store pull [--cache DIR]

Fetch what the local index refers to and the local tier lacks, verifying each object against the name it was asked for. This moves what THIS cache already knows about, so on a machine with no index yet there is nothing to pull: use ligase run, which is what works out which objects the pipeline needs.

Options