pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/errorsysfield.py

@@ -0,0 +1,383 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import copy
+from dataclasses import dataclass
+import numpy as np
+from scipy.spatial.transform import Rotation
+
+from pyvale.sensorsim.field import IField
+from pyvale.sensorsim.fieldsampler import sample_field_with_sensor_data
+from pyvale.sensorsim.sensordata import SensorData
+from pyvale.sensorsim.integratortype import EIntSpatialType
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                    EErrType,
+                                    EErrDep)
+from pyvale.sensorsim.errordriftcalc import IDriftCalculator
+from pyvale.sensorsim.generatorsrandom import IGenRandom
+
+# TODO:
+# - Implement different perturbed sampling times for each sensor or allow all
+#   to lock to the same time step as it works now.
+# - Need to check that we perform field rotations correctly for sensor angles.
+#   - This needs to be updated to take rotation objects for offsets and to build
+#     and compose rotations
+
+
+@dataclass(slots=True)
+class ErrFieldData:
+    """Dataclass for controlling sensor parameter perturbations for field based
+    systematic errors (i.e. errors that require interpolation of the physical
+    field).
+    """
+
+    pos_offset_xyz: np.ndarray | None = None
+    """Array of offsets to apply to the sensor positions for error calculation.
+    shape=(num_sensors,3) where the columns represent the X, Y and Z offsets in
+    simulation world coordinates. If None then no position offset is applied.
+    """
+
+    ang_offset_zyx: np.ndarray | None = None
+    """Array of offsets to apply to the sensor angles for error calculation.
+    shape=(num_sensors,3) where the columns represent rotations about offsets
+    about the Z, Y and X axis of the sensor in sensor local coordinates. If None
+    then no angular offsets are applied.
+    """
+
+    time_offset: np.ndarray | None = None
+    """Array of offsets to apply to the sampling times for all sensors. shape=(
+    num_time_steps,). If None then no time offset is applied.
+    """
+
+    pos_rand_xyz: tuple[IGenRandom | None,
+                        IGenRandom | None,
+                        IGenRandom | None] = (None,None,None)
+    """Tuple of random generators (implementations of `IGenRandom`
+    interface) for perturbing the sensor positions. The generators perturb the
+    X, Y and Z coordinates in order. If None then that axis is not randomly
+    perturbed from the nominal sensor position. Note that the random generators
+    should return position perturbations consistent with the simulation units.
+    """
+
+    ang_rand_zyx: tuple[IGenRandom | None,
+                        IGenRandom | None,
+                        IGenRandom | None] = (None,None,None)
+    """Tuple of random generators (implementations of `IGenRandom`
+    interface) for perturbing the sensor angles. The generators perturb
+    rotations about the the Z, Y and X axis  in order. If None then that axis is
+    not randomly perturbed from the nominal sensor position.
+    """
+
+    time_rand: IGenRandom | None = None
+    """Random generator for perturbing sensor array sampling times for the
+    purpose of calculating field based errors. If None then sensor sampling
+    times will not be perturbed from the nominal times.
+    """
+
+    spatial_averager: EIntSpatialType | None = None
+    """Type of spatial averaging to use for this sensor array for the purpose of
+    calculating field based errors. If None then no spatial averaging is
+    performed.
+    """
+
+    spatial_dims: np.ndarray | None = None
+    """The spatial dimension of the sensor in its local X,Y,Z coordinates for
+    the purpose of calculating field errors. Only used if spatial averager is
+    specified above. shape=(3,)
+    """
+
+    pos_lock_xyz: np.ndarray | None = None
+    """Boolean array with shape=(num_sensors,coord[X,Y,Z]), Setting equal to 
+    True will lock the axis for the particular sensor so that it will not have
+    it's position perturbed.
+    """
+    
+    ang_lock_zyx: np.ndarray | None = None
+    """Boolean array with shape=(num_sensors,ang[Z,Y,X]), Setting equal to 
+    True will lock the rotation about that axis for the particular sensor.
+    """
+    
+    # TODO: implement drift for other dimensions, pos/angle
+    time_drift: IDriftCalculator | None = None
+    """Temporal drift calculation
+    """
+
+
+class ErrSysField(IErrSimulator):
+    """Class for calculating field based systematic errors. Field based errors
+    are errors that require interpolation or sampling of the simulated physical
+    field such as perturbations of the sensor position or sampling time.
+
+    All perturbations to the sensor parameters (positions, sample times, angles
+    area averaging) are calculated first before performing a single
+    interpolation with the perturbed sensor state.
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_field","_sensor_data_perturbed","_field_err_data","_err_dep")
+
+    def __init__(self,
+                field: IField,
+                field_err_data: ErrFieldData,
+                err_dep: EErrDep = EErrDep.DEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        field : IField
+            The physical field to interpolate which will be an implementation of
+            the `IField` interface. This will be a `FieldScalar`, `FieldVector`
+            or `FieldTensor` object.
+        field_err_data : ErrFieldData
+            Dataclass specifying which sensor array parameters will be perturbed
+            and how they will be perturbed. See the `ErrFieldData` class for
+            more detail
+        err_dep : EErrDep, optional
+            Error calculation dependence, by default EErrDep.DEPENDENT.
+        """
+        self._field = field
+        self._field_err_data = field_err_data
+        self._err_dep = err_dep
+        self._sensor_data_perturbed = SensorData()
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def get_perturbed_sensor_data(self) -> SensorData:
+        return self._sensor_data_perturbed
+
+    def reseed(self, seed: int | None = None) -> None:        
+        for rr in self._field_err_data.pos_rand_xyz:
+            if rr is not None:
+                rr.reseed(seed)
+
+        for rr in self._field_err_data.ang_rand_zyx:
+            if rr is not None:
+                rr.reseed(seed)
+
+        if self._field_err_data.time_rand is not None:
+            self._field_err_data.time_rand.reseed(seed)
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        self._sensor_data_perturbed = copy.deepcopy(sens_data)
+        self._sensor_data_perturbed.spatial_averager = \
+            self._field_err_data.spatial_averager
+        self._sensor_data_perturbed.spatial_dims = \
+            self._field_err_data.spatial_dims
+
+        self._sensor_data_perturbed.positions = _perturb_sensor_positions(
+            self._sensor_data_perturbed.positions,
+            self._field_err_data.pos_offset_xyz,
+            self._field_err_data.pos_rand_xyz,
+            self._field_err_data.pos_lock_xyz,
+        )
+
+        self._sensor_data_perturbed.sample_times = _perturb_sample_times(
+            self._field.get_time_steps(),
+            self._sensor_data_perturbed.sample_times,
+            self._field_err_data.time_offset,
+            self._field_err_data.time_rand,
+            self._field_err_data.time_drift,
+        )
+
+        self._sensor_data_perturbed.angles = _perturb_sensor_angles(
+            sens_data.positions.shape[0],
+            self._sensor_data_perturbed.angles,
+            self._field_err_data.ang_offset_zyx,
+            self._field_err_data.ang_rand_zyx,
+            self._field_err_data.ang_lock_zyx,
+        )
+
+        sys_errs = sample_field_with_sensor_data(
+            self._field,
+            self._sensor_data_perturbed
+        ) - err_basis
+
+        return (sys_errs,self._sensor_data_perturbed)
+
+
+def _perturb_sensor_positions(sens_pos_nominal: np.ndarray,
+                             pos_offset_xyz: np.ndarray | None,
+                             pos_rand_xyz: tuple[IGenRandom | None,
+                                                 IGenRandom | None,
+                                                 IGenRandom | None] | None,
+                             pos_loc_xyz: np.ndarray | None,
+                            ) -> np.ndarray:
+    """Helper function for perturbing the sensor positions from their nominal
+    positions based on the user specified offset and random generators for each
+    axis.
+
+    Parameters
+    ----------
+    sens_pos_nominal : np.ndarray
+        Nominal sensor positions as an array with shape=(num_sensors,3) where
+        the columns represent the position in the X, Y and Z axes.
+    pos_offset_xyz : np.ndarray | None
+        Offsets to apply to the sensor positions as an array with shape=
+        (num_sensors,3) wherethe columns represent the position in the X, Y and
+        Z axes. If None then no offset is applied.
+    pos_rand_xyz : tuple[IGenRandom  |  None,
+                         IGenRandom  |  None,
+                         IGenRandom  |  None] | None
+        Random generators for sensor position perturbations along the the X, Y
+        and Z axes. If None then no perturbation is applied.
+    pos_loc_xyz : np.ndarray | None
+        Boolean mask with shape=(num_sensors,3), where the mask is true the
+        coordinate is locked and will not perturb based on offset or rand above.
+
+    Returns
+    -------
+    np.ndarray
+        Array of perturbed sensors positions with shape=(num_sensors,3) where
+        the columns represent the position in the X, Y and Z axes.
+    """
+    sens_pos_perturbed = np.copy(sens_pos_nominal)
+
+    if pos_offset_xyz is not None:
+        sens_pos_perturbed = sens_pos_perturbed + pos_offset_xyz
+
+    if pos_rand_xyz is not None:
+        for ii,rng in enumerate(pos_rand_xyz):
+            if rng is not None:
+                sens_pos_perturbed[:,ii] = sens_pos_perturbed[:,ii] + \
+                    rng.generate(shape=sens_pos_perturbed.shape[0])
+
+    if pos_loc_xyz is not None:
+        sens_pos_perturbed[pos_loc_xyz] = sens_pos_nominal[pos_loc_xyz]
+
+    return sens_pos_perturbed
+
+
+def _perturb_sample_times(sim_time: np.ndarray,
+                         time_nominal: np.ndarray | None,
+                         time_offset: np.ndarray | None,
+                         time_rand: IGenRandom | None,
+                         time_drift: IDriftCalculator | None
+                         ) -> np.ndarray | None:
+    """Helper function for calculating perturbed sensor sampling times for the
+    purpose of calculating field based systematic errors.
+
+    Parameters
+    ----------
+    sim_time : np.ndarray
+        Simulation time steps for the underlying physical field.
+    time_nominal : np.ndarray | None
+        Nominal sensor sampling times. If None then the simulation time steps
+        are assumed to be the sampling times.
+    time_offset : np.ndarray | None
+        Array of time offsets to apply to all sensors. If None then no offsets
+        are applied.
+    time_rand : IGenRandom | None
+        Random generator for perturbing the sampling times of all sensors. If
+        None then no random perturbation of sampling times occurs.
+    time_drift : IDriftCalculator | None
+        Drift function for calculating temporal sampling drift. If None then no
+        temporal drift is applied.
+
+    Returns
+    -------
+    np.ndarray | None
+        Array of perturbed sample times
+    """
+    if time_nominal is None:
+        if (time_offset is not None
+            or time_rand is not None
+            or time_drift is not None):
+            time_nominal = sim_time
+        else:
+            return None
+
+    time_perturbed = np.copy(time_nominal)
+
+    if time_offset is not None:
+        time_perturbed = time_perturbed + time_offset
+    if time_rand is not None:
+        time_perturbed = time_perturbed + time_rand.generate(
+            shape=time_nominal.shape)
+    if time_drift is not None:
+        time_perturbed = time_perturbed + time_drift.calc_drift(time_nominal)
+
+    return time_perturbed
+
+
+def _perturb_sensor_angles(n_sensors: int,
+                          angles_nominal: tuple[Rotation,...] | None,
+                          angle_offsets_zyx: np.ndarray | None,
+                          rand_ang_zyx: tuple[IGenRandom | None,
+                                              IGenRandom | None,
+                                              IGenRandom | None] | None,
+                          angle_loc_zyx: np.ndarray | None,
+                          ) -> tuple[Rotation,...] | None:
+    """Helper function for perturbing sensor angles for the purpose of
+    calculating field based systematic errors.
+
+    Parameters
+    ----------
+    n_sensors : int
+        Number of sensors in the sensor array.
+    angles_nominal : tuple[Rotation,...] | None
+        The nominal angles of the sensors as a tuple of scipy Rotation objects.
+        This tuple should have length equal to the number of sensors. If None
+        then an initial orienation of [0,0,0] is assumed.
+    angle_offsets_zyx : np.ndarray | None
+        Angle offsets to apply to the sensor array as an array with shape=(
+        num_sensors,3) where the columns are the rotations about Z, Y and X in
+        degrees. If None then no offsets are applied.
+    rand_ang_zyx : tuple[IGenRandom  |  None,
+                         IGenRandom  |  None,
+                         IGenRandom  |  None] | None
+        Random generators for perturbing sensor angles about the Z, Y and X axis
+        respectively. If None then no random perturbation to the sensor angle
+        occurs.
+    angle_loc_zyx : np.ndarray | None
+        Boolean mask with shape=(num_sensors,3), where the mask is true the
+        angle is locked and the sensor will not rotate about that axis despite
+        the offset of rand generators above,
+
+    Returns
+    -------
+    tuple[Rotation,...] | None
+        Rotation object giving each sensors perturbed angle. If None then the
+        no sensors have had their angles perturbed.
+    """
+    if angles_nominal is None:
+        if angle_offsets_zyx is not None or rand_ang_zyx is not None:
+            angles_nominal = n_sensors * \
+                (Rotation.from_euler("zyx",[0,0,0], degrees=True),)
+        else:
+            return None
+
+    angles_perturbed = [Rotation.from_euler("zyx",[0,0,0], degrees=True)] * \
+        len(angles_nominal)
+    for ii,rot_nom in enumerate(angles_nominal): # loop over sensors
+        # NOTE: adding angles here might not be correct
+        sensor_rot_angs = np.zeros((3,))
+
+        if angle_offsets_zyx is not None:
+            sensor_rot_angs = sensor_rot_angs + angle_offsets_zyx[ii,:]
+
+        if rand_ang_zyx is not None:
+            for jj,rand_ang in enumerate(rand_ang_zyx): # loop over components
+                if rand_ang is not None:
+                    sensor_rot_angs[jj] = sensor_rot_angs[jj] + \
+                        rand_ang.generate(shape=(1,))[0]
+
+        if angle_loc_zyx is not None:
+            # No rotation about locked axes using mask
+            sensor_rot_angs[angle_loc_zyx[ii,:]] = 0.0
+
+        sensor_rot = Rotation.from_euler("zyx",sensor_rot_angs, degrees=True)
+        angles_perturbed[ii] = sensor_rot*rot_nom
+
+    return tuple(angles_perturbed)

