Skip to content

epymorph.time

GroupKeyType module-attribute 

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

The numpy type used to represent the group keys of a TimeGrouping.

AggMethod module-attribute 

AggMethod = Literal[
    "sum", "max", "min", "mean", "median", "last", "first"
]

A method for aggregating time series data.

DEFAULT_TIME_AGG module-attribute 

DEFAULT_TIME_AGG = TimeAggMethod('last', 'sum')

By default, time series should be aggregated using 'last' for compartments and 'sum' for events.

DateRange dataclass 

DateRange(start_date: date, end_date: date, step: int = 1)

A sequence of calendar dates, with a fixed interval between dates (default 1 day).

Parameters:

  • start_date (date) –

    The first date in the range.

  • end_date (date) –

    The last date in the range. Must be an exact multiple of steps after start_date.

  • step (int, default: 1 ) –

    The step between dates in the range, as a number of days. Must be 1 or greater.

start_date instance-attribute 

start_date: date

The first date in the range.

end_date instance-attribute 

end_date: date

The last date in the range.

step class-attribute instance-attribute 

step: int = field(default=1)

The step between dates in the range, as a number of days.

until_date classmethod 

until_date(
    start_date: date, max_end_date: date, step: int
) -> Self

Alternative constructor for cases where you aren't sure of the precise end date: that is, you know roughly when the range ends but aren't sure if that date is an exact number of steps after start date.

Parameters:

  • start_date (date) –

    The first date in the range.

  • max_end_date (date) –

    The latest possible date in the range. If max_end_date is already an exact multiple of steps away from start_date, it will be the DateRange's end date. Otherwise, we will calculate the latest date that is before max_end_date and also an exact multiple of steps after start date.

  • step (int) –

    The interval between dates in the range, as a number of days. Must be 1 or greater.

Returns:

  • Self –

    A new DateRange.

between 

between(min_date: date, max_date: date) -> DateRange | None

Compute a new DateRange that represents the subset of dates in this range that are also between min_date and max_date (inclusive).

Parameters:

  • min_date (date) –

    The earliest date to include in the subset.

  • max_date (date) –

    The latest date to include in the subset.

Returns:

  • DateRange | None –

    The subset DateRange, or None if that subset would be empty -- when there's no overlap between this range and the min/max dates.

overlap 

overlap(time_frame: TimeFrame) -> DateRange | None

Compute a new DateRange that represents the subset of dates in this range that are also in the given TimeFrame.

Parameters:

  • time_frame (TimeFrame) –

    The time frame to overlap.

Returns:

  • DateRange | None –

    The subset DateRange, or None if that subset would be empty -- when there's no overlap between this DateRange and the time frame.

overlap_or_raise 

overlap_or_raise(time_frame: TimeFrame) -> DateRange

Compute a new DateRange that represents the subset of dates in this range that are also in the given TimeFrame. If there is no overlap, raise an error.

Parameters:

  • time_frame (TimeFrame) –

    The time frame to overlap.

Returns:

Raises:

  • ValueError –

    When there's no overlap between this DateRange and the time frame.

to_pandas 

to_pandas() -> DatetimeIndex

Convert the DateRange to a Pandas datetime index.

Returns:

  • DatetimeIndex –

    The index containing all dates in the range in order.

to_numpy 

to_numpy() -> NDArray[datetime64]

Convert the DateRange to a numpy datetime64 array.

Returns:

  • NDArray[datetime64] –

    The one-dimensional array containing all dates in the range in order.

TimeFrame dataclass 

TimeFrame(start_date: date, duration_days: int)

Describes a time frame as a contiguous set of calendar dates, primarily used to define the time frame of a simulation.

Parameters:

  • start_date (date) –

    The first date included in the time frame.

  • duration_days (int) –

    The number of days included in the time frame.

Examples:

For your convenience, there are a number of ways to construct TimeFrame instances:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from datetime import date
from epymorph.time import TimeFrame

# 1. Start January 1st, 2020 and go for 150 days
TimeFrame(date(2020, 1, 1), 150)

# 2. Equivalent, but accept dates as ISO-8601 strings
TimeFrame.of("2020-01-01", 150)

# 3. January through March 2020
TimeFrame.range("2020-01-01", "2020-03-31")

# 4. Equivalent, but using an exclusive endpoint
TimeFrame.rangex("2020-01-01", "2020-04-01")

