epymorph.attribute

Data attributes are how epymorph keeps track of input data for simulations. An IPM's requirements are expressed as attributes, and when supplying data values to a RUME you use names to match values to the requirement(s) they fulfill.

This module provides a foundation for that, encoding systems for how names work and defining the DataAttribute object itself.

STRATA_PLACEHOLDER module-attribute

STRATA_PLACEHOLDER = '(unspecified)'

The strata name to use when one has not been specified.

MODULE_PLACEHOLDER module-attribute

MODULE_PLACEHOLDER = '(unspecified)'

The module name to use when one has not been specified.

ID_PLACEHOLDER module-attribute

ID_PLACEHOLDER = '(unspecified)'

The attribute ID to use when one has not been specified.

NAMESPACE_PLACEHOLDER module-attribute

NAMESPACE_PLACEHOLDER = ModuleNamespace(
    STRATA_PLACEHOLDER, MODULE_PLACEHOLDER
)

A namespace to use when we don't need to be specific.

NAME_PLACEHOLDER module-attribute

NAME_PLACEHOLDER = to_absolute(ID_PLACEHOLDER)

An absolute name to use when we don't need to be specific.

AttributeT module-attribute

AttributeT = TypeVar('AttributeT', bound=AttributeType)

The data type of an attribute; maps to the numpy type of the attribute array.

ModuleNamespace dataclass

ModuleNamespace(strata: str, module: str)

A namespace which specifies strata and module.

Parameters:

• strata (str) –

  The strata name.

• module (str) –

  The module name.

strata instance-attribute

strata: str

The strata name.

module instance-attribute

module: str

The module name.

parse classmethod

parse(name: str) -> Self

Parse a module namespace from a ::-delimited string.

Parameters:

• name (str) –

  The string to parse.

Returns:

• Self –

  The new namespace instance.

Raises:

• ValueError –

  If the given string cannot be parsed.

Examples:

>>> ModuleNamespace.parse("gpm:human::ipm")
ModuleNamespace(strata="gpm:human", module="ipm")

to_absolute

to_absolute(attrib_id: str) -> AbsoluteName

Creates an absolute name by providing the attribute ID.

Parameters:

• attrib_id (str) –

  The attribute ID to append to the namespace.

Returns:

• AbsoluteName –

  The new absolute name instance.

AbsoluteName dataclass

AbsoluteName(strata: str, module: str, id: str)

A fully-specified name: strata, module, and attribute ID.

Parameters:

• strata (str) –

  The strata name.

• module (str) –

  The module name.

• id (str) –

  The attribute ID.

strata instance-attribute

strata: str

The strata name.

module instance-attribute

module: str

The module name.

id instance-attribute

id: str

The attribute ID.

parse classmethod

parse(name: str) -> Self

Parse a module name from a ::-delimited string.

Parameters:

• name (str) –

  The string to parse.

Returns:

• Self –

  The new name instance.

Raises:

• ValueError –

  If the given string cannot be parsed.

Examples:

>>> AbsoluteName.parse("gpm:human::ipm::beta")
AbsoluteName(strata="gpm:human", module="ipm", id="beta")

in_strata

in_strata(new_strata: str) -> AbsoluteName

Creates a new AbsoluteName that is a copy of this name but with the given strata.

Parameters:

• new_strata (str) –

  The strata to use to replace this name's strata.

Returns:

• AbsoluteName –

  The new name instance.

with_id

with_id(new_id: str) -> AbsoluteName

Creates a new AbsoluteName that is a copy of this name but with the given ID.

Parameters:

• new_id (str) –

  The attribute ID to use to replace this name's ID.

Returns:

• AbsoluteName –

  The new name instance.

to_namespace

to_namespace() -> ModuleNamespace

Extracts the module namespace part of this name.

Returns:

• ModuleNamespace –

  The new module namespace instance.

to_pattern

to_pattern() -> NamePattern

Converts this name to a pattern that is an exact match for this name.

Returns:

• NamePattern –

  The new name pattern instance.

ModuleName dataclass

ModuleName(module: str, id: str)

A partially-specified name with module and attribute ID.

Parameters:

• module (str) –

  The module name.

• id (str) –

  The attribute ID.

module instance-attribute

module: str

The module name.

id instance-attribute

id: str

The attribute ID.

parse classmethod

parse(name: str) -> Self

Parse a module name from a ::-delimited string.

Parameters:

• name (str) –

  The string to parse.

Returns:

• Self –

  The new name instance.

Raises:

• ValueError –

  If the given string cannot be parsed.

Examples:

>>> ModuleName.parse("ipm::beta")
ModuleName(module="ipm", id="beta")

to_absolute

to_absolute(strata: str) -> AbsoluteName

Creates an absolute name by providing the strata.

Parameters:

• strata (str) –

  The strata name to use.

Returns:

• AbsoluteName –

  The new absolute name instance.

