modelrunner.run.results module

Classes that describe results of simulations of models.

class MockModel(parameters=None)

Bases: ModelBase

Helper class to store parameter values when the original model is not present.

Parameters:

parameters (dict) – A dictionary of parameters

class Result(model, result, *, storage=None, info=None)

Bases: object

Describes the result of a single model run together with auxillary information.

Besides storing the final outcome of the model in result, the class also stores information about the original model in model, additional information in info, and potentially arbitrary objects that were added during the model run in storage.

Note

The result is represented as a hierarchical structure when safed using the storage. The actual result is stored in the result group, whereas the model information can be found in _model group. Additional information is stored in the storage group. Thus, the full Result can be read using storage[loc], where loc denotes the result location. If only the actual result is needed, storage[loc + "/result"] can be read.

Parameters:

• model (ModelBase) – The model from which the result was obtained

• result (Any) – The actual result

• storage (StorageGroup | None) – A storage containing additional data from the model run

• info (dict) – Additional information for this result

property data

Direct access to the underlying state data.

classmethod from_data(model_data, result, *, model=None, storage=None, info=None)

Create result from data.

Parameters:

• model_data (dict) – The data identifying the model

• result – The actual result data

• model (ModelBase) – The model from which the result was obtained

• storage (StorageGroup | None) – A storage containing additional data from the model run

• info (dict) – Additional information for this result

Returns:

The result object

Return type:

Result

classmethod from_file(storage, loc=None, *, model=None)

Load object from a file.

This function loads the results from a hierachical storage. It also attempts to read information about the model that was used to create this result and additional data that might have been stored in a storage while the model was running.

Parameters:

• store (str or zarr.Store) – Path or instance describing the storage, which is either a file path or a zarr.Storage.

• loc (str | Sequence[Location] | None) – The location where the result is stored in the storage. This should rarely be modified.

• model (ModelBase) – The model which lead to this result

• storage (str | Path | StorageGroup | StorageBase | None)

info: dict[str, Any] | None

Additional information for this result

Type:

dict

model: ModelBase

Model that was run.

This is a MockModel instance if details are not available

Type:

ModelBase

property parameters: dict[str, Any]

result: Any

The final outcome of the model.

storage: StorageGroup | None

Storage that might contain additional information, e.g., stored during the model run.

Type:

StorageGroup

to_file(storage, loc=None, *, mode='insert')

Write the results to a file.

Note that this does only write the actual results but omits additional data that might have been stored in a storage that is associated with the results.

Parameters:

• storage (StorageBase or StorageGroup) – The storage where the group is defined. If this is a StorageGroup itself, loc is interpreted relative to that group

• loc (str or list of str) – Denotes the location (path) of the group within the storage

• mode (str or ModeType) – The file mode with which the storage is accessed, which determines the allowed operations. Common options are “read”, “full”, “append”, and “truncate”.

Return type:

None

class ResultCollection(iterable=(), /)

Bases: list[Result]

Represents a collection of results.

as_dataframe(*, enforce_same_model=True, drop_keys=None)

Create a pandas dataframe summarizing the data.

Parameters:

• enforce_same_model (bool) – If True, forces all model results to derive from the same model

• drop_keys (sequence) – A list of items that will not be included in the final data frame

property constant_parameters: dict[str, Any]

the parameters that are constant in this result collection

Type:

dict

filtered(**kwargs)

Return a subset of the results.

Parameters:

**kwargs – Specify parameter values of results that are retained

Returns:

The filtered collection

Return type:

ResultColelction

classmethod from_folder(folder, pattern='*.*', model=None, *, strict=False, progress=False)

Create results collection from a folder.

Parameters:

• folder (str) – Path to the folder that is scanned

• pattern (str) – Filename pattern that is used to detect result files

• model (ModelBase) – Base class from which models are initialized

• strict (bool) – Whether to raise an exception or just emit a warning when a file cannot be read

• progress (bool) – Flag indicating whether a progress bar is shown

get(**kwargs)

Return a single result with the given parameters.

Warning

If there are multiple results compatible with the specified parameters, only the first one is returned.

Parameters:

**kwargs – Specify parameter values of result that is returned

Returns:

A single result from the collection

Return type:

Result

groupby(*args)

Group results according to the given variables.

Parameters:

*args – Specify parameters according to which the results are sorted

Returns:

generator that allows iterating over the groups. Each iteration returns a dictionary with the current parameters and the associated ResultCollection.

Return type:

Iterator[tuple[dict[str, list[Any]], ResultCollection]]

property parameters: dict[str, set[Any]]

the parameter values in this result collection

Note that parameters that are lists in the individual models are turned into tuples, so they can be handled efficiently, e.g., in sets.

Type:

dict

remove_duplicates()

Remove duplicates in the result collection.

Return type:

ResultCollection

property same_model: bool

flag determining whether all results are from the same model

Type:

bool

sorted(*args, reverse=False)

Return a sorted version of the results.

Parameters:

• *args – Specify parameters according to which the results are sorted

• reverse (bool) – If True, sort in descending order

Returns:

The filtered collection

Return type:

ResultColelction

property varying_parameters: dict[str, list[Any]]

the parameters that vary in this result collection

Type:

dict