The Value Pipeline System

The value pipeline system is a vital part of the vivarium infrastructure. It allows for values that determine the behavior of individual simulants to be constructed across across multiple components.

For more information about when and how you should use pipelines in your simulations, see the value system concept note.

exception vivarium.framework.values.DynamicValueError

Indicates an improperly configured value was invoked.

vivarium.framework.values.replace_combiner(value, mutator, *args, **kwargs)

Replace the previous pipeline output with the output of the mutator.

This is the default combiner.

Parameters:

• value (Any) – The value from the previous step in the pipeline.

• mutator (Callable) – A callable that takes in all arguments that the pipeline source takes in plus an additional last positional argument for the value from the previous stage in the pipeline.

• args (Any) – The same args and kwargs provided during the invocation of the pipeline.

• kwargs (Any) – The same args and kwargs provided during the invocation of the pipeline.

Returns:

A modified version of the input value.

Return type:

Any

vivarium.framework.values.list_combiner(value, mutator, *args, **kwargs)

Aggregates source and mutator output into a list.

This combiner is meant to be used with a post-processor that does some kind of reduce operation like summing all values in the list.

Parameters:

• value (List) – A list of all values provided by the source and prior mutators in the pipeline.

• mutator (Callable) – A callable that returns some portion of this pipeline’s final value.

• args (Any) – The same args and kwargs provided during the invocation of the pipeline.

• kwargs (Any) – The same args and kwargs provided during the invocation of the pipeline.

Returns:

• The input list with new mutator portion of the pipeline value

• appended to it.

Return type:

List

vivarium.framework.values.rescale_post_processor(value, manager)

Rescales annual rates to time-step appropriate rates.

This should only be used with a simulation using a DateTimeClock or another implementation of a clock that traffics in pandas date-time objects.

Parameters:

• value (ndarray | Series | DataFrame | Number) – Annual rates, either as a number or something we can broadcast multiplication over like a numpy array or pandas data frame.

• time_step – A pandas time delta representing the size of the upcoming time step.

• manager (ValuesManager) –

Returns:

The annual rates rescaled to the size of the current time step size.

Return type:

Union[numpy.ndarray, pandas.Series, pandas.DataFrame, numbers.Number]

vivarium.framework.values.union_post_processor(values, _)

Computes a probability on the union of the sample spaces in the values.

Given a list of values where each value is a probability of an independent event, this post processor computes the probability of the union of the events.

\(p_x\)	Probability of event x
\(1 - p_x\)	Probability of not event x
\(\prod_x(1 - p_x)\)	Probability of not any events x
\(1 - \prod_x(1 - p_x)\)	Probability of any event x

Parameters:

values (List[ndarray | Series | DataFrame | Number]) – A list of independent proportions or probabilities, either as numbers or as a something we can broadcast addition and multiplication over.

Returns:

The probability over the union of the sample spaces represented by the original probabilities.

Return type:

Union[numpy.ndarray, pandas.Series, pandas.DataFrame, numbers.Number]

class vivarium.framework.values.Pipeline

A tool for building up values across several components.

Pipelines are lazily initialized so that we don’t have to put constraints on the order in which components are created and set up. The values manager will configure a pipeline (set all of its attributes) when the pipeline source is created.

As long as a pipeline is not actually called in a simulation, it does not need a source or to be configured. This might occur when writing generic components that create a set of pipeline modifiers for values that won’t be used in the particular simulation.

name

The name of the value represented by this pipeline.

source

A callable source for this pipeline’s value.

mutators

A list of callables that directly modify the pipeline source or contribute portions of the value.

combiner

A strategy for combining the source and mutator values into the final value represented by the pipeline.

post_processor

An optional final transformation to perform on the combined output of the source and mutators.

manager

A reference to the simulation values manager.

class vivarium.framework.values.ValuesManager

Manager for the dynamic value system.

property name

setup(builder)

on_post_setup(_)

Finalizes dependency structure for the pipelines.

register_value_producer(value_name, source, requires_columns=(), requires_values=(), requires_streams=(), preferred_combiner=<function replace_combiner>, preferred_post_processor=None)

Marks a Callable as the producer of a named value.

Parameters:

• value_name (str) –

• source (Callable) –

• requires_columns (List[str]) –

• requires_values (List[str]) –

• requires_streams (List[str]) –

• preferred_combiner (Callable) –

• preferred_post_processor (Callable) –

