Skip to content

epymorph.data_shape

Expression of the shape of numpy data whose dimensions can be relative to a simulation context. Provides utilities to declare, check, and adapt data dimensionality.

DataT module-attribute 

DataT = TypeVar('DataT', bound=generic)

The dtype of a numpy array.

Dimensions

Bases: Protocol

Stores the lengths of simulation dimensions which are supported by DataShapes.

See Also

Concrete implementations epymorph.data_shape.CompleteDimensions and epymorph.data_shape.PartialDimensions exist to enable cases where either all or only some of the dimensions are specified.

T abstractmethod property 

T: int

The number of days.

N abstractmethod property 

N: int

The number of nodes.

C abstractmethod property 

C: int

The number of compartments.

E abstractmethod property 

E: int

The number of events.

of staticmethod 

of(
    *,
    T: int | None = None,
    N: int | None = None,
    C: int | None = None,
    E: int | None = None,
) -> Dimensions

Construct either a CompleteDimensions or PartialDimensions instance, depending on whether or not the dimensions are fully specified.

Parameters:

  • T (int | None, default: None ) –

    The number of simulation days, if known.

  • N (int | None, default: None ) –

    The number of geo nodes, if known.

  • C (int | None, default: None ) –

    The number of compartments in the disease model, if known.

  • E (int | None, default: None ) –

    The number of events in the disease model, if known.

Returns:

  • Dimensions –

    A new Dimensions instance (either complete or partial).

PartialDimensions 

PartialDimensions(
    *,
    T: int | None = None,
    N: int | None = None,
    C: int | None = None,
    E: int | None = None,
)

Bases: Dimensions

A Dimensions implementation where some dimensions are unknown. If code accesses an unspecified dimension, DimensionError is raised.

T property 

T

The number of days.

N property 

N

The number of nodes.

C property 

C

The number of compartments.

E property 

E

The number of events.

CompleteDimensions 

CompleteDimensions(*, T: int, N: int, C: int, E: int)

Bases: Dimensions

A Dimensions instance where all dimensions are known.

T property 

T

The number of days.

N property 

N

The number of nodes.

C property 

C

The number of compartments.

E property 

E

The number of events.

DataShape

Bases: ABC

Description of a data attribute's shape relative to the simulation context.

to_tuple abstractmethod 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches abstractmethod 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt abstractmethod 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

Scalar dataclass 

Scalar()

Bases: DataShape

A scalar value.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

Time dataclass 

Time()

Bases: DataShape

An array of at least size T: the number of simulation days.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

Node dataclass 

Node()

Bases: DataShape

An array of size N: the number of simulation nodes.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

NodeAndNode dataclass 

NodeAndNode()

Bases: DataShape

An array of size NxN: a square of the number of simulation nodes.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

NodeAndCompartment dataclass 

NodeAndCompartment()

Bases: DataShape

An array of size NxC: the number of simulation nodes by the number of disease compartments.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

TimeAndNode dataclass 

TimeAndNode()

Bases: DataShape

An array of size at-least-T by exactly-N: T is the number of simulation days and N is the number of simulation nodes.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

NodeAndArbitrary dataclass 

NodeAndArbitrary()

Bases: DataShape

An array of size exactly-N by any dimension: N is the number of geo nodes.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

ArbitraryAndNode dataclass 

ArbitraryAndNode()

Bases: DataShape

An array of size any dimension by exactly-N: N is the number of geo nodes.

to_tuple 

to_tuple(dim: Dimensions) -> tuple[int, ...]

Return a tuple with the lengths of the dimensions in this shape.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

Returns:

  • tuple[int, ...] –

    The absolute size of this shape in the given context. If an axis is of indeterminate length, it is represented as -1.

matches 

matches(dim: Dimensions, value: NDArray) -> bool

Check if the given value matches this shape expression.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray) –

    The numpy array to check.

Returns:

  • bool –

    True if the array's shape matches this shape description in the given context.

adapt 

adapt(
    dim: Dimensions, value: NDArray[DataT]
) -> NDArray[DataT]

Adapt the given value to this shape.

Note that this shape adaptation is more permissive than standard numpy broadcasting.

Parameters:

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • value (NDArray[DataT]) –

    The numpy array to reshape.

Returns:

Raises:

Shapes dataclass 

Shapes(
    Scalar: ClassVar = Scalar(),
    T: ClassVar = Time(),
    N: ClassVar = Node(),
    NxC: ClassVar = NodeAndCompartment(),
    NxN: ClassVar = NodeAndNode(),
    TxN: ClassVar = TimeAndNode(),
    NxA: ClassVar = NodeAndArbitrary(),
    AxN: ClassVar = ArbitraryAndNode(),
)

Static instances for all available shapes.

Data can be in any of these shapes, where:

  • Scalar is a single scalar value
  • T is the number of days
  • N is the number of nodes
  • C is the number of IPM compartments
  • A is any length (arbitrary; this dimension is effectively unchecked)

Scalar class-attribute instance-attribute 

Scalar: ClassVar = Scalar()

T class-attribute instance-attribute 

T: ClassVar = Time()

N class-attribute instance-attribute 

N: ClassVar = Node()

NxC class-attribute instance-attribute 

NxC: ClassVar = NodeAndCompartment()

NxN class-attribute instance-attribute 

NxN: ClassVar = NodeAndNode()

TxN class-attribute instance-attribute 

TxN: ClassVar = TimeAndNode()

NxA class-attribute instance-attribute 

NxA: ClassVar = NodeAndArbitrary()

AxN class-attribute instance-attribute 

AxN: ClassVar = ArbitraryAndNode()

DataShapeMatcher 

DataShapeMatcher(
    shape: DataShape,
    dim: Dimensions,
    *,
    exact: bool = False,
)

Bases: Matcher[NDArray]

A Matcher which checks whether an array is adaptable to shape under the given dimensions (dim).

Parameters:

  • shape (DataShape) –

    The data shape to match.

  • dim (Dimensions) –

    Information about the simulation context's dimensions.

  • exact (bool, default: False ) –

    If True, do not accept array adaptation, require that the array match exactly.

expected 

expected() -> str

The description of what this matcher's expected valid value(s) are.

Returns:

  • str –

    The value(s) we expect to match, as a string.

__call__ 

__call__(value: NDArray) -> bool

Test whether or not the given value matches this matcher.

Parameters:

  • value (Any) –

    The value to match.

Returns:

  • bool –

    Whether or not the match is successful.

parse_shape 

parse_shape(shape: str) -> DataShape

Attempt to parse DataShape from a shape expression string.

Parameters:

  • shape (str) –

    The shape expression string.

Returns:

  • DataShape –

    The DataShape instance, if valid.

Raises:

  • ValueError –

    If the string is not a supported shape.