Output Layout#

CFTK writes results below <output_dir>/results.

Path	Purpose
`0_power/`	Statistical power analysis outputs and plots.
`provenance/commands.jsonl`	Append-only start and finish records for exact external commands, including return codes and working directories.
`provenance/runs/<run-id>/`	Immutable beginner-run attempt directory containing stage state, config/lock/options identity, exact `software_identity`, doctor and tool reports, an immediate command-ledger mirror, expected output/figure tables, events, and an HTML summary.
`provenance/runs/<run-id>/resource-plan.json`	Resolved total CPU budgets, parallel samples, per-sample threads, estimated peak threads, and detected scheduler allocation by stage.
`provenance/runs/<run-id>/evidence/`	Automatically generated stage/artifact/command TSVs and evidence figures for every terminal `cftk run` attempt. Tables may contain private absolute paths and verbatim commands; do not commit them. The source-checkout helper remains available for historical manifests.
`provenance/runs/<run-id>/run-summary.html`	Core processing/QC summary. When `cftk run --downstream PRESET` is used, it also links the downstream manifest and HTML summary and records the downstream preset/status without merging the two provenance files.
`provenance/analysis-plans/<plan-id>/`	Read-only downstream dependency, input, role, resource, and output plan written by `cftk plan`.
`provenance/analysis-runs/<run-id>/`	Immutable downstream-analysis attempt (schema-v2) containing the selected preset, exact `software_identity`, doctor preflight, artifact/figure contracts, command mirror, resource plan, evidence bundle, and HTML summary.
`provenance/job-plans/<plan-id>/`	Advanced per-sample task scripts, finalizer scripts, and `job-plan.json` written by `cftk plan --execution per-sample`. They are never submitted automatically.
`provenance/job-finalizers/<plan-id>/`	Completion markers written only after the generated cohort finalizer succeeds. `cftk status` checks these markers together with current sample artifacts; it does not replace scheduler status commands.
`provenance/quarantine/<run-id>/`	Preserved partial or damaged stage artifacts moved before a safe retry.
`1_process/1_trimming/`	Trimmed FASTQ files and trimming QC reports.
`1_process/2_alignment/`	Aligned BAM files and alignment metrics.
`1_process/3_markdup/`	Duplicate-marked BAM files, indexes, and `picard_metrics/` target and alignment performance outputs.
`1_process/4_methylation/`	Per-sample CpG methylation calls.
`1_process/5_merged_matrix/`	Merged CpG matrix.
`2_qc/`	QC result tables and figures. The beginner guide includes rendered examples for the fragment-length and methylation-distribution outputs.
`3_differential/`	Differential result tables, PCA intermediates/figures, heatmaps, violin plots, and DMR outputs. Managed differential manifests also record the selected modalities and SHA-256 input-matrix signatures; managed DMR manifests record the selected samples and CpG bedGraph signatures.
`4_fragmentomics/occupancy/`	Occupancy features and `fragmentomics_scope.json` when scoped.
`4_fragmentomics/wps/`	WPS features and `fragmentomics_scope.json` when scoped.
`4_fragmentomics/delfi/`	DELFI-style features and `fragmentomics_scope.json` when scoped.
`4_fragmentomics/end_motif/`	End motif features.
`4_fragmentomics/cleavage/`	Cleavage features.
`4_fragmentomics/_scope/<scope-id>/`	Deterministic targeted-fragmentomics intermediates: clipped panel regions/bins, panel-read BAMs and indexes, and `scope.json`. These files document the panel limitation and are required for resume.
`5_mesa/`	MESA performance, model, and LOOCV outputs.
`report/`	Self-contained HTML report.

Completion Checks#

Launching a command is not enough to mark a workflow complete. Check command exit status, the command provenance ledger, logs, and expected files under the output directory before using downstream steps.

cftk run automates the stage-level subset of these checks. Its expected-outputs.tsv and figures.tsv enumerate the exact required paths, and run.json distinguishes planned, pending, running, complete, complete_with_reporting_error, failed, interrupted, skipped, resumed, and adopted states. Artifact validation checks required file existence and nonempty content; it does not currently calculate checksums for large outputs. Differential stage reuse is stricter: every selected input matrix must match the SHA-256 signature stored in the trusted analysis manifest. The final report links each differential TSV and shows modality context, PCA/violin/heatmap figures, and a lowest-q navigation table without applying a significance threshold.