.. index:: Troubleshooting

.. _troubleshooting:

Troubleshooting Guide
=====================

This guide helps you diagnose and solve common issues when using biallelic_py.

Installation Issues
===================

ModuleNotFoundError: No module named 'biallelic'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Python cannot find the biallelic_py package

**Solutions**:

1. **Ensure package is installed**:

   .. code-block:: bash

       # Install in development mode
       pip install -e .

2. **Check Python path**:

   .. code-block:: bash

       # Verify biallelic is installed
       python -c "import biallelic; print(biallelic.__file__)"

3. **Check virtual environment**:

   .. code-block:: bash

       # Ensure you're in the right virtual environment
       which python
       python --version

4. **Reinstall package**:

   .. code-block:: bash

       pip uninstall biallelic_py
       pip install -e .

ImportError: cannot import name 'X' from 'biallelic'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Module import failed for a specific class or function

**Causes and solutions**:

1. **Check class/function exists**:

   .. code-block:: python

       # Verify the name exists
       from biallelic import models
       print(dir(models))

2. **Check spelling** - Common mistakes:

   - `Abberations` (wrong) → `Aberrations` (correct)
   - `SimpleLoger` (wrong) → `SimpleLogger` (correct)
   - `Gender.MALE` (wrong) → `Gender.Male` (correct)

3. **Update your code** to match actual names from :ref:`api`

Manifest Issues
===============

"sample_donors reference not found"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Analysis fails with error about missing sample_donors

**Causes**:

1. Missing ``sample_donors`` in ``ref`` section of manifest
2. File path to sample_donors is incorrect
3. File doesn't contain required columns

**Solution**:

Ensure manifest has valid ``ref`` section:

.. code-block:: yaml

    ref:
      genes:
        path: path/to/genes.bed.gz
        format_driver: bed
      sample_donors:                    # ← MUST BE PRESENT
        path: path/to/samples.txt
        format_driver: maf              # Must match file format

**Verification**:

.. code-block:: bash

    # Check file exists
    ls -la path/to/samples.txt

    # Verify it's readable
    zcat path/to/samples.txt | head -5

"genes reference not found"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Gene annotations cannot be loaded

**Causes**:

1. ``genes`` entry missing from ``ref`` section
2. File path is incorrect
3. File doesn't exist or isn't readable
4. File format doesn't match specified driver

**Solution**:

Check ``ref`` section has genes entry:

.. code-block:: yaml

    ref:
      genes:                            # ← MUST BE PRESENT
        path: path/to/genes.bed.gz
        format_driver: bed              # Must match file format
      sample_donors:
        path: path/to/samples.txt
        format_driver: maf

**Verification**:

.. code-block:: bash

    # Check file exists and is readable
    ls -lah path/to/genes.bed.gz

    # Verify format (should be BED: chrom, start, end, name, ...)
    zcat path/to/genes.bed.gz | head -3

"Driver XXX doesn't implement YYY"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Unknown data format driver or missing method

**Causes**:

1. Driver name misspelled
2. Driver doesn't support requested data type
3. Driver module not found

**Example error**:

.. code-block:: text

    Driver vcf doesn't implement snv

**Solution**:

Check the manifest specifies a supported driver:

.. code-block:: yaml

    input:
      - path: variants.maf.gz
        type: snv
        format_driver: maf              # ← Correct driver
        extra_driver_args: {}

**List available drivers**:

.. code-block:: python

    from biallelic.misc import get_modules_names
    import biallelic.drivers
    drivers = get_modules_names(biallelic.drivers)
    print("Available drivers:", drivers)

**Check what a driver supports**:

.. code-block:: bash

    # Look at driver source code
    grep "^def " biallelic/drivers/maf.py

File Path Issues
================

"File not found" error
~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Input or reference file cannot be found

**Common causes**:

1. File path is incorrect
2. Relative path is wrong (should be relative to manifest directory)
3. File doesn't exist
4. File is in a different location than expected

