Exceptions

All basanos exceptions inherit from BasanosError, so callers can catch the base class or a specific subclass as needed.

BasanosError

BasanosError

Bases: Exception

Base class for all Basanos domain errors.

---

Input-validation errors

ColumnMismatchError

Bases: BasanosError, ValueError

Raised when two DataFrames have different column sets.

Parameters:

Name	Type	Description	Default
prices_columns	list[str]	Columns of the prices DataFrame.	required
mu_columns	list[str]	Columns of the mu DataFrame.	required

Examples:

>>> raise ColumnMismatchError(["A", "B"], ["A", "C"])
Traceback (most recent call last):
    ...
basanos.exceptions.ColumnMismatchError: 'prices' and 'mu' must have identical columns...

prices_columns = prices_columns instance-attribute

mu_columns = mu_columns instance-attribute

__init__(prices_columns: list[str], mu_columns: list[str]) -> None

Initialize with the column lists of the two mismatched DataFrames.

DimensionMismatchError

Bases: BasanosError, ValueError

Raised when vector and matrix dimensions are incompatible.

Parameters:

Name	Type	Description	Default
vector_size	int	Length of the offending vector.	required
matrix_size	int	Expected dimension inferred from the matrix.	required

Examples:

>>> raise DimensionMismatchError(3, 2)
Traceback (most recent call last):
    ...
basanos.exceptions.DimensionMismatchError: Vector length 3 does not match matrix dimension 2.

vector_size = vector_size instance-attribute

matrix_size = matrix_size instance-attribute

__init__(vector_size: int, matrix_size: int) -> None

Initialize with the offending vector and matrix sizes.

ExcessiveNullsError

Bases: BasanosError, ValueError

Raised when an asset column contains too many null values.

Parameters:

Name	Type	Description	Default
asset	str	Name of the offending asset column.	required
null_fraction	float	Observed fraction of null values (0.0 to 1.0).	required
max_fraction	float	Maximum allowed fraction of null values.	required

Examples:

>>> raise ExcessiveNullsError("A", 1.0, 0.9)
Traceback (most recent call last):
    ...
basanos.exceptions.ExcessiveNullsError: Asset 'A' has 100% null values,...

asset = asset instance-attribute

null_fraction = null_fraction instance-attribute

max_fraction = max_fraction instance-attribute

__init__(asset: str, null_fraction: float, max_fraction: float) -> None

Initialize with the asset name and the observed/maximum null fractions.

InsufficientDataError

Bases: BasanosError, ValueError

Raised when there are too few finite entries to perform a computation.

Examples:

>>> raise InsufficientDataError("All diagonal entries are non-finite.")
Traceback (most recent call last):
    ...
basanos.exceptions.InsufficientDataError: All diagonal entries are non-finite.

__init__(detail: str = '') -> None

Initialize with an optional detail message that overrides the default.

MissingDateColumnError

Bases: BasanosError, ValueError

Raised when a required 'date' column is absent from a DataFrame.

Parameters:

Name	Type	Description	Default
frame_name	str	Descriptive name of the frame missing the column (e.g. "prices").	required

Examples:

>>> raise MissingDateColumnError("prices")
Traceback (most recent call last):
    ...
basanos.exceptions.MissingDateColumnError: DataFrame 'prices' is missing the required 'date' column.

frame_name = frame_name instance-attribute

__init__(frame_name: str) -> None

Initialize with the name of the frame that is missing the column.

MonotonicPricesError

Bases: BasanosError, ValueError

Raised when an asset's price series is strictly monotonic.

A monotonic series (all non-decreasing or all non-increasing) has no variance in its return sign, indicating malformed or synthetic data.

Parameters:

Name	Type	Description	Default
asset	str	Name of the offending asset column.	required

Examples:

>>> raise MonotonicPricesError("A")
Traceback (most recent call last):
    ...
basanos.exceptions.MonotonicPricesError: Asset 'A' has monotonic prices...

asset = asset instance-attribute

__init__(asset: str) -> None

Initialize with the name of the asset that has monotonic prices.

NonPositivePricesError

Bases: BasanosError, ValueError

Raised when an asset column contains zero or negative prices.

Log-return computation requires strictly positive prices.

Parameters:

Name	Type	Description	Default
asset	str	Name of the asset with the offending values.	required

Examples:

>>> raise NonPositivePricesError("A")
Traceback (most recent call last):
    ...
basanos.exceptions.NonPositivePricesError: Asset 'A' contains non-positive...

asset = asset instance-attribute

__init__(asset: str) -> None

Initialize with the name of the asset that contains non-positive prices.

NonSquareMatrixError

Bases: BasanosError, ValueError

Raised when a matrix is required to be square but is not.

Parameters:

Name	Type	Description	Default
rows	int	Number of rows in the offending matrix.	required
cols	int	Number of columns in the offending matrix.	required

Examples:

>>> raise NonSquareMatrixError(3, 2)
Traceback (most recent call last):
    ...
basanos.exceptions.NonSquareMatrixError: Matrix must be square, got shape (3, 2).

rows = rows instance-attribute

cols = cols instance-attribute

__init__(rows: int, cols: int) -> None

Initialize with the offending matrix shape.

ShapeMismatchError

Bases: BasanosError, ValueError

Raised when two DataFrames have incompatible shapes.

Parameters:

Name	Type	Description	Default
prices_shape	tuple[int, int]	Shape of the prices DataFrame.	required
mu_shape	tuple[int, int]	Shape of the mu DataFrame.	required

Examples:

>>> raise ShapeMismatchError((10, 3), (9, 3))
Traceback (most recent call last):
    ...
basanos.exceptions.ShapeMismatchError: 'prices' and 'mu' must have the same shape, got (10, 3) vs (9, 3).

prices_shape = prices_shape instance-attribute

mu_shape = mu_shape instance-attribute

__init__(prices_shape: tuple[int, int], mu_shape: tuple[int, int]) -> None

Initialize with the shapes of the two mismatched DataFrames.

SingularMatrixError

Bases: BasanosError, ValueError

Raised when a matrix is (numerically) singular and cannot be inverted.

This wraps :class:numpy.linalg.LinAlgError to provide domain-specific context.

Examples:

>>> raise SingularMatrixError()
Traceback (most recent call last):
    ...
basanos.exceptions.SingularMatrixError: Matrix is singular and cannot be solved.

__init__(detail: str = '') -> None

Initialize with an optional extra detail string.

---

Model errors

FactorModelError

Bases: BasanosError, ValueError

Raised when :class:~basanos.math.FactorModel arguments fail validation.

Covers shape mismatches between factor loadings, factor covariance, and idiosyncratic variance arrays, non-positive idiosyncratic variances, invalid return matrix dimensionality, and out-of-range factor counts.

Examples:

>>> raise FactorModelError("factor_loadings must be 2-D, got ndim=1.")
Traceback (most recent call last):
    ...
basanos.exceptions.FactorModelError: factor_loadings must be 2-D, got ndim=1.