Skip to content

epymorph.geography.scope

GeoScopeT module-attribute 

GeoScopeT = TypeVar('GeoScopeT', bound=GeoScope)

A type of GeoScope.

GeoScopeT_co module-attribute 

GeoScopeT_co = TypeVar(
    "GeoScopeT_co", covariant=True, bound=GeoScope
)

A type of GeoScope: covariant.

GeoAggMethod module-attribute 

GeoAggMethod = Literal['sum', 'min', 'max']

Methods for aggregating results along the geo axis.

GeoSelectionT_co module-attribute 

GeoSelectionT_co = TypeVar(
    "GeoSelectionT_co", covariant=True, bound=GeoSelection
)

The type of geo selection.

GeoScope

Bases: Protocol

The common interface expected of all geo scopes.

node_ids abstractmethod property 

node_ids: NDArray[str_]

The list of node IDs included in this scope.

nodes property 

nodes: int

The number of nodes in this scope.

labels_option property 

labels_option: NDArray[str_] | None

An optional text label for each node. If this returns None, convention is to use the node IDs as the labels.

labels property 

labels: NDArray[str_]

The best text label for each node. (This uses labels_option if available and falls back to node_ids.)

geography abstractmethod property 

geography: GeoDataFrame | Never

Retrieves the shapes corresponding to the nodes of this scope as a GeoDataFrame. Note that this is not possible for all types of GeoScope.

Returns:

Raises:

  • GeographyError –

    If we cannot fetch geography for this type of scope.

index_of 

index_of(node_id: str) -> int

Returns the index of a given node by its ID string.

Parameters:

  • node_id (str) –

    The ID to check for.

Returns:

  • int –

    The index if node_id exists in this scope.

Raises:

GeoStrategy dataclass 

GeoStrategy(
    scope: GeoScopeT_co,
    selection: NDArray[bool_],
    grouping: GeoGrouping | None,
    aggregation: GeoAggMethod | None,
)

Bases: ABC, Generic[GeoScopeT_co]

A strategy for dealing with the spatial axis, e.g., in processing results. Strategies can include selection of a subset, grouping, and aggregation.

Typically you will create one of these buy calling methods on a GeoSelector instance.

GeoStrategy is generic in the type of GeoScope it works with (GeoScopeT_co).

scope instance-attribute 

scope: GeoScopeT_co

The original scope.

selection instance-attribute 

selection: NDArray[bool_]

A boolean mask for selection of a subset of geo nodes.

grouping instance-attribute 

grouping: GeoGrouping | None

A method for grouping geo nodes.

aggregation instance-attribute 

aggregation: GeoAggMethod | None

A method for aggregating by group (if no grouping is specified, selected nodes are treated as one group).

indices property 

indices: tuple[int, ...]

A tuple containing the indices from the original scope that are selected by this strategy.

to_scope 

to_scope() -> GeoScope

Convert this strategy to the scope that results from applying this strategy.

For example, if your original scope included all tracts in the US and the strategy selects Arizona and groups by county, this method would return a scope containing all counties in Arizona.

Returns:

Raises:

GeoGrouping

Bases: ABC

Defines a geo-axis grouping scheme. This is essentially a function that maps the simulation geo axis info (node IDs) into a new series which describes the group membership of each geo axis row.

Certain groupings may only be valid for specific types of GeoScope.

map abstractmethod 

map(node_ids: NDArray[str_]) -> NDArray[str_]

Produce a column that describes the group membership of each node.

The returned column will be used as the basis of a groupby operation.

Parameters:

Returns:

  • NDArray[str_] –

    An array of the same length as node_ids where each value defines which group the original node ID belongs to.

GeoSelection dataclass 

GeoSelection(
    scope: GeoScopeT_co,
    selection: NDArray[bool_],
    grouping: GeoGrouping | None,
    aggregation: GeoAggMethod | None,
)

Bases: _CanGeoAggregate[GeoScopeT_co], GeoStrategy[GeoScopeT_co]

A kind of GeoStrategy describing a sub-selection operation on a geo scope. A selection performs no grouping or aggregation.

Typically you will create one of these by calling methods on a GeoSelector instance.

Parameters:

  • scope (GeoScopeT_co) –

    The original scope.

  • selection (NDArray[bool_]) –

    A boolean mask for selection of a subset of geo nodes.

scope instance-attribute 

scope: GeoScopeT_co

The original scope.

selection instance-attribute 

selection: NDArray[bool_]

A boolean mask for selection of a subset of geo nodes.

grouping class-attribute instance-attribute 

grouping: None = field(init=False, default=None)

A method for grouping geo nodes.

