cfDNAlab 0.9.0

• Adds --trim-to to fcoverage for counting a centered span around each fragment's midpoint. Shorter fragments can be left unchanged or extended to the requested span.

cfDNAlab 0.8.0

Main focus: This release handles the issue where running many jobs with cfdna <command> calls in parallel led to significant increased runtime due to shared-filesystem contention. It does so by introducing the --temp-dir argument for specifying a node-local scratch location for temporary files. The main contention issue was identified to be the many reads of the ref-2bit reference sequence file. By copying it into the temporary local scratch directory before processing, the issue was heavily reduced. Thanks to Anders from GenomeDK for spotting this.

• Adds --temp-dir to commands that create temporary files. This allows temporary copies of the --ref-2bit file, tile files, and other intermediate files to be placed on node-local scratch when running on HPC clusters. When omitted, temporary files remain under the output directory. cfDNAlab does not select $TMPDIR or another environment variable automatically.
• Commands that use --ref-2bit now copy the file into a unique temporary directory for each command call. This reduces shared-filesystem contention when many jobs run in parallel.
• Separates temporary processing files from temporary final-output files. Both directories remain uniquely named and are cleaned up after successful runs, errors, and Ctrl-C. Final outputs are still written to the requested output directory.

cfDNAlab 0.7.0; Py 0.5.0; R 0.5.0

BREAKING CHANGES:

• cfdna ref-kmers gets the --orientation argument which now defaults to both, meaning we count a k-mer with 0.5 for each orientation (forward-oriented and reverse complemented). This changes the counts significantly, as the reverse-complemented motifs now have the same count. The motivation for this change is to make the default cfdna ref-kmers output suitable for reference correction of cfdna ends motif counts, where the right-end motifs are reverse-complemented. This solves #10.
• Reference correction for end motifs now require cfdna ref-kmers --orientation both. Files created with cfdnalab 0.6.0 will fail to be used.

R and Python loaders:

BREAKING CHANGES:

• Reference correction now requires reference k-mer output generated with cfdna ref-kmers --orientation both.
• Reference k-mer outputs created with cfDNAlab 0.6.0 are no longer supported. Regenerate them with cfDNAlab 0.7.0 or newer.

cfDNAlab 0.6.0; Py 0.4.0; R 0.4.0

cfDNAlab 0.6.0

New command:

• Adds cfdna ref-kmers command for counting k-mers in the reference assembly for downstream normalization of k-mer counts.
  • Adds loaders for ref-kmers output in R, Python and Rust.
  • Adds reference k-mers correction to ends output loaders.

BREAKING CHANGES:

• Grouped motifs-file outputs now order motif groups alphabetically by group name.

Other changes:

• Speeds up the window overlap detection algorithm used in lengths and ends when the --by-bed/--by-grouped-bed contain both broad and narrow windows that are nested.
• Adds minimal validation of BED files to catch obviously non-BED formats.
• Optimizes reading and parsing of BED-like files for improved runtime and RAM usage.
• Library: The Rust fcoverage run result now includes grouped group_index.tsv filepaths in output_files() when they are written.
• Library: Adds missing blacklist setters on the Rust LengthsConfig API.

R and Python 0.4.0

• Adds zarr loader for the outputs of cfdna ref-kmers.
• Adds reference correction in the loader for outputs of cfdna ends using the ref-kmers frequencies.

cfDNAlab 0.5.0

BREAKING CHANGES:

• cfdna fcoverage --normalize-by-length is now actually called --normalize-by-length instead of --normalize-by-length-mode, matching the guides and documentation.
• The Rust crate feature cmd_ref_gc_bias has been removed. Enable cmd_gc_bias (on by default) to compile both the gc-bias and ref-gc-bias command APIs.

Other changes:

• Pins the build-time Clang/LLVM conda packages to version 21.x in installation instructions to avoid broken rust-htslib bindings with libclang version 22.
• cfdna fragment-count-weights and cfdna coverage-weights shows progress bar by default in the internal call to cfdna fcoverage.
• CLI runs now log the equivalent full cfdna <COMMAND> <OPTION> command call for reproducibility and transparency.
• The Rust library can render equivalent command calls from exported configs without enabling the cli feature. This adds the RunOptions.log_equivalent_cli field.
• Adds initial output loaders for lengths, fcoverage, ends, and midpoints to the Rust library.
• General feature gating improvements for an improved library experience.

cfDNAlab 0.4.0

BREAKING CHANGES:

• cfdna fcoverage --per-window summary-stats* output TSV columns are renamed and deduplicated.
• For cfdna fcoverage --normalize-by-length, aggregate TSV headers now use fragment_mass instead of coverage for the length-normalized signal columns.

Other changes:

• Allows reading BAM files from URLs via the curl feature in rust-htslib. This adds url as dependency.
• Updates rust-htslib dependency to 1.0.0 and reduces its feature set for fewer dependencies.
• Enables libdeflate-sys for faster BAM reading.
• bam-to-bam and frag-to-bam writes .bam.bai index files alongside the BAM outputs.
• Requires bindgen >=0.69.5, <0.70 to remove issue with 0.69.4 when users don't install with lockfile.
• Adds --locked to install commands in installation instructions.

cfDNAlab 0.3.0

BREAKING CHANGES:

• Major refactor of the rust library. Makes a clearer boundary of what is public/private. While cfDNAlab is primarily a CLI tool, the library side needed a clean up. This does not affect CLI usage.

Other changes:

• Adds --motifs-file to cfdna ends for pre-specifying the motifs to count. This allows counting larger motifs without exploding the memory.
• In cfdna lengths, the max_soft_clips cap is only applied when --clip-mode adjust.
• In cfdna ends, fixes theoretical bug that wrongly filtered fragments when kmer-size was larger than read sequence but reference was used as source.

---

r-cfDNAlab 0.3.0

• Adds support for schema v2 end-motif Zarr stores written by cfdna ends --motifs-file, including outputs where the motif axis contains user-defined motif groups instead of concrete motif labels.
• Adds the common motifs/motif_idxs, groups/group_idxs, and window_idxs selectors to the sparse_counts_matrix() and dense_counts_matrix functions.
• ends: Improves error message when sparse data has no counts.

---

py-cfDNAlab 0.3.0

• Adds support for schema v2 end-motif Zarr stores written by cfdna ends --motifs-file, including outputs where the motif axis contains user-defined motif groups instead of concrete motif labels.
• ends: Improves error message when sparse data has no counts.

py-cfDNAlab 0.2.0, r-cfDNAlab 0.2.0

py-cfDNAlab 0.2.0

This version cleans up the API and introduces read_lengths for reading the output of cfdna lengths.

BREAKING CHANGES:

• Changes windowed end-motif metadata columns to window_idx, chrom,
  start, end, and blacklisted_fraction.
• Renames Python metadata helpers to window_metadata() and
  group_metadata(), and uses motifs_metadata() for end-motif metadata.
• Adds max_blacklisted_fraction filtering to row-based end-motif data frame
  helpers.
• Adds read_lengths() for cfdna lengths TSV outputs, including length-bin
  metadata, counts_array(), and data frame reshaping.
• Adds length-bin selectors with_lengths, with_length_range, and
  length_bin_idxs to length-count outputs, and with_length_range to
  midpoint outputs.
• Adds denominator to length-count data frames so fraction and density
  can be normalized over all bins or only selected bins.
• Removes the internal count_column field from length_bins() output. Wide
  length data frames still preserve the source count column labels.
• Replaces midpoint and end-motif data frame families with mode-aware
  data_frame() methods using plural selectors such as groups, group_idxs,
  window_idxs, motifs, and motif_idxs.
