API Reference

epymorph.rume

Specify runnable modeling experiments.

RUME	A RUME (or Runnable Modeling Experiment) contains the configuration of an epymorph-style simulation.
RUME.params_description	Provide a description of all attributes required by the RUME.
RUME.estimate_data	Prints a report estimating the data requirements of this RUME.
RUME.requirements_tree	Compute the requirements tree for the given RUME.
RUME.generate_params_dict	Generate a skeleton dictionary you can use to provide parameter values to the RUME.
RUME.evaluate_params	Evaluates the parameters of this RUME.
RUME.initialize	Evaluates the Initializer(s) for this RUME.
RUME.symbols	Convenient function to retrieve the symbols used to represent simulation quantities.
SingleStrataRUME	A RUME with a single strata.
SingleStrataRUME.build	Create a RUME with a single strata.
MultiStrataRUME	A RUME with multiple strata.
MultiStrataRUME.build	Create a multistrata RUME by combining one GPM per strata. Using this function directly is not the recommended workflow for creating a multistrata RUME; see MultiStrataRUMEBuilder.
MultiStrataRUMEBuilder	Declare a multi-strata RUME by combining GPMs, one for each strata.
MultiStrataRUMEBuilder.meta_edges	When implementing a MultiStrataRumeBuilder, override this method to build the meta-transition-edges – the edges which represent cross-strata interactions. You are given a reference to this model’s symbols library so you can build expressions for the transition rates.
MultiStrataRUMEBuilder.build	Complete the RUME definition and construct an instance.
GPM	A GPM (short for Geo-Population Model) combines an IPM, MM, and initialization scheme. Most often, a GPM is used to define one strata in a multi-strata RUME.
GEO_LABELS	A special attribute which, if provided to a RUME (“meta::geo::label”), will be used as labels for the geo node. Otherwise labels will be taken from the geo scope.

epymorph.simulator.basic

Run forward simulations.

basic_simulator.BasicSimulator	A simulator for running singular simulation passes and producing time-series output. The most basic simulator!
basic_simulator.BasicSimulator.run	Run a forward simulation on the RUME and produce one realization (output).
output.Output	The output of a simulation run, including compartment data for all locations and all IPM compartments and event data for all locations and all IPM events.

epymorph.compartment_model

Specify disease models.

CompartmentModel	A compartment model definition and its corresponding metadata. Effectively, a collection of compartments, transitions between compartments, and the data parameters which are required to compute the transitions.
CompartmentModel.diagram	Render a diagram of this IPM, either by showing it with matplotlib (default) or by saving it to file as a png image.
CompartmentModel.edges	When implementing a CompartmentModel, override this method to define the transition edges between compartments.
ModelSymbols	IPM symbols needed in defining the model’s transition rate expressions.
ModelSymbols.compartments	Select compartment symbols by name.
ModelSymbols.requirements	Select requirement symbols by name.
CompartmentDef	Defines an IPM compartment.
CompartmentDef.with_strata	Return a copy of this compartment with the strata changed.
CompartmentName	The name of a compartment, which may have subscript and strata parts.
CompartmentName.parse	Parses a string as a CompartmentName. If the name contains no underscores, the entire name is the base name. If the name contains at least one underscore, the part before the first underscore is the base name and everything after is the subscript part. It is not possible to create a stratified name this way.
CompartmentName.with_subscript	Return a copy of this name with the subscript changed.
CompartmentName.with_strata	Return a copy of this name with the strata changed.
compartment	Define an IPM compartment. Convenience constructor for CompartmentDef.
EdgeDef	Defines a single edge transitions in a compartment model.
EdgeName	The name of a transition edge, from one compartment to another.
EdgeName.with_subscript	Return a copy of this edge with the subscript changed.
EdgeName.with_strata	Return a copy of this edge with the strata changed.
edge	Define a transition edge from one compartment to another at the given rate.
ForkDef	Defines a fork-style transition in a compartment model.
fork	Define a forked transition: a set of edges that come from the same compartment but go to different compartments. It is assumed the edges will share a “base rate”– a common sub-expression among all edge rates – and that each edge in the fork is given a proportion on that base rate.
TransitionDef	All ways to define a compartment model transition: edges or forks.
BIRTH	An IPM psuedo-compartment representing exogenous input of individuals. This is useful in defining IPM edges.
DEATH	An IPM psuedo-compartment representing exogenous removal of individuals. This is useful in defining IPM edges.
CombinedCompartmentModel	A CompartmentModel constructed by combining others for use in multi-strata models. Typically you will not have to create a CombinedCompartmentModel directly. Building a MultiStrataRUME will combine the models for you.
CombinedCompartmentModel.diagram	Render a diagram of this IPM, either by showing it with matplotlib (default) or by saving it to file as a png image.
MultiStrataModelSymbols	IPM symbols needed in defining the model’s transition rate expressions.
MultiStrataModelSymbols.strata_compartments	Select compartment symbols by name in a particular strata. If names is non-empty, select those symbols by their original name. If names is empty, return all symbols.
MultiStrataModelSymbols.strata_requirements	Select requirement symbols by name in a particular strata. If names is non-empty, select those symbols by their original name. If names is empty, return all symbols.
MetaEdgeBuilder	The type of a function for creating meta edges in a multistrata RUME.
BaseCompartmentModel	Shared base-class for compartment models.
BaseCompartmentModel.diagram	Render a diagram of this IPM, either by showing it with matplotlib (default) or by saving it to file as a png image.
QuantitySelector	A utility class for selecting a subset of IPM quantities. Most of the time you obtain one of these using CompartmentModel’s select property.
QuantitySelector.all	Select all compartments and events.
QuantitySelector.indices	Select quantities by index (determined by IPM definition order: all IPM compartments, all IPM events, and then meta edge events if any).
QuantitySelector.by	Select compartments and events by providing pattern strings for each.
QuantitySelector.compartments	Select compartments with zero or more pattern strings.
QuantitySelector.events	Select events with zero or more pattern strings.
QuantityStrategy	A strategy for dealing with the quantity axis, e.g., in processing results. Quantities here are an IPM’s compartments and events. Strategies can include selection of a subset, grouping, and aggregation.
QuantitySelection	A kind of QuantityStrategy describing a sub-selection of IPM quantities (its events and compartments). A selection performs no grouping or aggregation.
QuantitySelection.group	Groups quantities according to the given options.
QuantityGroup	A kind of QuantityStrategy describing a group operation on IPM quantities, with an optional sub-selection.
QuantityGroup.agg	Combine grouped quantities using the named aggregation.
QuantityGroup.sum	Combine grouped quantities by adding their values.
QuantityAggregation	A kind of QuantityStrategy describing a group-and-aggregate operation on IPM quantities, with an optional sub-selection.
Quantity	The type of a quantity referenced by a QuantityStrategy.
QuantityGrouping	Describes how to group simulation output quantities (events and compartments). The default combines any quantity whose names match exactly. This is common in multistrata models where events from several strata impact one transition. You can also choose to group across strata and subscript differences. Setting strata or subscript to True means those elements of quantity names (if they exist) are ignored for the purposes of matching.
QuantityAggMethod	The supported methods for aggregating IPM quantities.