aggregation class-attribute instance-attribute 

aggregation: None = field(init=False, default=None)

A method for aggregating by group (if no grouping is specified, selected nodes are treated as one group).

agg 

agg(agg: GeoAggMethod) -> GeoAggregation[GeoScopeT_co]

Apply the named aggregation for each geo node group.

Parameters:

Returns:

sum 

sum() -> GeoAggregation[GeoScopeT_co]

Perform a sum for each geo node group.

Returns:

min 

min() -> GeoAggregation[GeoScopeT_co]

Take the min value for each geo node group.

Returns:

max 

max() -> GeoAggregation[GeoScopeT_co]

Take the max value for each geo node group.

Returns:

GeoGroup dataclass 

GeoGroup(
    scope: GeoScopeT_co,
    selection: NDArray[bool_],
    grouping: GeoGrouping,
    aggregation: GeoAggMethod | None,
)

Bases: _CanGeoAggregate[GeoScopeT_co], GeoStrategy[GeoScopeT_co]

A kind of GeoStrategy describing a grouping operation on a geo scope, with an optional sub-selection.

Typically you will create one of these by calling methods on a GeoSelection instance.

Parameters:

  • scope (GeoScopeT_co) –

    The original scope.

  • selection (NDArray[bool_]) –

    A boolean mask for selection of a subset of geo nodes.

  • grouping (GeoGrouping) –

    A method for grouping geo nodes.

scope instance-attribute 

scope: GeoScopeT_co

The original scope.

selection instance-attribute 

selection: NDArray[bool_]

A boolean mask for selection of a subset of geo nodes.

grouping instance-attribute 

grouping: GeoGrouping

A method for grouping geo nodes.

aggregation class-attribute instance-attribute 

aggregation: None = field(init=False, default=None)

A method for aggregating by group (if no grouping is specified, selected nodes are treated as one group).

agg 

agg(agg: GeoAggMethod) -> GeoAggregation[GeoScopeT_co]

Apply the named aggregation for each geo node group.

Parameters:

Returns:

sum 

sum() -> GeoAggregation[GeoScopeT_co]

Perform a sum for each geo node group.

Returns:

min 

min() -> GeoAggregation[GeoScopeT_co]

Take the min value for each geo node group.

Returns:

max 

max() -> GeoAggregation[GeoScopeT_co]

Take the max value for each geo node group.

Returns:

GeoAggregation dataclass 

GeoAggregation(
    scope: GeoScopeT_co,
    selection: NDArray[bool_],
    grouping: GeoGrouping | None,
    aggregation: GeoAggMethod,
)

Bases: GeoStrategy[GeoScopeT_co]

Describes a group-and-aggregate operation on a geo scope, with an optional sub-selection.

Typically you will create one of these by calling methods on a GeoSelection instance.

Parameters:

  • scope (GeoScopeT_co) –

    The original scope.

  • selection (NDArray[bool_]) –

    A boolean mask for selection of a subset of geo nodes.

  • grouping (GeoGrouping | None) –

    A method for grouping geo nodes.

  • aggregation (GeoAggMethod) –

    A method for aggregating by group (if no grouping is specified, selected nodes are treated as one group).

scope instance-attribute 

scope: GeoScopeT_co

The original scope.

selection instance-attribute 

selection: NDArray[bool_]

A boolean mask for selection of a subset of geo nodes.

grouping instance-attribute 

grouping: GeoGrouping | None

A method for grouping geo nodes.

aggregation instance-attribute 

aggregation: GeoAggMethod

A method for aggregating by group (if no grouping is specified, selected nodes are treated as one group).

GeoSelector dataclass 

GeoSelector(
    _scope: GeoScopeT_co,
    _selection_class: type[GeoSelectionT_co],
)

Bases: Generic[GeoScopeT_co, GeoSelectionT_co]

A utility class for making a selection on a particular kind of GeoScope. Most of the time you obtain one of these using a GeoScope's select property.

all 

all() -> GeoSelectionT_co

Select all geo nodes.

Returns:

by_id 

by_id(*ids: str) -> GeoSelectionT_co

Select geo nodes by their ID (exact matches only).

Parameters:

  • *ids (str, default: () ) –

    Node IDs to include in the selection, as var-args.

Returns:

strategy_to_scope 

strategy_to_scope(
    scope: GeoScopeT, strategy: GeoStrategy[GeoScopeT]
) -> GeoScope

Converts a GeoStrategy instance to the GeoScope that would result from applying the strategy.

Warning

This function is intended for epymorph's internal use; users should instead call to_scope on a GeoStrategy object.

Parameters:

Returns:

Raises: