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
¶
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
¶
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
¶
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
¶
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
¶
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