# 5. The whole of 2020
TimeFrame.year(2020)

start_date instance-attribute 

start_date: date

The first date in the time frame.

duration_days instance-attribute 

duration_days: int

The number of days included in the time frame.

end_date class-attribute instance-attribute 

end_date: date = field(init=False)

The last date included in the time frame.

days property 

days: int

Alias for duration_days

select property 

select: TimeSelector

Create a time-axis strategy from this time frame.

In most cases, this will be used to process a simulation result and so you should use a selection on the time frame used in the RUME that produced the result.

of classmethod 

of(start_date: date | str, duration_days: int) -> Self

Alternate constructor: start date (accepts ISO-8601 strings) and a given duration in days.

Parameters:

  • start_date (date | str) –

    The starting date. If a date is passed as a string, it will be parsed using ISO-8601 format.

  • duration_days (int) –

    The number of days in the time frame, including the first day.

Returns:

  • Self –

    The new TimeFrame.

range classmethod 

range(start_date: date | str, end_date: date | str) -> Self

Alternate constructor: start and end date (inclusive).

Parameters:

  • start_date (date | str) –

    The starting date. If a date is passed as a string, it will be parsed using ISO-8601 format.

  • end_date (date | str) –

    The final date included in the time frame. If a date is passed as a string, it will be parsed using ISO-8601 format.

Returns:

  • Self –

    The new TimeFrame.

rangex classmethod 

rangex(
    start_date: date | str, end_date_exclusive: date | str
) -> Self

Alternate constructor: start and end date (exclusive).

Parameters:

  • start_date (date | str) –

    The starting date. If a date is passed as a string, it will be parsed using ISO-8601 format.

  • end_date_exclusive (date | str) –

    The stop date, which is to say the first date not in the time frame. If a date is passed as a string, it will be parsed using ISO-8601 format.

Returns:

  • Self –

    The new TimeFrame.

year classmethod 

year(year: int) -> Self

Alternate constructor: an entire calendar year.

Parameters:

  • year (int) –

    The year of the time frame, from January 1st through December 31st. Includes 365 days, or 366 days on a leap year.

Returns:

  • Self –

    The new TimeFrame.

is_subset 

is_subset(other: TimeFrame) -> bool

Is the given TimeFrame a subset of this one?

Parameters:

  • other (TimeFrame) –

    The other time frame to consider.

Returns:

  • bool –

    True if the other time frame is a subset of this time frame.

__iter__ 

__iter__() -> Iterator[date]

Iterate over the sequence of dates in the time frame.

to_numpy 

to_numpy() -> NDArray[datetime64]

Returns a numpy array of the dates in this time frame.

Returns:

to_date_range 

to_date_range() -> DateRange

Returns a date range that corresponds to this time frame's start and end date.

Returns:

EpiWeek

Bases: NamedTuple

Identifies a specific epi week, a CDC-defined system for labeling weeks of the year in a consistent way.

See Also

This reference on epi weeks.

year instance-attribute 

year: int

Four-digit year

week instance-attribute 

week: int

Week number, in the range [1,53]

start property 

start: Timestamp

The first date in this epi week.

Dim

Bases: NamedTuple

Describes data dimensions for a time-grouping operation; i.e., after subselections and geo-grouping.

nodes instance-attribute 

nodes: int

The number of unique nodes or node-groups.

days instance-attribute 

days: int

The number of days, after any sub-selection.

tau_steps instance-attribute 

tau_steps: int

The number of tau steps per day.

TimeGrouping

Bases: ABC, Generic[GroupKeyType]

Base class for time-axis grouping schemes. This is essentially a function that maps the simulation time axis info (ticks and dates) into a new series which describes the group membership of each time axis row.

TimeGrouping is generic in the type of the key it uses for its time groups (GroupKeyType) -- e.g., a grouping that groups weeks using the Monday of the week is datetime64 typed, while a grouping that groups days into arbitrary buckets might use integers to identify groups.

group_format instance-attribute 

group_format: Literal['date', 'tick', 'day', 'other']

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

map abstractmethod 

map(
    dim: Dim,
    ticks: NDArray[int64],
    dates: NDArray[datetime64],
) -> NDArray[GroupKeyType]

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

ByTick

Bases: TimeGrouping[int64]

A kind of TimeGrouping to group by simulation tick. (Effectively the same as no grouping.)