**Solution**:

1. **Use absolute paths** for testing:

   .. code-block:: yaml

       input:
         - path: /absolute/path/to/file.maf.gz
           type: snv
           format_driver: maf

2. **Check relative paths** - they're relative to manifest directory:

   .. code-block:: bash

       # Manifest structure
       project/
       ├── manifest.yaml
       ├── data/
       │   └── variants.maf.gz
       └── ref/
           └── genes.bed.gz

   .. code-block:: yaml

       # manifest.yaml uses relative paths
       input:
         - path: data/variants.maf.gz    # ← Relative to manifest
           type: snv
           format_driver: maf

3. **Verify file exists**:

   .. code-block:: bash

       ls -lah /path/to/file

4. **Check file permissions**:

   .. code-block:: bash

       # File should be readable
       test -r /path/to/file && echo "readable"

5. **Check path separators** on Windows:

   .. code-block:: yaml

       # Windows paths should use forward slashes or double backslashes
       path: data\variants.maf.gz        # Wrong
       path: data/variants.maf.gz        # Correct
       path: "data\\variants.maf.gz"     # Also correct

"Permission denied" error
~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Cannot read file due to permissions

**Solution**:

.. code-block:: bash

    # Check file permissions
    ls -l /path/to/file

    # Add read permission if needed
    chmod +r /path/to/file

    # Or for directory
    chmod +rx /path/to/directory

Data Format Issues
==================

"Empty reference_map"
~~~~~~~~~~~~~~~~~~~~~

**Problem**: Reference data loaded but appears empty

**Causes**:

1. Reference file doesn't have expected data
2. Driver isn't parsing file correctly
3. File format doesn't match specified driver

**Solution**:

Test the driver directly:

.. code-block:: python

    from biallelic.drivers.bed import genes
    from biallelic.logging import SimpleLogger

    logger = SimpleLogger("test", "/tmp/logs")

    # Try loading genes file
    genes_df = genes("path/to/genes.bed.gz", logger)
    print(f"Loaded {len(genes_df)} genes")
    print(genes_df.head())

Invalid data format in file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Driver can't parse file due to format issues

**Example error**:

.. code-block:: text

    ValueError: invalid literal for int(): 'not_a_number'

**Causes**:

1. File format doesn't match driver expectations
2. File is corrupted
3. Wrong file type specified in manifest

**Solution**:

1. **Inspect file manually**:

   .. code-block:: bash

       # View first few lines
       zcat file.txt.gz | head -5

       # Check delimiter
       zcat file.txt.gz | head -1 | od -c

2. **Compare with example**:

   Check test data files for correct format:

   .. code-block:: bash

       ls test/data/

3. **Use correct driver**:

   .. code-block:: yaml

       # Verify driver matches file type
       input:
         - path: file.maf.gz
           type: snv
           format_driver: maf          # ← Matches file type

Analysis Issues
===============

"Analysis module not found"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Unknown discovery analysis name

**Causes**:

1. Analysis name misspelled
2. Analysis module doesn't exist
3. Module is in wrong location

**Solution**:

List available analyses:

.. code-block:: python

    from biallelic.misc import get_modules_names
    import biallelic.discovery
    analyses = get_modules_names(biallelic.discovery)
    print("Available analyses:", analyses)

Correct manifest to use existing analysis:

.. code-block:: yaml

    analyses:
      - name: annotate_snv            # ← Must exist
      - name: summary_biallelic

Memory Issues
=============

"MemoryError" or "Killed" during analysis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Analysis runs out of memory

**Causes**:

1. Dataset is very large
2. All aberrations loaded into memory at once
3. Large DataFrame operations

**Solutions**:

1. **Process subset of data**:

   .. code-block:: yaml

       # Test with single chromosome first
       input:
         - path: variants_chr1.maf.gz
           type: snv
           format_driver: maf