pyvale/sensorsim/errorsysindep.py

@@ -0,0 +1,209 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                         EErrType,
+                                         EErrDep)
+from pyvale.sensorsim.generatorsrandom import IGenRandom
+from pyvale.sensorsim.sensordata import SensorData
+
+
+class ErrSysOffset(IErrSimulator):
+    """Systematic error calculator applying a constant offset to all simulated
+    sensor measurements. Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_offset","_err_dep")
+
+    def __init__(self,
+                 offset: float,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        offset : float
+            Constant offset to apply to all simulated measurements from the
+            sensor array.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
+        self._offset = offset
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        return (self._offset*np.ones(shape=err_basis.shape),sens_data)
+
+
+class ErrSysOffsetPercent(IErrSimulator):
+    """Systematic error calculator applying a constant offset as a percentage of
+    the sensor reading to each individual simulated sensor measurement.
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_offset_percent","_err_dep")
+
+    def __init__(self,
+                 offset_percent: float,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        offset_percent : float
+            Percentage offset to apply to apply to all simulated measurements
+            from the sensor array.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT
+        """
+        self._offset_percent = offset_percent
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        return (self._offset_percent/100 *
+                err_basis *
+                np.ones(shape=err_basis.shape),
+                sens_data)
+
+class ErrSysGen(IErrSimulator):
+    """Systematic error calculator for applying a unique offset to each sensor
+    by sample from a user specified probability distribution (an implementation
+    of the `IGeneratorRandom` interface).
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_generator","_err_dep")
+
+    def __init__(self,
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGenRandom
+            Random generator object used to calculate the systematic error in
+            simulation units.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
+        self._generator = generator
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        self._generator.reseed(seed)
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        err_shape = np.array(err_basis.shape)
+        err_shape[-1] = 1
+
+        sys_errs = self._generator.generate(shape=err_shape)
+
+        tile_shape = np.array(err_basis.shape)
+        tile_shape[0:-1] = 1
+        sys_errs = np.tile(sys_errs,tuple(tile_shape))
+
+        return (sys_errs,sens_data)
+
+
+class ErrSysGenPercent(IErrSimulator):
+    """Systematic error calculator for applying a unique percentage offset to
+    each sensor by sample from a user specified probability distribution (an
+    implementation of the `IGeneratorRandom` interface). This class assumes the
+    random generator is for a percentage error based on the input error basis
+    and therefore it supports error dependence.
+
+    The percentage error is calculated based on the ground truth if the error
+    dependence is `INDEPENDENT` or based on the accumulated sensor measurement
+    if the dependence is `DEPENDENT`.
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_generator","_err_dep")
+
+    def __init__(self,
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGenRandom
+            Random generator which returns a percentage error in the range
+            (0,100)
+        err_dep : EErrDep, optional
+            Error calculation dependence, by default EErrDep.INDEPENDENT
+        """
+        self._generator = generator
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        self._generator.reseed(seed)
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        err_shape = np.array(err_basis.shape)
+        err_shape[-1] = 1
+
+        sys_errs = self._generator.generate(shape=err_shape)
+        # Convert percent to decimal
+        sys_errs = sys_errs/100.0
+
+        tile_shape = np.array(err_basis.shape)
+        tile_shape[0:-1] = 1
+        sys_errs = np.tile(sys_errs,tuple(tile_shape))
+        sys_errs = err_basis * sys_errs
+
+        return (sys_errs,sens_data)
+

pyvale/sensorsim/exceptions.py

@@ -0,0 +1,14 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+class VisError(Exception):
+    pass
+
+class Collapse2Dto3DError(Exception):
+    pass
+
+class ExpSimError(Exception):
+    pass

pyvale/sensorsim/experimentsimio.py

@@ -0,0 +1,94 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module contains functions for saving/loading the results of simulated
+experiments with virtual sensor arrays.
+"""
+
+from pathlib import Path
+import numpy as np
+
+
+def save_exp_sim_data(save_file: Path,
+                      exp_data: dict[tuple[str,...],np.ndarray]) -> None:
+    """Saves the results of a simulated experiment to disk.
+
+    Parameters
+    ----------
+    save_file : Path
+        Path including file name to where the simulated experiment data should 
+        be saved.
+    exp_data : dict[tuple[str,...],np.ndarray]
+        The simulated experiment data dictionary to save.
+    """
+
+    flat_keys = []
+    key_lens = []        
+    save_dict = {}
+    for kk,vv in exp_data.items():
+        key_lens.append(len(kk))
+        for ss in kk:
+            flat_keys.append(ss)
+    
+        new_key = "-".join(kk)
+        save_dict[new_key] = vv
+        
+    save_dict["keys"] = np.array(flat_keys,dtype='U')
+    save_dict["key_lens"] = np.array(key_lens,dtype=np.uint8) 
+    
+    # exp_data:
+    # dict[tuple[str,...],shape=(n_exps,n_sens,n_comps,n_time_steps)]
+    # The ** operator unpacks the dictionary into function keyword arguments
+    np.savez(save_file,**save_dict,allow_pickle=False)
+
+
+def load_exp_sim_data(load_file: Path) -> dict[str,np.ndarray]:
+    """Loads the results of a simulated experiment from disk.
+
+    Parameters
+    ----------
+    load_file : Path
+        Path and file name for the file where the data should be loaded from. 
+
+    Returns
+    -------
+    dict[tuple[str,...],np.ndarray]
+        The simulated experiment data dictionary loaded from disk.
+    """
+    # NOTE: npz files are loaded in a 'lazy' manner so we must use a context
+    # manager here and convert to a dictionary which forces everything in the
+    # npz to be directly loaded into memory.
+    flat_data = {}
+    with np.load(load_file) as npzfile:
+        flat_data = dict(npzfile)
+    
+    flat_keys = flat_data["keys"]
+    key_lens = flat_data["key_lens"]
+    flat_data.pop("keys")
+    flat_data.pop("key_lens")
+    
+    exp_data = {}
+    key_ind: int = 0
+    for key_len in key_lens:
+        tuple_key = tuple(flat_keys[key_ind:key_ind+key_len])
+        key_ind += key_len
+
+        for join_key in flat_data:
+            str_key_count: int = 0
+            
+            for str_key in tuple_key:
+                if str_key in join_key:
+                    str_key_count += 1
+
+            if str_key_count == key_len:
+                exp_data[tuple_key] = flat_data[join_key]
+                flat_data.pop(join_key)
+                break
+            
+    # dict[tuple[str,...],shape=(n_sims,n_exps,n_sens,n_comps,n_time_steps)]
+    return exp_data
+