group_format class-attribute instance-attribute 

group_format = 'tick'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

ByDate

Bases: TimeGrouping[datetime64]

A kind of TimeGrouping to group by date.

group_format class-attribute instance-attribute 

group_format = 'date'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

ByWeek 

ByWeek(start_of_week: int = 0)

Bases: TimeGrouping[datetime64]

A kind of TimeGrouping to group by week, using a configurable start of the week.

Parameters:

  • start_of_week (int, default: 0 ) –

    Which day of the week is the begins each weekly group? This uses the Python standard numbering for week days, so 0=Monday and 6=Sunday.

group_format class-attribute instance-attribute 

group_format = 'date'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

start_of_week instance-attribute 

start_of_week: int = start_of_week

Which day of the week should we group on? 0=Monday through 6=Sunday

map 

map(dim, ticks, dates) -> NDArray[datetime64]

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

ByMonth

Bases: TimeGrouping[datetime64]

A kind TimeGrouping to group by month, using the first day of the month.

group_format class-attribute instance-attribute 

group_format = 'date'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

EveryNDays 

EveryNDays(days: int)

Bases: TimeGrouping[datetime64]

A kind of TimeGrouping to group every 'n' days from the start of the time range.

Parameters:

  • days (int) –

    How many days should be in each group?

group_format class-attribute instance-attribute 

group_format = 'date'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

days instance-attribute 

days: int = days

How many days are in each group?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

NBins 

NBins(bins: int)

Bases: TimeGrouping[int64]

A kind of TimeGrouping to group the time series into a number of bins where bin boundaries must align with simulation days.

If the time series is not evenly divisible into the given number of bins, you may get more bins than requested (data will not be truncated). You will never get more than one bin per day.

Parameters:

  • bins (int) –

    Approximately how many bins should be in the result?

group_format class-attribute instance-attribute 

group_format = 'other'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

bins instance-attribute 

bins: int = bins

Approximately how many bins should be in the result?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

ByEpiWeek

Bases: TimeGrouping[str_]

A kind of TimeGrouping to group the time series by epi week.

group_format class-attribute instance-attribute 

group_format = 'other'

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

map 

map(dim, ticks, dates)

Produce a column that describes the group membership of each "row", where each entry of ticks and dates describes a row of the time series. This column will be used as the basis of a groupby operation.

The result must correspond element-wise to the given ticks and dates arrays. dim contains dimensional info relevant to this grouping operation. Note that we may have sub-selected the geo and/or the time frame, so these dimensions may differ from those of the simulation as a whole.

ticks and dates will be nodes * days * tau_steps in length. Values will be in order, but each tick will be represented nodes times, and each date will be represented nodes * tau_steps times. Since we may be grouping a slice of the simulation time frame, ticks may start after 0 and end before the last tick of the simulation.

Parameters:

  • dim (Dim) –

    The simulation dimensions for time grouping.

  • ticks (NDArray[int64]) –

    The series of simulation ticks.

  • dates (NDArray[datetime64]) –

    The series of calendar dates corresponding to simulation ticks.

Returns:

  • NDArray[GroupKeyType] –

    The group membership of each tick. For example, if the first three ticks were in group 0 and the next three ticks were in group 1, etc., the returned array would contain [0,0,0,1,1,1,...].

TimeAggMethod

Bases: NamedTuple

A time-axis aggregation scheme. There may be one aggregation method for compartments and another for events.

compartments instance-attribute 

compartments: AggMethod

The method for aggregating compartment values.

events instance-attribute 

events: AggMethod

The method for aggregating event values.

TimeStrategy dataclass 

TimeStrategy(
    time_frame: TimeFrame,
    selection: tuple[slice, int | None],
    grouping: TimeGrouping | None,
    aggregation: TimeAggMethod | None,
)

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

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

Parameters:

  • time_frame (TimeFrame) –

    The original simulation time frame.

  • selection (tuple[slice, int | None]) –

    The selected subset of the time frame: described as a date slice and an optional tau step index.

  • grouping (TimeGrouping | None) –

    A method for grouping the time series data.

  • aggregation (TimeAggMethod | None) –

    A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

time_frame instance-attribute 

time_frame: TimeFrame

The original time frame.

selection instance-attribute 

selection: tuple[slice, int | None]

