epymorph.tools.out_table

Tools for rendering tables from epymorph simulation output data.

OrderingOption module-attribute

OrderingOption = Literal['location', 'quantity']

Options for table row ordering.

FormatOption module-attribute

FormatOption = Literal['dataframe', 'string', 'print']

Options for table render output format.

TableRenderer

TableRenderer(output: Output)

Provides a number of methods for rendering an output in tabular form.

Most commonly, you will use TableRenderer starting from a simulation output object that supports it:

out = BasicSimulation(rume).run()
out.table.quantiles(...)

Parameters:

• output (Output) –

  The output the renderer will use.

output instance-attribute

output: Output = output

The output the renderer will use.

quantiles

quantiles(
    quantiles: Sequence[float],
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    ordering: OrderingOption = "location",
    result_format: FormatOption = "dataframe",
    column_names: Sequence[str] | None = None,
) -> DataFrame | str | None

Renders a table showing time-series quantiles for the given selections.

Parameters:

• quantiles (Sequence[float]) –

  The list of quantiles to calculate and display, in the range [0,1].

• geo (GeoSelection | GeoAggregation) –

  The geographic selection to make on the output data.

• time (TimeSelection | TimeAggregation) –

  The time selection to make on the output data.

• quantity (QuantitySelection | QuantityAggregation) –

  The quantity selection to make on the output data.

• ordering (OrderingOption, default: 'location' ) –

  Controls the ordering of rows in the result; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

• result_format (FormatOption, default: 'dataframe' ) –

  Controls the type of the result of this method; "dataframe" returns a Pandas dataframe, "string" returns the stringified table, and "print" just prints the stringified table directly and returns None.

• column_names (Sequence[str] | None, default: None ) –

  Overrides the default names of the quantiles columns; by default, this is just the quantile value itself.

Returns:

• DataFrame | str | None –

  Output according to the value of the result_format parameter.

range

range(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    ordering: OrderingOption = "location",
    result_format: FormatOption = "dataframe",
) -> DataFrame | str | None

Renders a table showing minimum and maximum values over time for the given selections. This is equivalent to calling quantiles() with 0 and 1.

Parameters:

• geo (GeoSelection | GeoAggregation) –

  The geographic selection to make on the output data.

• time (TimeSelection | TimeAggregation) –

  The time selection to make on the output data.

• quantity (QuantitySelection | QuantityAggregation) –

  The quantity selection to make on the output data.

• ordering (OrderingOption, default: 'location' ) –

  Controls the ordering of rows in the result; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

• result_format (FormatOption, default: 'dataframe' ) –

  Controls the type of the result of this method; "dataframe" returns a Pandas dataframe, "string" returns the stringified table, and "print" just prints the stringified table directly and returns None.

Returns:

• DataFrame | str | None –

  Output according to the value of the result_format parameter.

sum

sum(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    ordering: OrderingOption = "location",
    result_format: FormatOption = "dataframe",
) -> DataFrame | str | None

Renders a table showing summed values over time for the given selections.

Because it is not valid to sum compartment values over time -- this would be double-counting individuals in a way that has no physical meaning -- compartment quantities are automatically omitted even if they are part of the selection, so only events are reflected in the result.

Parameters:

• geo (GeoSelection | GeoAggregation) –

  The geographic selection to make on the output data.

• time (TimeSelection | TimeAggregation) –

  The time selection to make on the output data.

• quantity (QuantitySelection | QuantityAggregation) –

  The quantity selection to make on the output data.

• ordering (OrderingOption, default: 'location' ) –

  Controls the ordering of rows in the result; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

• result_format (FormatOption, default: 'dataframe' ) –

  Controls the type of the result of this method; "dataframe" returns a Pandas dataframe, "string" returns the stringified table, and "print" just prints the stringified table directly and returns None.

Returns:

• DataFrame | str | None –

  Output according to the value of the result_format parameter.

chart

chart(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    chart_length: int = 20,
    ordering: OrderingOption = "location",
    result_format: FormatOption = "dataframe",
) -> DataFrame | str | None

Renders a table showing a rough time series bar chart for the given selections using ASCII characters.

It is of course limited by the fact that this is a relatively coarse display method. The y-axis of each chart is on its own scale, and thus is not comparable to others. However the x-axis is on a shared scale, so this can give you an idea of the time-series behavior of your simulation and relative timing between the selected quantities and locations.

Parameters:

• geo (GeoSelection | GeoAggregation) –

  The geographic selection to make on the output data.

• time (TimeSelection | TimeAggregation) –

  The time selection to make on the output data.

• quantity (QuantitySelection | QuantityAggregation) –

  The quantity selection to make on the output data.

• chart_length (int, default: 20 ) –

  Approximately how many characters should we use to render the charts? This is simply a ballpark, similar to automatically selecting the number of bins in a histogram, so you may get more or less than you ask for. Multiple days may be compressed into one bin, but one day will never be split between bins. The last bin may contain less days of data than the rest of the bins.

• ordering (OrderingOption, default: 'location' ) –

  Controls the ordering of rows in the result; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

• result_format (FormatOption, default: 'dataframe' ) –

  Controls the type of the result of this method; "dataframe" returns a Pandas dataframe, "string" returns the stringified table, and "print" just prints the stringified table directly and returns None.

Returns:

• DataFrame | str | None –

  Output according to the value of the result_format parameter.

TableRendererMixin

Bases: Output

Mixin class that adds a convenient method for rendering tables from an output.

table property

table: TableRenderer

Render a table from this output.