.. _api_misc:

Utilities Module (biallelic.misc)
=================================

The misc module provides utility functions for file I/O, string manipulation,
module discovery, and visualization support.

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

Overview
--------

This module contains:

- **File I/O**: Transparent handling of regular, gzip, and BGZF files
- **String Utilities**: Formatting and parsing functions
- **Module Discovery**: Dynamic plugin loading for drivers and analyses
- **Visualization**: Color palettes for oncoprint generation
- **Unique IDs**: UID generation for analysis runs

File I/O Functions
-------------------

Transparent file opening with automatic format detection:

.. code-block:: python

    from biallelic.misc import xopen

    # Read text file
    with xopen("data.txt", "r") as f:
        content = f.read()

    # Read gzip-compressed file (auto-detected)
    with xopen("data.txt.gz", "rt") as f:
        lines = f.readlines()

    # Read BGZF-compressed file
    with xopen("data.txt.bgz", "r", bgzip=True) as f:
        data = f.read()

    # Write gzip-compressed file
    with xopen("output.txt.gz", "wt") as f:
        f.write("data")

    # Read from stdin / write to stdout
    with xopen("-", "r") as f:
        user_input = f.read()

String Utilities
----------------

Working with genomic data strings:

.. code-block:: python

    from biallelic.misc import make_ucsc_format, camel_case_split

    # Format genomic coordinates in UCSC style
    ucsc = make_ucsc_format("17", 7577121, 7590863)
    # Returns: "chr17:7577121-7590863"

    # Split camelCase/PascalCase strings
    words = camel_case_split("AberrationType")
    # Returns: ["Aberration", "Type"]

Module Discovery
----------------

Finding and loading driver modules:

.. code-block:: python

    from biallelic.misc import (
        package_modules,
        get_modules_names,
        get_module_method
    )
    import biallelic.drivers

    # Get all module names in package
    all_modules = package_modules(biallelic.drivers)
    # Returns: {"biallelic.drivers.maf", "biallelic.drivers.bed", ...}

    # Get simple module names
    driver_names = get_modules_names(biallelic.drivers)
    # Returns: ["maf", "bed", "simple_segments", ...]

    # Get specific method from module
    snv_loader = get_module_method(
        biallelic.drivers,
        "maf",
        "snv"
    )
    # Returns: callable function for loading SNVs from MAF files

Dynamic Module Loading
~~~~~~~~~~~~~~~~~~~~~~

Advanced usage for custom modules:

.. code-block:: python

    from biallelic.misc import import_module, try_import

    # Load module directly from file path
    my_driver = import_module("my_driver", "/path/to/my_driver.py")
    snv_data = my_driver.snv(file_path, logger, reference_map)

    # Create and import custom module directory
    custom_analysis = try_import("/path/to/analyses", "my_analysis")

Unique ID Generation
--------------------

Generate unique identifiers for analysis runs:

.. code-block:: python

    from biallelic.misc import generate_uid

    # Generate default UID
    uid1 = generate_uid()
    # Returns: "251029123456.789012_A1B2C3D4"

    # Generate with longer random suffix
    uid2 = generate_uid(n=8)
    # Returns: "251029123456.789012_X1Y2Z3W4V5"

Format: ``YYMMDDHHMMss.ffffff_RANDOM``

- **YY**: 2-digit year
- **MM**: 2-digit month
- **DD**: 2-digit day
- **HH**: 2-digit hour
- **MM**: 2-digit minute
- **ss**: 2-digit second
- **ffffff**: 6-digit microsecond
- **RANDOM**: n random alphanumeric characters

Visualization Support
---------------------

Color palettes for genomic visualization:

.. code-block:: python

    from biallelic.misc import color_palettes

    colors = color_palettes()
    # Returns: {"som_snv/som_snv": "#2c4c68", ...}

    # Use in visualization
    hit_color = colors.get("som_loss/som_snv", "#000000")

Available Colors
~~~~~~~~~~~~~~~~

Biallelic hit type to color mapping:

- ``germ_snp/som_loss``: #768b02 (olive green)
- ``som_cn_loh/som_snv``: #8b6a54 (brown)
- ``som_gain_loh/som_snv``: #aa96b1 (purple)
- ``som_loss/methyl``: #d5b28a (tan)
- ``som_loss/som_indel``: #80997f (gray-green)
- ``som_loss/som_loss``: #d56e67 (coral red)
- ``som_loss/som_snv``: #c6c0ac (beige)
- ``som_loss/som_sv``: #5a4b67 (slate purple)
- ``som_snv/som_snv``: #2c4c68 (navy blue)
- ``som_loss/subclonal_snv``: #a05a6e (mauve)

Argparse Utilities
------------------

Custom argparse components:

.. code-block:: python

    from biallelic.misc import SubcommandHelpFormatter, DefaultHelpParser

    # Better subcommand help formatting
    parser = DefaultHelpParser(
        formatter_class=SubcommandHelpFormatter,
        description="Biallelic inactivation analysis"
    )

    # Improved error handling - shows help on error
    parser.error("Invalid option")  # Shows help instead of just error

See Also
--------

- :ref:`api_bi`: Using utilities for orchestration
- :ref:`developing`: Guide for custom drivers
- Python pathlib: https://docs.python.org/3/library/pathlib.html
- Python zipfile: https://docs.python.org/3/library/zipfile.html