The selected subset of the time frame: described as a date slice and an optional tau step index.

grouping instance-attribute 

grouping: TimeGrouping | None

A method for grouping the time series data.

aggregation instance-attribute 

aggregation: TimeAggMethod | None

A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

group_format abstractmethod property 

group_format: Literal['date', 'tick', 'day', 'other']

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

date_bounds property 

date_bounds: tuple[date, date]

The bounds of the selection, given as the first and last date included.

to_time_frame 

to_time_frame() -> TimeFrame

Creates a TimeFrame that has the same bounds as this TimeStrategy.

NOTE: this does not mean the TimeFrame contains the same number of entries (group keys) as the result of applying this strategy -- groups can skip days whereas TimeFrames are contiguous.

Returns:

  • TimeFrame –

    The corresponding time frame.

selection_ticks 

selection_ticks(taus: int) -> slice

Converts this into a slice for which ticks are selected (by index).

Parameters:

  • taus (int) –

    The total number of tau steps per day.

Returns:

  • slice –

    The selection as an index slice.

TimeSelection dataclass 

TimeSelection(
    time_frame: TimeFrame,
    selection: tuple[slice, int | None],
    grouping: TimeGrouping | None,
    aggregation: TimeAggMethod | None,
)

Bases: _CanAggregate, TimeStrategy

A kind of TimeStrategy describing a sub-selection of a time frame. A selection performs no grouping or aggregation.

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

Parameters:

  • time_frame (TimeFrame) –

    The original simulation time frame.

  • selection (tuple[slice, int | None]) –

    The selected subset of the time frame: described as a date slice and an optional tau step index.

time_frame instance-attribute 

time_frame: TimeFrame

The original time frame.

selection instance-attribute 

selection: tuple[slice, int | None]

The selected subset of the time frame: described as a date slice and an optional tau step index.

grouping class-attribute instance-attribute 

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

A method for grouping the time series data.

aggregation class-attribute instance-attribute 

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

A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

group_format property 

group_format: Literal['tick']

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

group 

group(
    grouping: Literal["day", "week", "epiweek", "month"]
    | TimeGrouping,
) -> TimeGroup

Groups the time series using the specified grouping.

Parameters:

  • grouping (Literal['day', 'week', 'epiweek', 'month'] | TimeGrouping) –

    The grouping to use. You can specify a supported string value -- all of which act as shortcuts for common TimeGrouping instances -- or you can provide a TimeGrouping instance to perform custom grouping.

    The shortcut values are:

    • "day": equivalent to ByDate
    • "week": equivalent to ByWeek
    • "epiweek": equivalent to ByEpiWeek
    • "month": equivalent to ByMonth

Returns:

agg 

agg(
    compartments: AggMethod = "last",
    events: AggMethod = "sum",
) -> TimeAggregation

Aggregates the time series using the specified methods.

Parameters:

  • compartments (AggMethod, default: 'last' ) –

    The method to use to aggregate compartment values.

  • events (AggMethod, default: 'sum' ) –

    The method to use to aggregate event values.

Returns:

TimeGroup dataclass 

TimeGroup(
    time_frame: TimeFrame,
    selection: tuple[slice, int | None],
    grouping: TimeGrouping,
    aggregation: TimeAggMethod | None,
)

Bases: _CanAggregate, TimeStrategy

A kind of TimeStrategy describing a group operation on a time frame, with an optional sub-selection.

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

Parameters:

  • time_frame (TimeFrame) –

    The original simulation time frame.

  • selection (tuple[slice, int | None]) –

    The selected subset of the time frame: described as a date slice and an optional tau step index.

  • grouping (TimeGrouping) –

    A method for grouping the time series data.

time_frame instance-attribute 

time_frame: TimeFrame

The original time frame.

selection instance-attribute 

selection: tuple[slice, int | None]

The selected subset of the time frame: described as a date slice and an optional tau step index.

grouping instance-attribute 

grouping: TimeGrouping

A method for grouping the time series data.

aggregation class-attribute instance-attribute 

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

A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

group_format property 

group_format

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

agg 

agg(
    compartments: AggMethod = "last",
    events: AggMethod = "sum",
) -> TimeAggregation

Aggregates the time series using the specified methods.

Parameters:

  • compartments (AggMethod, default: 'last' ) –

    The method to use to aggregate compartment values.

  • events (AggMethod, default: 'sum' ) –

    The method to use to aggregate event values.

