Skip to content

Exceptions

Custom exception classes for clear error handling in LZGraphs.

Exception Hierarchy

LZGraphError (base)
├── InputValidationError
│   ├── EmptyDataError
│   ├── MissingColumnError
│   └── InvalidSequenceError
├── GraphConstructionError
│   └── EncodingError
├── GeneDataError
│   ├── NoGeneDataError
│   └── GeneAnnotationError
├── WalkError
│   ├── NoValidPathError
│   ├── MissingNodeError
│   └── MissingEdgeError
├── SerializationError
│   ├── UnsupportedFormatError
│   └── CorruptedFileError
├── BOWError
│   ├── EncodingFunctionMismatchError
│   └── UnfittedBOWError
├── GraphOperationError
│   └── IncompatibleGraphsError
└── MetricsError
    └── InsufficientDataError

Import

from LZGraphs.exceptions import (
    LZGraphError,
    MissingColumnError,
    NoGeneDataError,
    MissingNodeError,
    # ... other exceptions
)

Common Exceptions

MissingColumnError

Raised when a required column is missing.

from LZGraphs.exceptions import MissingColumnError

try:
    graph = AAPLZGraph(data)  # data missing 'cdr3_amino_acid'
except MissingColumnError as e:
    print(f"Missing column: {e.column_name}")
    print(f"Available: {e.available_columns}")

NoGeneDataError

Raised when gene operations are used without gene data.

from LZGraphs.exceptions import NoGeneDataError

try:
    walk, v, j = graph.genomic_random_walk()
except NoGeneDataError as e:
    print(f"Gene data required: {e}")
    # Fall back to regular random walk
    walk = graph.random_walk()

MissingNodeError

Raised when a required node doesn't exist.

from LZGraphs.exceptions import MissingNodeError

try:
    pgen = graph.walk_probability(encoded_sequence)
except MissingNodeError as e:
    print(f"Node not found: {e.node}")
    pgen = 0

EmptyDataError

Raised when input data is empty.

from LZGraphs.exceptions import EmptyDataError

try:
    graph = AAPLZGraph(pd.DataFrame())
except EmptyDataError:
    print("Cannot build graph from empty data")

Error Handling Patterns

Catch All LZGraphs Errors

from LZGraphs.exceptions import LZGraphError

try:
    # Any LZGraphs operation
    graph = AAPLZGraph(data)
    pgen = graph.walk_probability(encoded)
except LZGraphError as e:
    print(f"LZGraphs error: {e}")

Specific Error Handling

from LZGraphs.exceptions import (
    MissingColumnError,
    NoGeneDataError,
    MissingNodeError
)

try:
    graph = AAPLZGraph(data)
    walk, v, j = graph.genomic_random_walk()
except MissingColumnError as e:
    print(f"Data format error: {e}")
except NoGeneDataError:
    print("Using non-genomic random walk")
    walk = graph.random_walk()
except MissingNodeError as e:
    print(f"Unknown pattern: {e.node}")

Batch Processing with Error Handling

results = []
for seq in sequences:
    try:
        encoded = AAPLZGraph.encode_sequence(seq)
        pgen = graph.walk_probability(encoded)
        results.append({'sequence': seq, 'pgen': pgen, 'error': None})
    except MissingNodeError as e:
        results.append({'sequence': seq, 'pgen': 0, 'error': str(e)})
    except Exception as e:
        results.append({'sequence': seq, 'pgen': None, 'error': str(e)})

df = pd.DataFrame(results)
print(f"Successful: {df['error'].isna().sum()}")
print(f"Failed: {df['error'].notna().sum()}")

Full Reference

Custom exceptions for the LZGraphs library.

This module provides a hierarchy of exception classes that give users clear, actionable error messages when something goes wrong. Using specific exception types allows for targeted error handling in downstream code.

Exception Hierarchy

LZGraphError (base) ├── InputValidationError │ ├── EmptyDataError │ ├── MissingColumnError │ └── InvalidSequenceError ├── GraphConstructionError │ └── EncodingError ├── GeneDataError │ ├── NoGeneDataError │ └── GeneAnnotationError ├── WalkError │ ├── NoValidPathError │ └── MissingNodeError ├── SerializationError │ └── UnsupportedFormatError ├── BOWError │ └── EncodingFunctionMismatchError └── GraphOperationError └── IncompatibleGraphsError

Example

from LZGraphs.exceptions import NoGeneDataError, InvalidSequenceError try: ... graph.genomic_random_walk() ... except NoGeneDataError as e: ... print(f"Gene data required: {e}")

LZGraphError

Bases: Exception

Base exception for all LZGraphs errors.

All custom exceptions in this library inherit from this class, allowing users to catch all LZGraphs-related errors with a single except clause if desired.

Example

try: ... # Any LZGraphs operation ... graph = AAPLZGraph(data) ... except LZGraphError as e: ... print(f"LZGraphs error: {e}")

InputValidationError

Bases: LZGraphError

Raised when input data fails validation checks.

This is the base class for all input-related errors. Use more specific subclasses when the error type is known.

EmptyDataError

Bases: InputValidationError

Raised when an operation receives empty data where non-empty is required.

Common causes: - Passing an empty DataFrame to graph constructor - Passing an empty list of sequences to transform - Empty sequence list for diversity metrics

Example

graph = AAPLZGraph(pd.DataFrame()) # Raises EmptyDataError

MissingColumnError

MissingColumnError(column_name: str, available_columns: list = None, message: str = None)

Bases: InputValidationError

Raised when a required column is missing from input DataFrame.

The error message includes: - The name of the missing column - The columns that were found in the DataFrame

Example

df = pd.DataFrame({'wrong_col': ['CASS']}) graph = AAPLZGraph(df) # Raises MissingColumnError

InvalidSequenceError

InvalidSequenceError(sequence: str = None, invalid_chars: str = None, message: str = None)

Bases: InputValidationError

Raised when a sequence contains invalid characters or format.

The error message includes: - The problematic sequence (or portion of it) - The invalid characters found - Expected format information

Example

graph.walk_probability("INVALID123SEQUENCE") # Raises InvalidSequenceError

NoGeneDataError

NoGeneDataError(operation: str = None, message: str = None)

Bases: GeneDataError

Raised when a gene-related operation is attempted on a non-genetic graph.

This occurs when: - Calling genomic_random_walk() on a graph with genetic=False - Accessing gene prediction features without gene data - Attempting gene-based filtering without annotations

Solution

Build the graph with V and J gene columns in the input DataFrame.

Example

graph = AAPLZGraph(df_without_genes) graph.genomic_random_walk() # Raises NoGeneDataError

MissingNodeError

MissingNodeError(node: str = None, message: str = None)

Bases: WalkError

Raised when a required node does not exist in the graph.

This typically occurs when: - Computing walk probability for an unseen sequence - A subpattern in the sequence was never observed during training - Referencing a node that was removed

Example

graph.walk_probability("CASSXYZABC") # Raises MissingNodeError if XYZ never seen

MissingEdgeError

MissingEdgeError(source: str = None, target: str = None, message: str = None)

Bases: WalkError

Raised when a required edge does not exist in the graph.

This occurs when: - A transition between two nodes was never observed - Computing probability for an impossible transition

Example

If 'CA_0' -> 'XY_1' was never seen during training

graph.walk_probability("CAXY...") # May raise MissingEdgeError

See Also