AttributeName dataclass

AttributeName(id: str)

A partially-specified name with just an attribute ID.

Parameters:

• id (str) –

  The attribute ID.

id instance-attribute

id: str

The attribute ID.

NamePattern dataclass

NamePattern(strata: str, module: str, id: str)

A name with a strata, module, and attribute ID that allows wildcards (*) so it can act as a pattern to match against AbsoluteNames.

Parameters:

• strata (str) –

  The strata name or wildcard.

• module (str) –

  The module name or wildcard.

• id (str) –

  The attribute ID or wildcard.

strata instance-attribute

strata: str

The strata name or wildcard.

module instance-attribute

module: str

The module name or wildcard.

id instance-attribute

id: str

The attribute ID or wildcard.

parse classmethod

parse(name: str) -> Self

Parse a pattern from a ::-delimited string. As a shorthand, you can omit preceding wildcard segments and they will be automatically filled in, e.g., "a" will become "::::a" and "a::b" will become "*::a::b".

Parameters:

• name (str) –

  The string to parse.

Returns:

• Self –

  The new name pattern instance.

Raises:

• ValueError –

  If the given string cannot be parsed.

Examples:

>>> NamePattern.parse("gpm:human::ipm::beta")
NamePattern(strata="gpm:human", module="ipm", id="beta")

>>> NamePattern.parse("*::*::beta")
NamePattern(strata="*", module="*", id="beta")

>>> NamePattern.parse("beta")
NamePattern(strata="*", module="*", id="beta")

of staticmethod

of(name: str | NamePattern) -> NamePattern

Coerce the given value to a NamePattern.

Parameters:

• name (str | NamePattern) –

  The name to coerce. This will be parsed if given as a string or returned as-is if it's already a NamePattern instance.

Returns:

• NamePattern –

  The name pattern instance.

Raises:

• ValueError –

  If name is given as a string but cannot be parsed.

match

match(name: AbsoluteName | NamePattern) -> bool

Test this pattern to see if it matches the given AbsoluteName or NamePattern. The ability to match against NamePatterns is useful to see if two patterns conflict with each other and would create ambiguity.

Parameters:

• name (AbsoluteName | NamePattern) –

  The name to check against this pattern.

Returns:

• bool –

  True if there is a match, false otherwise.

ModuleNamePattern dataclass

ModuleNamePattern(module: str, id: str)

A name with a module and attribute ID that allows wildcards (*). Mostly this is useful to provide parameters to GPMs, which don't have a concept of which strata they belong to. A ModuleNamePattern can be transformed into a full NamePattern by adding the strata.

Parameters:

• module (str) –

  The module name or wildcard.

• id (str) –

  The attribute ID or wildcard.

module instance-attribute

module: str

The module name or wildcard.

id instance-attribute

id: str

The attribute ID or wildcard.

parse classmethod

parse(name: str) -> Self

Parse a pattern from a ::-delimited string. As a shorthand, you can omit a preceding wildcard segment and it will be automatically filled in, e.g.,"a" will become "*::a".

Parameters:

• name (str) –

  The string to parse.

Returns:

• Self –

  The new name pattern instance.

Raises:

• ValueError –

  If the given string cannot be parsed.

Examples:

>>> ModuleNamePattern.parse("ipm::beta")
ModuleNamePattern(module="ipm", id="beta")

>>> ModuleNamePattern.parse("*::beta")
ModuleNamePattern(module="*", id="beta")

>>> ModuleNamePattern.parse("beta")
ModuleNamePattern(module="*", id="beta")

to_absolute

to_absolute(strata: str) -> NamePattern

Creates a full name pattern by providing the strata.

Parameters:

• strata (str) –

  The strata to use.

Returns:

• NamePattern –

  The new name pattern instance.

AttributeDef dataclass

AttributeDef(
    name: str,
    type: AttributeT,
    shape: DataShape,
    default_value: AttributeValue | None = None,
    comment: str | None = None,
)

Bases: Generic[AttributeT]

The definition of a data attribute. Attributes are frequently used to define the data requirements of things like IPMs and parameter functions.

AttributeDef is generic on the AttributeType which describes the type of the data (AttributeT).

Parameters:

• name (str) –

  The name used to identify the attribute.

• type (AttributeT) –

  The type of the data.

• shape (DataShape) –

  The expected array shape of the data.

• default_value (AttributeValue | None, default: None ) –

  An optional default value.

• comment (str | None, default: None ) –

  An optional description of the attribute.

name instance-attribute

name: str

The name used to identify the attribute.

type instance-attribute

type: AttributeT

The type of the data.

shape instance-attribute

shape: DataShape

The expected array shape of the data.

default_value class-attribute instance-attribute

default_value: AttributeValue | None = field(
    default=None, compare=False
)

An optional default value.

comment class-attribute instance-attribute

comment: str | None = field(default=None, compare=False)

An optional description of the attribute.