.. _api_bi:

Orchestrator Module (biallelic.bi)
==================================

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

.. automodule:: biallelic.bi
   :members:
   :undoc-members:
   :show-inheritance:

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:

.. code-block:: python

    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:

.. code-block:: yaml

    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
--------

- :ref:`manifest`: Complete manifest specification
- :ref:`api_models`: Data model classes
- :ref:`developing`: Extension guide