2. **Check available memory**:

   .. code-block:: bash

       # macOS
       vm_stat | grep "Pages free"

       # Linux
       free -h

3. **Process by chromosome**:

   Create separate manifests for each chromosome

4. **Filter input data**:

   Pre-filter large files to essential samples/regions

Performance Issues
==================

"Analysis takes too long"
~~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Analysis runs slowly

**Causes**:

1. Large input files
2. Complex discovery algorithms
3. Inefficient file format (uncompressed vs compressed)

**Solutions**:

1. **Use compressed files**:

   .. code-block:: yaml

       # Good - compressed
       path: variants.maf.gz

       # Slow - uncompressed
       path: variants.maf

2. **Check file I/O**:

   Monitor disk usage during analysis:

   .. code-block:: bash

       # macOS
       iostat -w 1

       # Linux
       iotop

3. **Profile analysis**:

   See :ref:`developing` for profiling instructions

4. **Reduce data size**:

   Test with subset before full analysis:

   .. code-block:: bash

       # Sample 10% of lines
       zcat variants.maf.gz | head -10000 | gzip > sample.maf.gz

Logging and Debugging
=====================

"ERROR: Analysis failed"
~~~~~~~~~~~~~~~~~~~~~~~~

**Problem**: Error message is generic and unhelpful

**Solution**:

1. **Check log files**:

   .. code-block:: bash

       cat logs/bi.log
       tail -f logs/bi.log  # Watch logs in real-time

2. **Enable debug logging**:

   .. code-block:: python

       import logging
       from biallelic.logging import SimpleLogger

       # Create logger with DEBUG level
       logger = SimpleLogger("debug_analysis", "/path/to/logs", level=logging.DEBUG)
       logger.log.debug("Detailed information now in logs")

3. **Run with minimal input**:

   Test with small subset to isolate issue:

   .. code-block:: bash

       # Run with single sample
       biallelic_inactivation manifest_single_sample.yaml

Getting More Help
=================

If you can't find a solution here:

1. **Check the source code**:

   - Read docstrings: :ref:`api`
   - Check examples in test data: ``test/data/``

2. **Review documentation**:

   - :ref:`manifest` - Manifest specification
   - :ref:`developing` - Development guide
   - :ref:`architecture` - System design

3. **Inspect error logs**:

   .. code-block:: bash

       # Full error with traceback
       cat logs/bi.log | grep -A 10 "ERROR"

4. **Create minimal test case**:

   Try to reproduce error with simplest possible input

5. **Check Python version**:

   .. code-block:: bash

       python --version
       # Should be 3.9 or higher

Common Mistakes
===============

1. **YAML syntax errors**:

   .. code-block:: yaml

       # Wrong - colon followed by no space
       title:Test
       # Correct
       title: Test

       # Wrong - inconsistent indentation
       ref:
       genes:
           path: file.bed
       # Correct
       ref:
         genes:
           path: file.bed

2. **Missing required fields**:

   .. code-block:: yaml

       # Wrong - missing format_driver
       input:
         - path: file.maf
           type: snv
       # Correct
       input:
         - path: file.maf.gz
           type: snv
           format_driver: maf

3. **Wrong data type**:

   .. code-block:: yaml

       # Wrong - type unknown
       input:
         - path: file.maf
           type: mutation              # Wrong - use 'snv'
       # Correct
       input:
         - path: file.maf.gz
           type: snv

4. **Not providing absolute or relative path**:

   All file paths must be either absolute or relative to manifest directory

5. **Using spaces in paths**:

   .. code-block:: yaml

       # Works but safer to quote
       path: my file.maf.gz            # Risky
       path: "my file.maf.gz"          # Better
       path: my_file.maf.gz            # Best

See Also
~~~~~~~~

- :ref:`developing`: Development and debugging guide
- :ref:`manifest`: Complete manifest specification
- :ref:`architecture`: System architecture and components