Logging Module (biallelic.logging)

The logging module provides hierarchical logging capabilities for the biallelic analysis pipeline.

Logging utilities for biallelic analysis pipeline.

Provides SimpleLogger and ExtendedLogger classes for hierarchical logging to both files and console output. Supports creating sublogs for different analysis stages.

class biallelic.logging.ExtendedLogger(name: str, path: str, level: int)[source]

Bases: object

Base logger with file and console output handlers.

Creates a logger that writes to both a log file and console output, with consistent formatting and specified logging level.

Attributes:

__name__: Logger name __path__: Directory where log files are written log: Python logging.Logger instance log_file: Path to the log file

Initialize ExtendedLogger with file and stream handlers.

Args:

name: Logger name (used for log file name) path: Directory path for log output level: Logging level (logging.DEBUG, INFO, WARNING, etc.)

class biallelic.logging.SimpleLogger(name: str, path: str, level: int = 20)[source]

Bases: ExtendedLogger

Hierarchical logger with support for child sublogs.

Extends ExtendedLogger to support creating child loggers for different analysis stages. All logs are written to the same directory with automatic file naming.

Attributes:

sublogs: Dictionary of child SimpleLogger instances

Example:
>>> from biallelic.logging import SimpleLogger
>>> logger = SimpleLogger("analysis", "/path/to/logs")
>>> ref_logger = logger.add_log("reference_loading")
>>> ref_logger.log.info("Loading gene annotations")

Initialize SimpleLogger with sublog support.

Args:

name: Logger name (used for log file name) path: Directory path for log output level: Logging level (default: logging.INFO)

add_log(name: str, level: int = 20) → SimpleLogger[source]

Create a child logger for a specific analysis stage.

Args:

name: Name of the sublog (used for log file name) level: Logging level for sublog (default: logging.INFO)

Returns:

SimpleLogger instance for the sublog

Overview

This module provides two logger classes:

  • SimpleLogger: Main logger with support for creating sublogs

  • ExtendedLogger: Low-level logger for detailed logging control

SimpleLogger is recommended for most use cases, while ExtendedLogger provides fine-grained control over logging behavior.

Basic Usage

Creating a logger for your analysis:

from biallelic.logging import SimpleLogger
import logging

# Create main logger
logger = SimpleLogger("my_analysis", "/path/to/logs")

# Log messages
logger.log.info("Starting analysis")
logger.log.debug("Debug information")
logger.log.error("Error message")

# Create sublogs for different analysis stages
stage1_log = logger.add_log("stage1")
stage1_log.log.info("Stage 1 processing")

stage2_log = logger.add_log("stage2", level=logging.DEBUG)
stage2_log.log.debug("Detailed stage 2 information")

Output

SimpleLogger creates two output streams:

  1. Log File: <logs_dir>/<logger_name>.log - Contains all messages at configured level - Includes timestamps and severity

  2. Console Output: stdout/stderr - Shows same messages as log file - Allows real-time monitoring

Configuration

Set logging level when creating logger:

import logging
from biallelic.logging import SimpleLogger

# DEBUG level - most verbose
debug_logger = SimpleLogger("debug", "/logs", level=logging.DEBUG)

# INFO level - standard
info_logger = SimpleLogger("analysis", "/logs", level=logging.INFO)

# WARNING level - only important messages
warn_logger = SimpleLogger("warnings", "/logs", level=logging.WARNING)

Log Format

Log messages include:

  • Timestamp: YYYY-MM-DD HH:MM:SS,mmm

  • Logger Name: Hierarchical logger identifier

  • Level: DEBUG, INFO, WARNING, ERROR, CRITICAL

  • Message: The log message

Example log output:

2025-10-29 12:34:56,789 - my_analysis - INFO - Starting analysis
2025-10-29 12:34:57,123 - my_analysis.stage1 - DEBUG - Processing file 1 of 100
2025-10-29 12:35:02,456 - my_analysis.stage1 - ERROR - Failed to read file: /path/to/file

Advanced Usage

Creating multiple independent analysis stages:

from biallelic.logging import SimpleLogger

# Main analysis logger
main_logger = SimpleLogger("biallelic_run", "/path/to/logs")

# Sub-loggers for each stage
refs_logger = main_logger.add_log("loading_refs")
data_logger = main_logger.add_log("loading_data")
discovery_logger = main_logger.add_log("discovery")
output_logger = main_logger.add_log("output")

# Each produces separate log entries under main logger
refs_logger.log.info("Loaded genes: 20000")
data_logger.log.info("Loaded samples: 500")

See Also