Return type:

Pipeline

register_value_modifier(value_name, modifier, requires_columns=(), requires_values=(), requires_streams=())

Marks a Callable as the modifier of a named value.

Parameters:

• value_name (str) – The name of the dynamic value pipeline to be modified.

• modifier (Callable) – A function that modifies the source of the dynamic value pipeline when called. If the pipeline has a replace_combiner, the modifier should accept the same arguments as the pipeline source with an additional last positional argument for the results of the previous stage in the pipeline. For the list_combiner strategy, the pipeline modifiers should have the same signature as the pipeline source.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the pipeline modifier is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the pipeline modifier is called.

• requires_streams (List[str]) – A list of the randomness streams that need to be properly sourced before the pipeline modifier is called.

get_value(name)

Retrieve the pipeline representing the named value.

Parameters:

name – Name of the pipeline to return.

Returns:

• A callable reference to the named pipeline. The pipeline arguments

• should be identical to the arguments to the pipeline source

• (frequently just a pandas.Index representing the

• simulants).

keys()

Get an iterable of pipeline names.

Return type:

Iterable[str]

items()

Get an iterable of name, pipeline tuples.

Return type:

Iterable[Tuple[str, Pipeline]]

values()

Get an iterable of all pipelines.

Return type:

Iterable[Pipeline]

class vivarium.framework.values.ValuesInterface(manager)

Public interface for the simulation values management system.

The values system provides tools to build up a value across many components, allowing users to build components that focus on small groups of simulant attributes.

Parameters:

manager (ValuesManager) –

register_value_producer(value_name, source, requires_columns=(), requires_values=(), requires_streams=(), preferred_combiner=<function replace_combiner>, preferred_post_processor=None)

Marks a Callable as the producer of a named value.

Parameters:

• value_name (str) – The name of the new dynamic value pipeline.

• source (Callable) – A callable source for the dynamic value pipeline.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the pipeline source is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the pipeline source is called.

• requires_streams (List[str]) – A list of the randomness streams that need to be properly sourced before the pipeline source is called.

• preferred_combiner (Callable) – A strategy for combining the source and the results of any calls to mutators in the pipeline. vivarium provides the strategies replace_combiner (the default) and list_combiner, which are importable from vivarium.framework.values. Client code may define additional strategies as necessary.

• preferred_post_processor (Callable) – A strategy for processing the final output of the pipeline. vivarium provides the strategies rescale_post_processor and union_post_processor which are importable from vivarium.framework.values. Client code may define additional strategies as necessary.

Returns:

A callable reference to the named dynamic value pipeline.

Return type:

Pipeline

register_rate_producer(rate_name, source, requires_columns=(), requires_values=(), requires_streams=())

Marks a Callable as the producer of a named rate.

This is a convenience wrapper around register_value_producer that makes sure rate data is appropriately scaled to the size of the simulation time step. It is equivalent to register_value_producer(value_name, source, preferred_combiner=replace_combiner, preferred_post_processor=rescale_post_processor)

Parameters:

• rate_name (str) – The name of the new dynamic rate pipeline.

• source (Callable) – A callable source for the dynamic rate pipeline.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the pipeline source is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the pipeline source is called.

• requires_streams (List[str]) – A list of the randomness streams that need to be properly sourced before the pipeline source is called.

Returns:

A callable reference to the named dynamic rate pipeline.

Return type:

Pipeline

register_value_modifier(value_name, modifier, requires_columns=(), requires_values=(), requires_streams=())

Marks a Callable as the modifier of a named value.

Parameters:

• value_name (str) – The name of the dynamic value pipeline to be modified.

• modifier (Callable) – A function that modifies the source of the dynamic value pipeline when called. If the pipeline has a replace_combiner, the modifier should accept the same arguments as the pipeline source with an additional last positional argument for the results of the previous stage in the pipeline. For the list_combiner strategy, the pipeline modifiers should have the same signature as the pipeline source.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the pipeline modifier is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the pipeline modifier is called.

• requires_streams (List[str]) – A list of the randomness streams that need to be properly sourced before the pipeline modifier is called.

get_value(name)

Retrieve the pipeline representing the named value.

Parameters:

name (str) – Name of the pipeline to return.

Returns:

• A callable reference to the named pipeline. The pipeline arguments

• should be identical to the arguments to the pipeline source

• (frequently just a pandas.Index representing the

• simulants).

Return type:

Pipeline