The ParamSpaceGroup

The ParamSpaceGroup is a group where each member is assumed to be a point in a multi-dimensional parameter space.

For the representation of the parameter space, the paramspace package (see here) is used. Subsequently, a ParamSpaceGroup is associated with a paramspace.ParamSpace object, which maps the members of the group to states in the parameter space.

Each member of the group (i.e.: each state of the parameter space) is represented by a ParamSpaceStateGroup, which ensures that the name of the group is a valid state name.

Usage Example

This usage example shows how a ParamSpaceGroup is populated and used.

First, let’s define a parameter space, in this case a two-dimensional one that goes over the parameters beta and seed. (For more information on usage of the paramspace package, consult its documentation).

# Define a 2D parameter space (typically done from a YAML file)
from paramspace import ParamSpace, ParamDim

all_params = {
    "some_parameter": "foo",
    "more_parameters": {
        "spam": "fish",
        "beta": ParamDim(default=1., values=[.01, .03, .1, .3, 1.]),
    },
    "seed": ParamDim(default=42, range=[20]),
}

pspace = ParamSpace(all_params)

Now, let’s set up a ParamSpaceGroup and populate it (with some random data in this case):

import numpy as np
import xarray as xr

from dantro.groups import ParamSpaceGroup
from dantro.containers import XrDataContainer

pspgrp = ParamSpaceGroup(name="my_parameter_sweep", pspace=pspace)

for params, state_no_str in pspace.iterator(with_info='state_no_str'):
    # Create a ParamSpaceState group, using the state number as name
    pss = pspgrp.new_group(state_no_str)

    # Populate the state group with some data (with labelled dimensions)
    some_data = xr.DataArray(data=np.random.random((2,3,4)),
                             dims=('foo', 'bar', 'baz'),
                             coords=dict(foo=[0, 1],
                                         bar=[0, 10, 20],
                                         baz=[.1, .2, .4, .8]))
    pss.add(XrDataContainer(name="some_data", data=some_data))

The pspgrp is now populated and ready to use.

Hint

For instructions on how to load data from files into a ParamSpaceGroup, see the examples in the integration guide.

On top of the capabilities of a regular group like iteration, the individual members can query their coordinates within the parameter space. Furthermore, it also supplies the select() method, with which data from the parameter states can be combined into a higher-dimensional object. The resulting object then has the parameter space dimensions plus the data dimensions:

# We now have fully populated group, associated with the 2D parameter space
assert pspgrp.pspace.num_dims == 2
assert pspgrp.pspace.volume == 5 * 20
assert len(pspgrp) == pspgrp.pspace.volume

# We can iterate over it, as usual
for pss in pspgrp.values():
    # ^- the ParamSpaceStateGroup for a specific state
    # ... and the states know their coordinates in the parameter space
    print("Point in parameter space: ", pss.coords)

# Also, we can combine the data inside the group into a higher-dimensional
# object using the select method:
all_data = pspgrp.select(field="some_data")

# ... should now have 5 dimensions: 3 data dimensions + 2 pspace dimensions
assert all_data["some_data"].ndim == 5
assert set(all_data["some_data"].coords.keys()) == {"foo", "bar", "baz",
                                                    "seed", "beta"}

Importantly, having data available in this structure allows to conveniently create plots for each point in parameter space using the plot creators specialized for this purpose.