V1.1

[alexmorinvt]

BEELINE v1.1 Release Notes

Breaking Changes

Config files

• Config file format has changed. Config files from v1.0 are not immediately compatible with v1.1. If migrating, configs should be updated, per the following changes:
  • The dataset_dir parameter has been removed.
  • The name fields for datasets and algorithms are replaced by dataset_id / algorithm_id.
  • Each dataset now has a runs list with individual run_id entries.
  • should_run is now a top-level field on each dataset and algorithm entry rather than nested inside params.
  • image specifies the Docker image used for running an algorithm. This enables users to swap multiple image versions without rebuilding or retagging images.
  • scan_run_subdirectories automatically searches for subdirectories of a dataset directory. If runs are not enumerated in the config file, they will be skipped (non-breaking).
  • Datasets may be labelled with an optional nickname parameter for plotting(non-breaking).
• Zenodo dataset version v4 is required. The input data directory structure has changed. Users on earlier versions of BEELINE should continue to use Zenodo dataset version v3.

Data Structure Changes

• The default ground truth network filename is GroundTruthNetwork.csv (previously refNetwork.csv).
• The ground truth network is specified once at the dataset level in config files (previously specified per-run as trueEdges).
• Note: The following changes are specific to the Zenodo datasets
• Curated datasets are now split into separate directories by dropout level (GSD, GSD-q50, GSD-q70), each with a shared GroundTruthNetwork.csv at the dataset directory level.
• Synthetic datasets have an added cell-count subdirectory level (e.g. dyn-BF/dyn-BF-100/dyn-BF-100-1/).

New Features

Runner

• Each algorithm is now implemented as a class inheriting from an abstract Runner base class, replacing the v1.0 function-map pattern.
• BLRunner.py now checks for existing working directories before running and prompts for confirmation before overwriting them.
• scan_run_subdirectories option on dataset entries allows BLRunner.py to auto-discover run subdirectories rather than requiring an explicit runs list.
• A new experiment_id field in output_settings inserts a named path segment in the output directory, allowing multiple experiments to share one output root.

Algorithms

• Added PEARSON (Pearson correlation baseline).
• Added SCSGL and JUMP3.
• SCNS is excluded from this release due to prohibitively long run time. SCNS is still included as a buildable Docker container, and users may manually migrate the SCNS runner code from BEELINE v1.0 if they desire.
• Updated Dockerfiles as needed such that containers build locally as of Docker version 28.5.1 and Ubunutu 24.04.2

Evaluation

• The evaluation subsystem is rewritten as a hierarchy of callable classes (AUPRC, AUROC, EarlyPrecision, etc.), each responsible for loading, computing, and writing its own output.
• Evaluation data now mirrors the dataset config hierarchy and infers grouping from it.

Plotting

• Plotting is rebuilt from 2 files to a full framework: PlotAUPRC, PlotAUROC, PlotEPR, PlotSummaryHeatmap, PlotEPRHeatmap, and shared helpers in plotter.py and _heatmap.py.
• BLPlotter.py now has a proper CLI with --auprc, --auroc, --epr, --summary, --epr-summary, and --all flags.

Utilities

• Moved and upgraded utils/generateExpInputs.py for preprocessing experimental scRNA-seq datasets.
• Moved and upgraded utils/initialize.sh and utils/setupAnacondaVENV.sh
• Moved and upgraded utils/environment.yml for direct conda environment creation.
• Created utils/buildDocs.sh for locally buidling the documentation.

Documentation

• Documentation is built with Sphinx.
• Added a new Reproducing BEELINE Results page with step-by-step instructions for recreating Figures 2 and 4 from Pratapa et al. (2020).

Disclaimer

Portions of this codebase and documentation were prepared with the assistance of Claude Sonnet 4.6, an AI assistant developed by Anthropic. All content has been reviewed and approved by the authors, who take full responsibility for its accuracy.