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:

Ensure package is installed:

# Install in development mode
pip install -e .

Check Python path:

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

Check virtual environment:

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

Reinstall package:

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:

Check class/function exists:

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

Check spelling - Common mistakes:
- Abberations (wrong) → Aberrations (correct)
- SimpleLoger (wrong) → SimpleLogger (correct)
- Gender.MALE (wrong) → Gender.Male (correct)
Update your code to match actual names from API Reference

Manifest Issues¶

“sample_donors reference not found”¶

Problem: Analysis fails with error about missing sample_donors

Causes:

Missing sample_donors in ref section of manifest
File path to sample_donors is incorrect
File doesn’t contain required columns

Solution:

Ensure manifest has valid ref section:

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:

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

genes entry missing from ref section
File path is incorrect
File doesn’t exist or isn’t readable
File format doesn’t match specified driver

Solution:

Check ref section has genes entry:

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:

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

Driver name misspelled
Driver doesn’t support requested data type
Driver module not found

Example error:

Driver vcf doesn't implement snv

Solution:

Check the manifest specifies a supported driver:

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

List available drivers:

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:

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

File path is incorrect
Relative path is wrong (should be relative to manifest directory)
File doesn’t exist
File is in a different location than expected

Solution:

Use absolute paths for testing:

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

Check relative paths - they’re relative to manifest directory:

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

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

Verify file exists:
```
ls -lah /path/to/file
```

Check file permissions:

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

Check path separators on Windows:

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

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

Reference file doesn’t have expected data
Driver isn’t parsing file correctly
File format doesn’t match specified driver

Solution:

Test the driver directly:

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:

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

Causes:

File format doesn’t match driver expectations
File is corrupted
Wrong file type specified in manifest

Solution:

Inspect file manually:

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

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

Compare with example:

Check test data files for correct format:
```
ls test/data/
```

Use correct driver:

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

Analysis name misspelled
Analysis module doesn’t exist
Module is in wrong location

Solution:

List available analyses:

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:

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

Memory Issues¶

“MemoryError” or “Killed” during analysis¶

Problem: Analysis runs out of memory

Causes:

Dataset is very large
All aberrations loaded into memory at once
Large DataFrame operations

Solutions:

Process subset of data:

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

Check available memory:

# macOS
vm_stat | grep "Pages free"

# Linux
free -h

Process by chromosome:

Create separate manifests for each chromosome
Filter input data:

Pre-filter large files to essential samples/regions

Performance Issues¶

“Analysis takes too long”¶

Problem: Analysis runs slowly

Causes:

Large input files
Complex discovery algorithms
Inefficient file format (uncompressed vs compressed)

Solutions:

Use compressed files:

# Good - compressed
path: variants.maf.gz

# Slow - uncompressed
path: variants.maf

Check file I/O:

Monitor disk usage during analysis:
```
# macOS
iostat -w 1

# Linux
iotop
```
Profile analysis:

See Development Guide for profiling instructions

Reduce data size:

Test with subset before full analysis:

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

Check log files:

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

Enable debug logging:

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

Run with minimal input:

Test with small subset to isolate issue:

# Run with single sample
biallelic_inactivation manifest_single_sample.yaml

Getting More Help¶

If you can’t find a solution here:

Check the source code:
- Read docstrings: API Reference
- Check examples in test data: test/data/
Review documentation:
- Manifest Format Specification - Manifest specification
- Development Guide - Development guide
- Architecture Guide - System design

Inspect error logs:

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

Create minimal test case:

Try to reproduce error with simplest possible input

Check Python version:

python --version
# Should be 3.9 or higher

Common Mistakes¶

YAML syntax errors:

# 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

Missing required fields:

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

Wrong data type:

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

Not providing absolute or relative path:

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

Using spaces in paths:

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

Troubleshooting Guide¶

Installation Issues¶

ModuleNotFoundError: No module named ‘biallelic’¶

ImportError: cannot import name ‘X’ from ‘biallelic’¶

Manifest Issues¶

“sample_donors reference not found”¶

“genes reference not found”¶

“Driver XXX doesn’t implement YYY”¶

File Path Issues¶

“File not found” error¶

“Permission denied” error¶

Data Format Issues¶

“Empty reference_map”¶

Invalid data format in file¶

Analysis Issues¶

“Analysis module not found”¶

Memory Issues¶

“MemoryError” or “Killed” during analysis¶

Performance Issues¶

“Analysis takes too long”¶

Logging and Debugging¶

“ERROR: Analysis failed”¶

Getting More Help¶

Common Mistakes¶

See Also¶

Table of Contents

Previous topic

This Page