Orchestrator Module (biallelic.bi)

The biallelic.bi module contains the main Aberrations orchestrator class that coordinates the entire analysis pipeline.

Main orchestrator for biallelic inactivation analysis pipeline.

This module contains the Aberrations class which coordinates the entire analysis workflow: loading manifest configuration, invoking data drivers, organizing reference data, and executing discovery analyses.

class biallelic.bi.Aberrations(manifest_file: str, logger)[source]

Bases: object

Orchestrates biallelic inactivation discovery from YAML manifest.

Loads a YAML manifest file that specifies: - Reference datasets (gene annotations, sample metadata) - Input files (genomic data in various formats) - Analyses to run (discovery algorithms to execute)

The class dynamically loads appropriate drivers for each file format and invokes discovery analyses to identify biallelic inactivation patterns.

Attributes:

manifest_file: Path to the YAML manifest file manifest_content: Parsed YAML manifest as dictionary data_path: Directory containing manifest (relative path base) logger: SimpleLogger for logging operations drivers_map: Mapping of driver names to module paths discovery_map: Mapping of analysis names to module paths aberration_list: List of loaded aberration DataFrames reference_map: Reference datasets (gene models, sample metadata) title: Analysis title from manifest

Example:
>>> from biallelic.bi import Aberrations
>>> from biallelic.logging import SimpleLogger
>>> logger = SimpleLogger("analysis", "/path/to/logs")
>>> aberrations = Aberrations("/path/to/manifest.yaml", logger)
>>> aberrations.biallelic_inactivations("/path/to/output")

Initialize Aberrations processor from YAML manifest.

Loads the manifest file, discovers available drivers and analyses, loads reference datasets, and prepares input data.

Args:

manifest_file: Path to YAML manifest configuration file logger: SimpleLogger instance for logging operations

(biallelic.logging.SimpleLogger)

Raises:

FileNotFoundError: If manifest file not found yaml.YAMLError: If manifest file is not valid YAML KeyError: If required fields missing from manifest ValueError: If sample_donors reference not defined (required) Exception: If driver or analysis loading fails

biallelic_inactivations(output_path: str) → None[source]

Execute discovery analyses to identify biallelic inactivations.

Iterates through manifest “analyses” section, invokes each discovery analysis with loaded aberrations and reference data, writing results to output directory.

Args:

output_path: Directory where analysis output files will be written

load_aberration(driver: str, input_type: str, input_path: str, extra_args: Dict, logger) → None[source]

Load aberrations from a single input file using appropriate driver.

Args:

driver: Name of the driver module to use input_type: Type of aberrations in file (snv, indel, scna, etc.) input_path: Path to input file extra_args: Additional arguments to pass to driver function logger: SubLogger for this load operation

load_contents() → None[source]

Load input data files specified in manifest.

Iterates through manifest “input” section, invokes appropriate drivers for each file format, and stores loaded aberration data in aberration_list.

load_refs() → None[source]

Load reference datasets specified in manifest.

Iterates through manifest “ref” section, invokes appropriate drivers for each reference type (genes, sample_donors, etc.), and stores results in reference_map.

Raises:

ValueError: If sample_donors reference is not defined

Overview

The Aberrations class is the central coordinator for biallelic inactivation analysis. It manages:

  1. Manifest Loading: Reads YAML configuration files

  2. Reference Management: Loads gene annotations and sample metadata

  3. Data Input: Processes genomic data from various file formats

  4. Discovery Execution: Runs biallelic hit detection algorithms

  5. Output Generation: Produces results and visualizations

Workflow

A typical analysis workflow:

from biallelic.bi import Aberrations
from biallelic.logging import SimpleLogger

# Initialize logger
logger = SimpleLogger("analysis", "/path/to/logs")

# Create orchestrator with manifest
aberrations = Aberrations("/path/to/manifest.yaml", logger)

# Load reference datasets (genes, sample metadata)
aberrations.load_refs()

# Load input data (SNVs, indels, copy number changes)
aberrations.load_contents()

# Execute discovery analyses
aberrations.biallelic_inactivations("/path/to/output")

Key Attributes

  • manifest_file: Path to YAML manifest configuration

  • manifest_content: Parsed YAML configuration dictionary

  • data_path: Base directory for resolving relative paths

  • logger: SimpleLogger instance for logging

  • drivers_map: Available input format drivers

  • discovery_map: Available discovery analysis modules

  • aberration_list: List of loaded aberration DataFrames

  • reference_map: Reference datasets (genes, sample metadata)

  • title: Analysis title from manifest

Configuration Format

The manifest YAML file should have this structure:

title: Analysis Title
date: 10/29/2025

ref:
  genes:
    path: genes.bed.gz
    format_driver: bed
  sample_donors:
    path: samples.txt
    format_driver: maf

input:
  - path: variants.maf.gz
    type: snv
    format_driver: maf
    extra_driver_args: {}

analyses:
  - name: annotate_snv
  - name: summary_biallelic

See Also