The Component Configuration Parser
The ComponentConfigurationParser
is responsible for taking a list or
hierarchical ConfigTree
of components
derived from a model specification yaml file and turning it into a list of
instantiated component objects. When a model specification yaml file is loaded,
the components come in as strings. In order for the simulation to be able to
use these components, they have to be converted into the actual objects they
represent. This occurs via the get_components
method of the parser, which is
used anytime a simulation is initialized from a model specification file.
There are three steps to this process.
Parsing the model specification’s components
Validating the arguments and prepping each component
Importing and instantiating the actual components
- exception vivarium.framework.components.parser.ParsingError[source]
Error raised when component configurations are not specified correctly.
- class vivarium.framework.components.parser.ComponentConfigurationParser[source]
Parses component configuration from model specification and initializes components.
To define your own set of parsing rules, you should write a parser class that inherits from this class and overrides
parse_component_config
. You can then define a set of parsing rules that turn component configuration information into a list of strings where each string is the full python import path to the class followed by a set of parentheses containing initialization arguments.For example, say your component configuration specifies
FancyClass
from theimportant_module
of yourmade_up_package
and thatFancyClass
has two initialization parameters,'important_thing1'
and'important_thing2'
. Your implementation ofparse_component_config
needs to generate the string'made_up_package.important_module.FancyClass ("important_thing1", "important_thing2")'
and include it in the list of components to generate.All classes that are initialized from the
yaml
configuration must either take no arguments or take arguments specified as strings.- get_components(component_config)[source]
Extracts component specifications from configuration information and returns initialized components.
This method encapsulates the three steps described above of parsing, validating/prepping, and importing/instantiating.
The first step of parsing is only done for component configurations that come in as a
ConfigTree
. Configurations that are provided in the form of a list are already assumed to be in the correct form.- Parameters:
component_config (ConfigTree | List) – A hierarchical component specification blob. This configuration information needs to be parsable into a full import path and a set of initialization arguments by the
parse_component_config
method.- Returns:
A list of initialized components.
- Return type:
List
- parse_component_config(component_config)[source]
Parses a hierarchical component specification into a list of standardized component definitions.
This default parser expects component configurations as a list of dicts. Each dict at the top level corresponds to a different package and has a single key. This key may be just the name of the package or a Python style import path to the module in which components live. The values of the top level dicts are a list of dicts or strings. If dicts, the keys are another step along the import path. If strings, the strings are representations of calls to the class constructor of components to be generated. This pattern may be arbitrarily nested.
- vivarium.framework.components.parser.parse_component_config_to_list(component_config)[source]
Helper function for parsing hierarchical component configuration into a flat list.
This function recursively walks the component configuration dictionary, treating it like a prefix tree and building the import path prefix. When it hits a list, it prepends the built prefix onto each item in the list. If the dictionary contains multiple lists, the prefix-prepended lists are concated together. For example, a component configuration dictionary like the following:
component_config = { 'vivarium_examples': { 'disease_model': { 'population': ['BasePopulation()', 'Mortality()'] 'disease': ['SIS_DiseaseModel("diarrhea")] } } }
would be parsed by this function into the following list:
['vivarium_examples.disease_model.population.BasePopulation()', 'vivarium_examples.disease_model.population.Mortality()', 'vivarium_examples.disease_model.disease.SIS_DiseaseModel("diarrhea")']
- vivarium.framework.components.parser.prep_components(component_list)[source]
Transform component description strings into tuples of component paths and required arguments.
- vivarium.framework.components.parser.clean_args(args, path)[source]
Transform component arguments into a tuple, validating that each argument is a string.
- vivarium.framework.components.parser.import_and_instantiate_components(component_list)[source]
Transform the list of tuples representing components into the actual instantiated component objects.
- Parameters:
component_list (List[Tuple[str, Tuple[str]]]) – A list of tuples representing components, where the first element of each tuple is a string with the full import path to the component and the component name and the second element is a tuple of the arguments to the component.
- Returns:
A list of instantiated component objects.
- Return type:
List