epymorph.movement_model

Specify movement models.

MovementModel	A MovementModel (MM) describes a pattern of geospatial movement for individuals in the model. The MM chops the day up into one or more parts (tau steps), and then describes movement clauses which trigger for certain parts of the day.
MovementClause	A movement clause is basically a function which calculates how many individuals should move between all of the geo nodes, and then epymorph decides by random draw which individuals move (as identified by their disease status, or IPM compartment). It also has various settings which determine when the clause is active (for example, only move people Monday-Friday at the start of the day) and when the individuals that were moved by the clause should return home (for example, stay for two days and then return at the end of the day).
MovementClause.evaluate	Implement this method to provide logic for the clause. Your implementation is free to use data, dim, and rng. You can also use defer to utilize another MovementClause instance.
MovementClause.is_active	Should this movement clause be applied this tick?

epymorph.tools

Process and visualize simulation results.

out_plot.PlotRenderer	Provides methods for rendering an output in plot form.
out_plot.PlotRenderer.line	Renders a line plot using matplotlib showing the given selections.
out_plot.PlotRenderer.line_plt	Draws lines onto the given matplotlib Axes to show the given selections. This is a variant of the method line() that gives you more control over the rendering of a plot by letting you do most of the work with matplotlib’s API.
out_map.MapRenderer	Provides methods for rendering an output in choropleth map form.
out_map.MapRenderer.choropleth	Renders a choropleth map using GeoPandas and matplotlib showing the given selections.
out_map.MapRenderer.choropleth_plt	Draws a choropleth map onto the given matplotlib Axes showing the given selections. This is a variant of the method choropleth() that gives you more control over the rendering of a plot by letting you do most of the work with matplotlib’s API. See that method for conditions that must be met to use this method effectively.
out_map.MapRenderer.geography	Calculate the GeoDataFrame for the given geo axis strategy, without merging any simulation data.
out_map.MapRenderer.geography_data	Calculate the GeoDataFrame used for drawing maps merged with the output data from the given axis strategies.
out_map.NodeLabelRenderer	A class for rendering text labels on choropleth maps. The default implementation is very simple, but you may override this class to customize.
out_map.NodeLabelRenderer.coords	Determine where to draw the labels.
out_map.NodeLabelRenderer.labels	Determine the text of each label.
out_map.NodeLabelRenderer.colors	Determine the color of each label.
out_map.NodeLabelRenderer.additional_kwargs	Determine extra keyword arguments to pass to the annotate() method for each label.
out_map.NodeLabelRenderer.render	Render labels onto the given matplotlib.axes.Axes.
out_table.TableRenderer	Provides a number of methods for rendering an output in tabular form.
out_table.TableRenderer.quantiles	Renders a table showing time-series quantiles for the given selections.
out_table.TableRenderer.range	Renders a table showing minimum and maximum values over time for the given selections. This is equivalent to calling quantiles() with 0 and 1.
out_table.TableRenderer.sum	Renders a table showing summed values over time for the given selections.
out_table.TableRenderer.chart	Renders a table showing a rough time series bar chart for the given selections using ASCII characters.

epymorph.time

Deal with time in epymorph.

TimeFrame	The time frame of a simulation.
DateRange	Like range but for dates, with an optional fixed interval between dates.

epymorph.attribute

Data attributes in epymorph.

AttributeDef	The definition of a data attribute.
ModuleNamespace	A namespace with a specified strata and module.
AbsoluteName	A fully-specified name (strata, module, and attribute ID).
ModuleName	A partially-specified name with module and attribute ID.
AttributeName	A partially-specified name with just an attribute ID.
NamePattern	A name with a strata, module, and attribute ID that allows wildcards (*) so it can act as a pattern to match against AbsoluteNames.
ModuleNamePattern	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.

epymorph.params

Functions for generating model parameters.

ParamSymbol	The names of common symbols used in epymorph simulation expressions. For example, building a ParamExpressionTimeAndNode may make use of these symbols.
simulation_symbols	Convenient function to retrieve the symbols used to represent simulation quantities.