Returns:

TimeAggregation dataclass 

TimeAggregation(
    time_frame: TimeFrame,
    selection: tuple[slice, int | None],
    grouping: TimeGrouping | None,
    aggregation: TimeAggMethod,
)

Bases: TimeStrategy

A kind of TimeStrategy describing a group-and-aggregate operation on a time frame, with an optional sub-selection.

Typically you will create one of these by calling methods on a TimeSelection or TimeGroup instance.

Parameters:

  • time_frame (TimeFrame) –

    The original simulation time frame.

  • selection (tuple[slice, int | None]) –

    The selected subset of the time frame: described as a date slice and an optional tau step index.

  • grouping (TimeGrouping | None) –

    A method for grouping the time series data.

  • aggregation (TimeAggMethod) –

    A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

time_frame instance-attribute 

time_frame: TimeFrame

The original time frame.

selection instance-attribute 

selection: tuple[slice, int | None]

The selected subset of the time frame: described as a date slice and an optional tau step index.

grouping instance-attribute 

grouping: TimeGrouping | None

A method for grouping the time series data.

aggregation instance-attribute 

aggregation: TimeAggMethod

A method for aggregating the time series data (if no grouping is specified, the time series is reduced to a scalar).

group_format property 

group_format

What scale describes the result of the grouping? Are the group keys dates? Simulation ticks? Simulation days? Or some arbitrary other type?

TimeSelector dataclass 

TimeSelector(time_frame: TimeFrame)

A utility class for selecting a subset of a time frame. Most of the time you obtain one of these using TimeFrame's select property.

time_frame instance-attribute 

time_frame: TimeFrame

The original time frame.

all 

all(step: int | None = None) -> TimeSelection

Select the entirety of the time frame.

Parameters:

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

    If given, narrow the selection to a specific tau step (by index) within the date range; by default include all steps.

Returns:

days 

days(
    from_day: int, to_day: int, step: int | None = None
) -> TimeSelection

Subset the time frame by providing a start and end simulation day (inclusive).

Parameters:

  • from_day (int) –

    The starting simulation day of the range, as an index.

  • to_day (int) –

    The last included simulation day of the range, as an index.

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

    If given, narrow the selection to a specific tau step (by index) within the date range; by default include all steps.

Returns:

range 

range(
    from_date: date | str,
    to_date: date | str,
    step: int | None = None,
) -> TimeSelection

Subset the time frame by providing the start and end date (inclusive).

Parameters:

  • from_date (date | str) –

    The starting date of the range, as a date object or an ISO-8601 string.

  • to_date (date | str) –

    The last included date of the range, as a date object or an ISO-8601 string.

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

    If given, narrow the selection to a specific tau step (by index) within the date range; by default include all steps.

Returns:

rangex 

rangex(
    from_date: date | str,
    until_date: date | str,
    step: int | None = None,
) -> TimeSelection

Subset the time frame by providing the start and end date (exclusive).

Parameters:

  • from_date (date | str) –

    The starting date of the range, as a date object or an ISO-8601 string.

  • until_date (date | str) –

    The stop date date of the range (the first date excluded) as a date object or an ISO-8601 string.

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

    If given, narrow the selection to a specific tau step (by index) within the date range; by default include all steps.

Returns:

year 

year(year: int, step: int | None = None) -> TimeSelection

Subset the time frame to a specific year.

Parameters:

  • year (int) –

    The year to include, from January 1st through December 31st.

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

    If given, narrow the selection to a specific tau step (by index) within the date range; by default include all steps.

Returns:

iso8601 

iso8601(value: date | str) -> date

Adapt ISO 8601 strings to dates; leave dates as they are.

Parameters:

  • value (date | str) –

    The value to parse (if string) or pass through unchanged (if date).

Returns:

  • date –

    The equivalent date.

epi_year_first_day 

epi_year_first_day(year: int) -> Timestamp

Calculates the first day in an epi-year.

Parameters:

  • year (int) –

    The year to consider.

Returns:

  • Timestamp –

    The first day of the first epi week in the given year.

epi_week 

epi_week(check_date: date) -> EpiWeek

Calculates which epi week the given date belongs to.

Parameters:

  • check_date (date) –

    The date to consider.

Returns:

  • EpiWeek –

    The EpiWeek that contains the given date.