• Replaces rank-dropping array helpers with counts_array(),
  dense_counts_array(), and sparse_counts_matrix().

---

r-cfDNAlab 0.2.0

This version cleans up the API and introduces read_lengths for reading the output of cfdna lengths.

BREAKING CHANGES:

• Renames groups() to group_metadata() to remove the masking with tidyverse.
• Adds window_metadata() as the R window metadata helper and removes the
  windows() helper.
• Standardizes public genomic window metadata columns to window_idx,
  chrom, start, end, and blacklisted_fraction.
• Adds read_lengths() for cfdna lengths TSV outputs, including length-bin
  metadata, matrix/vector getters, and long or wide data frame reshaping.
• Adds row selectors to length_counts_matrix() for windowed and grouped
  length-count outputs.
• Adds length-bin selectors with_lengths, with_length_range, and
  length_bin_idxs to length-count outputs, and with_length_range to
  midpoint outputs.
• Adds denominator to length-count data frames so fraction and density
  can be normalized over all bins or only selected bins.
• Removes the internal count_column field from length_bins() output. Wide
  length data frames still preserve the source count column labels.
• Adds max_blacklisted_fraction filtering to row-based end-motif data frame
  helpers.
• Replaces the R midpoint and end-motif data frame families with
  midpoint_data_frame() and end_motif_data_frame(), using plural selectors
  such as groups, group_idxs, window_idxs, motifs, and motif_idxs.

cfDNAlab 0.2.0

cfDNAlab 0.2.0

BREAKING CHANGES:

The output formats are changed to simplify downstream work in R and python. While the previous NumPy .npy format was easy to load in python, the user had to infer the column names, etc. We are moving towards more self-contained formats for a better and safer experience.

• cfdna lengths now outputs a wide-format Zstandard-compressed TSV (.tsv.zst) file with one row per window/group. This is readable by pandas in Python and fread(cmd = "zstd -dc file.tsv.zst") in R.
• cfdna lengths writes command settings to <prefix>.length_settings.json.
• cfdna lengths adds --decimals to control written count precision.
• cfdna midpoints now outputs profiles as a self-contained Zarr store at <prefix>.midpoint_profiles.zarr.
• cfdna midpoints writes command settings to <prefix>.midpoint_settings.json.
• cfdna ends now outputs dense and sparse motif counts as a self-contained Zarr store at <prefix>.end_motifs.zarr.
• cfdna ends writes command settings to <prefix>.end_settings.json.
• cfdna ref-gc-bias now writes the public reference GC package as <prefix>.ref_gc_package.zarr.
• cfdna gc-bias now writes the public sample correction package as <prefix>.gc_bias_correction.zarr.

Any GC-correction packages previously computed are no longer compatible. Please recompute.

Python and R packages for downstream loading:

While the new .zarr format has many benefits, such as being self-contained and working in both R and Python, it's not the easiest to work with in its raw form. We added both an R package and a Python package with friendly loaders and data frame + array getters.

• Adds the Python cfDNAlab package for loading the .zarr outputs of the CLI tool and extracting data frames, meta data, etc. See the cfDNAlab/py-cfdnalab/ directory.
• Adds the R cfDNAlab package for loading the .zarr outputs of the CLI tool and extracting data frames, meta data, etc. See the cfDNAlab/r-cfdnalab/ directory.

Other changes:

• Adds zarrs=0.23.11 dependency.
• Adds downstream Zarr compatibility checks for Python and R reader packages.
• We no longer expose the former gen_cli_docs binary that is for internal use only.

cfDNAlab 0.1.0

Adds the following public commands:

• cfdna fcoverage
• cfdna lengths
• cfdna ends
• cfdna midpoints
• cfdna gc-bias
• cfdna coverage-weights
• cfdna fragment-count-weights
• cfdna bam-to-bam
• cfdna bam-to-frag
• cfdna frag-to-bam
• cfdna ref-gc-bias

Additional commands are in development and will be added in future releases.