The Values System

The values system provides an interface to an alternative representation of state in the simulation: pipelines. Pipelines are dynamically calculated values that can be constructed across multiple components. This ability for multiple components to together compose a single value is the biggest advantage pipelines provide over the standard state representation of the population state table.

Note

You should use the values system when you have a value that must be composed across multiple components.

What are pipelines?

We can visualize a pipeline as the following:

../_images/pipeline.jpg

At the left, we have the original source of the pipeline. This is a callable registered by a single component that returns a dataframe. To this source, additional components can register modifiers. These modifiers are also callables that return dataframes.

The source and modifiers are composed into a single value by the combiner with which the pipeline is registered. The combiner is also a callable that returns a dataframe - it is the function that dictates how the dataframe produced by the source and the dataframes produced by the modifiers will be combined into a single dataframe. The combiner also determines the required signatures of modifiers in relation to the source. The values system provides three options for combiners, detailed in the following table.

Pipeline Combiners
Combiner Description Modifier Signature
Replace
Replaces the output of the source or modifier with the output of the
next modifier. This is the default combiner if none is specified on
pipeline registration.
Arguments for the modifiers should be the same as the source with an
additional last argument of the results of the previous modifier.
List
The output of the source should be a list to which the results of the
modifiers are appended.
Modifiers should have the same signature as the source.

Pipelines may also optionally be registered with a postprocessor. This is a callable that returns a dataframe that will be called on the output of the combiner to do some postprocessing.

Pipeline Post-processors
Post-processor Description
Rescale
Used for pipelines that produce rates. Rescales the rates to the
size of the time step. Rates provided by source and modifiers are
presumed to be annual.
Union
Used for pipelines that produce independent proportions or
probabilities. Combines values in a way that is consistent with a
union of the underlying sample space

The values system also inverts the direction of control from information that is stored in the state table. Components that update columns in the state table can be seen as “pushing” that information out. Pipelines, however, are “pulled” on by components, often components that did not play any part in the construction of the pipeline value.

How to use pipelines

The values system provides four interface methods, available off the builder during setup.

Values System Interface Methods
Method Description
Register a new pipeline with the values system. Provide a name for the
pipeline and a source. Optionally provide a combiner (defaults to
the replace combiner) and a postprocessor. Provide dependencies (see note).
A special case of register_value_producer() for rates specifically.
Provide a name for the pipeline and a source and the values system will
automatically use the rescale postprocessor. Provide dependencies (see note).
Register a modifier to a pipeline. Provide a name for the pipeline to
modify and a modifier callable. Provide dependencies (see note).
Retrieve a reference to the pipeline with the given name.

Note

The registration methods for the values system require dependencies be specified in order for the resource manager to properly order and manage dependencies. These dependencies are the state table columns, other pipelines, and randomness streams that the source or modifier callable uses in producing the dataframe it returns.

For a view of the values system in action, see the disease model tutorial, specifically the mortality component.