Values Interface

This module provides a ValuesInterface class with methods to register different types of value and attribute producers and modifiers.

class vivarium.engine.framework.values.interface.ValuesInterface(manager)[source]

Public interface for the simulation values management system.

The values system provides tools to build up values across many components, allowing users to build components that focus on small groups of simulation variables.

Notes

This is the only public interface for the values system; different methods exist for working with generic value Pipelines and AttributePipelines.

Parameters:: manager (ValuesManager)

register_value_producer(value_name, source, required_resources=(), preferred_combiner=<function replace_combiner>, preferred_post_processor=())[source]

Registers a Pipeline as the producer of a named value.

Return type:

Pipeline

Parameters:

value_name (str) – The name of the new dynamic value pipeline.
source (Callable[[...], Any]) – A callable source for the dynamic value pipeline.
required_resources (Sequence[str | Resource]) – A list of resources that the producer requires. A string represents a population attribute.
preferred_combiner (ValueCombiner) – 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.engine.framework.values. Client code may define additional strategies as necessary.
preferred_post_processor (PostProcessor | Sequence[PostProcessor]) – 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.engine.framework.values. Client code may define additional strategies as necessary. If a sequence of post processors is provided, they will be applied in the order they are provided.

Returns:

The Pipeline that is registered as the producer of the named value.

register_attribute_producer(value_name, source, required_resources=(), preferred_combiner=<function replace_combiner>, preferred_post_processor=(), source_is_private_column=False)[source]

Registers an AttributePipeline as the producer of a named attribute.

Parameters:

value_name (str) – The name of the new dynamic attribute pipeline.
source (Callable[[pd.Index[int]], Any] | list[str]) – The source for the dynamic attribute pipeline. This can be a callable, a list containing a single name of a private column created by this component, or a list of population attributes. If a private column name is passed, source_is_private_column must also be set to True.
required_resources (Sequence[str | Resource]) – A list of resources that the producer requires. A string represents a population attribute.
preferred_combiner (ValueCombiner) – 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.engine.framework.values. Client code may define additional strategies as necessary.
preferred_post_processor (AttributePostProcessor | Sequence[AttributePostProcessor]) – 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.engine.framework.values. Client code may define additional strategies as necessary. If a sequence of post processors is provided, they will be applied in the order they are provided.
source_is_private_column (bool) – Whether or not the source is the name of a private column created by this component.

Return type:

None

register_rate_producer(rate_name, source, required_resources=(), preferred_combiner=<function replace_combiner>, preferred_post_processor=())[source]

Registers an AttributePipeline as the producer of a named rate.

This is a convenience wrapper around register_attribute_producer that makes sure rate data is appropriately scaled to the size of the simulation time step. It is equivalent to calling register_attribute_producer() with the rescale_post_processor as the preferred post processor.

Parameters:

rate_name (str) – The name of the new dynamic rate pipeline.
source (Callable[[pd.Index[int]], Any] | list[str]) – The source for the dynamic rate pipeline. This can be a callable or a list of column names. If a list of column names is provided, the component that is registering this attribute producer must be the one that creates those columns.
required_resources (Sequence[str | Resource]) – A list of resources that the producer requires. A string represents a population attribute.
preferred_combiner (ValueCombiner) – 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.engine.framework.values. Client code may define additional strategies as necessary.
preferred_post_processor (AttributePostProcessor | Sequence[AttributePostProcessor]) – A strategy for processing the final output of the pipeline. These will be applied after the rescale_post_processor has been applied first. vivarium provides the strategy union_post_processor which is importable from vivarium.engine.framework.values. Client code may define additional strategies as necessary. If a sequence of post processors is provided, they will be applied in the order they are provided.

Return type:

None

register_value_modifier(value_name, modifier, required_resources=())[source]

Marks a Callable as the modifier of a named value.

Return type:

None

Parameters:

value_name (str) – The name of the dynamic value Pipeline to be modified.
modifier (Callable[[...], Any]) – A function that modifies the source of the dynamic value Pipeline when called. If the pipeline has a replace_combiner, the modifier must have 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.
required_resources (Sequence[str | Resource]) – A list of resources that the producer requires. A string represents a population attribute.

register_attribute_modifier(value_name, modifier, required_resources=())[source]

Marks a Callable as the modifier of a named attribute.

Return type:

None

Parameters:

value_name (str) – The name of the dynamic AttributePipeline to be modified.
modifier (Callable[[...], Any] | str) – A function that modifies the source of the dynamic AttributePipeline when called. If a string is passed, it refers to the name of an AttributePipeline. 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.
required_resources (Sequence[str | Resource]) – A list of resources that the producer requires. A string represents a population attribute.

get_value(name)[source]

Retrieves the Pipeline representing the named value.

Return type:: Pipeline
Parameters:: name (str) – Name of the Pipeline to return.
Returns:: The requested Pipeline.

Notes

This will create a new Pipeline if one does not already exist.

get_attribute_pipelines()[source]

Returns a Callable that retrieves a dictionary of AttributePipelines.

Return type:: Callable[[], dict[str, AttributePipeline]]
Returns:: A Callable that returns a dictionary mapping all registered attribute names to their corresponding AttributePipelines.

Notes

This is not the preferred access method to getting population attributes since it does not implement various features (e.g. querying, simulant tracking, etc); it exists for other managers to use if needed. Use vivarium.engine.framework.population.population_view.PopulationView.get() or vivarium.engine.framework.population.population_view.PopulationView.get_frame() instead.