nilspodlib.session.Session#

class nilspodlib.session.Session(datasets: Iterable[Dataset])[source]#

Object representing a collection of Datasets.

Note

By default a session makes no assumption about when and how datasets are recorded. It just provides an interface to manipulate multiple datasets at once. If you have datasets that were recorded simultaneously with active sensor_type synchronisation, you should use a SyncedSession instead of a Session to take full advantage of this.

A session can access all the same attributes and most of the methods provided by a dataset. However, instead of returning a single value/acting only on a single dataset, it will return a tuple of values (one for each dataset) or modify all datasets of a session. You can also use the self.info object to access header information of all datasets at the same time. All return values will be in the same order as self.datasets.

Attributes:

datasets: A tuple of the datasets belonging to the session
info: Get metainfo for all datasets.

See also

nilspodlib.session.SyncedSession

Methods

`calibrate_imu`(calibrations[, inplace])	Calibrate the imus of all datasets by providing a list of calibration infos.
`cut`([start, stop, step, inplace])	Apply `Dataset.cut` to all datasets of the session.
`cut_counter_val`([start, stop, step, inplace])	Apply `Dataset.cut_counter_val` to all datasets of the session.
`cut_to_syncregion`([start, end, warn_thres, ...])	Apply `Dataset.cut_to_syncregion` to all datasets of the session.
`data_as_df`([datastreams, index, include_units])	Apply `Dataset.data_as_df` to all datasets of the session.
`downsample`(factor[, inplace])	Apply `Dataset.downsample` to all datasets of the session.
`find_calibrations`([folder, recursive, ...])	Apply `Dataset.find_calibrations` to all datasets of the session.
`find_closest_calibration`([folder, ...])	Apply `Dataset.find_closest_calibration` to all datasets of the session.
`from_file_paths`(paths[, legacy_support, ...])	Create a new session from a list of files pointing to valid .bin files.
`from_folder_path`(base_path[, ...])	Create a new session from a folder path containing valid .bin files.
`get_dataset_by_id`(sensor_id)	Get a specific dataset by its sensor_type id.
`imu_data_as_df`([index])	Apply `Dataset.imu_data_as_df` to all datasets of the session.

__init__(datasets: Iterable[Dataset])[source]#

Create new session.

Instead of this init you can also use the factory methods from_file_paths and from_folder_path.

Parameters:

datasets: List of nilspodlib.dataset.Dataset instances, which should be grouped into a session.

calibrate_imu(calibrations: Iterable[Union[CalibrationInfo, path_t]], inplace: bool = False) → Self[source]#

Calibrate the imus of all datasets by providing a list of calibration infos.

If you do not want to calibrate a specific IMU, you can pass None for its position.

Parameters:

calibrations: List of calibration infos in the same order than self.datasets
inplace: If True this methods modifies the current session object. If False, a copy of the sesion and all dataset objects is created

See also

nilspodlib.dataset.Dataset.calibrate_imu

cut(start: Optional[int] = None, stop: Optional[int] = None, step: Optional[int] = None, inplace: bool = False) → Self[source]#

Apply Dataset.cut to all datasets of the session.

See nilspodlib.dataset.Dataset.cut for more details. The docstring of this method is included below:

Cut all datastreams of the dataset. datastreams of the dataset.

This is equivalent to applying the following slicing to all datastreams and the counter: array[start:stop:step]

Warning

This will not modify any values in the header/info the dataset. I.e. the number of samples in the header/ sync index values. Using methods that rely on these values might result in unexpected behaviour. For example cut_to_syncregion will not work correctly, if cut or cut_counter_val was used before.

Parameters:

start: Start index
stop: Stop index
step: Step size of the cut
inplace: If True this methods modifies the current dataset object. If False, a copy of the dataset and all datastream objects is created

cut_counter_val(start: Optional[int] = None, stop: Optional[int] = None, step: Optional[int] = None, inplace: bool = False) → Self[source]#

Apply Dataset.cut_counter_val to all datasets of the session.

See nilspodlib.dataset.Dataset.cut_counter_val for more details. The docstring of this method is included below:

Cut the dataset based on values in the counter and not the index. dataset based on values in the counter and not the index.

Instead of just cutting the datastream based on its index, it is cut based on the counter value. This is equivalent to applying the following pandas style slicing to all datastreams and the counter: array.loc[start:stop:step]

Warning

Parameters:

start: Start value in counter
stop: Stop value in counter
step: Step size of the cut
inplace: If True this methods modifies the current dataset object. If False, a copy of the dataset and all datastream objects is created

Notes

The method searches the respective index for the start and the stop value in the counter and calls cut with these values. The step size will be passed directly and not modified (i.e. the step size will not respect downsampling or similar operations done beforehand).

cut_to_syncregion(start: bool = True, end: bool = False, warn_thres: Optional[int] = 30, inplace: bool = False) → Self[source]#

Apply Dataset.cut_to_syncregion to all datasets of the session.

See nilspodlib.dataset.Dataset.cut_to_syncregion for more details. The docstring of this method is included below:

Cut the dataset to the region indicated by the first and last sync package received from master. dataset to the region indicated by the first and last sync package received from master.

This cuts the dataset to the values indicated by info.sync_index_start and info.sync_index_stop. In case the dataset was a sync-master (info.sync_role = 'master') this will have no effect and the dataset will be returned unmodified.

Warning

This function should not be used after any other methods that can modify the counter (e.g. cut or downsample).

Warning

Parameters:

start: Whether the dataset should be cut at the info.sync_index_start. If this is False, a jump in the counter will remain. The only usecase for not cutting at the start is when the counters are already perfectly aligned.
end: Whether the dataset should be cut at the info.sync_index_stop. Usually it can be assumed that the data will be synchronous for multiple seconds after the last sync package. Therefore, it might be acceptable to just ignore the last syncpackage and just cut the start of the dataset.
warn_thres: Threshold in seconds from the end of a dataset. If the last syncpackage occurred more than warn_thres before the end of the dataset, a warning is emitted. Use warn_thres = None to silence. This is not relevant if the end of the dataset is cut (e.g. end=True)
inplace: If True this methods modifies the current dataset object. If False, a copy of the dataset and all datastream objects is created

Raises:

ValueError: If the dataset does not have any sync infos
ValueError: If the dataset does not have any sync infos

Warning

UserWarning: If a syncpackage occurred far before the last sample in the dataset. See arg warn_thres.

Notes

Usually to work with multiple syncronised datasets, a SyncedSession should be used instead of cutting the datasets manually. SyncedSession.cut_to_syncregion will cover multiple edge cases involving multiple datasets, which can not be handled by this method.

data_as_df(datastreams: Optional[Sequence[str]] = None, index: Optional[str] = None, include_units: Optional[bool] = True) → Tuple[pd.DataFrame][source]#

Apply Dataset.data_as_df to all datasets of the session.

See nilspodlib.dataset.Dataset.data_as_df for more details. The docstring of this method is included below:

Export the datastreams of the dataset in a single pandas DataFrame. he datastreams of the dataset in a single pandas DataFrame.

Parameters:

datastreams: Optional list of datastream names, if only specific ones should be included. Datastreams that are not part of the current dataset will be silently ignored.
index: Specify which index should be used for the dataset. The options are: “counter”: For the actual counter “time”: For the time in seconds since the first sample “utc”: For the utc time stamp of each sample “utc_datetime”: for a pandas DateTime index in UTC time “local_datetime”: for a pandas DateTime index in the timezone set for the session None: For a simple index (0…N)
include_units: If True the column names will have the unit of the datastream concatenated with an _ Notes:
include_units: If True the column names will have the unit of the datastream concatenated with an _ Notes: This method calls the data_as_df methods of each Datastream object and then concats the results.
include_units: If True the column names will have the unit of the datastream concatenated with an _

Raises:

ValueError: If any other than the allowed index values are used.

Notes

This method calls the data_as_df methods of each Datastream object and then concats the results. Therefore, it will use the column information of each datastream.

downsample(factor: int, inplace: bool = False) → Self[source]#

Apply Dataset.downsample to all datasets of the session.

See nilspodlib.dataset.Dataset.downsample for more details. The docstring of this method is included below:

Downsample all datastreams by a factor. le all datastreams by a factor.

This applies scipy.signal.decimate to all datastreams and the counter of the dataset. See nilspodlib.datastream.Datastream.downsample for details.

Warning

Parameters:

factor: Factor by which the dataset should be downsampled.
inplace: If True this methods modifies the current dataset object. If False, a copy of the dataset and all datastream objects is created

find_calibrations(folder: Optional[path_t] = None, recursive: bool = True, filter_cal_type: Optional[str] = None, ignore_file_not_found: Optional[bool] = False)[source]#

Apply Dataset.find_calibrations to all datasets of the session.

See nilspodlib.dataset.Dataset.find_calibrations for more details. The docstring of this method is included below:

Find all calibration infos that belong to a given sensor_type.: calibration infos that belong to a given sensor_type.

As this only checks the filenames, this might return a false positive depending on your folder structure and naming.

Parameters:

folder: Basepath of the folder to search. If None, tries to find a default calibration
recursive: If the folder should be searched recursive or not.
filter_cal_type: Whether only files obtain with a certain calibration type should be found. This will look for the CalType inside the json file and hence cause performance problems. If None, all found files will be returned. For possible values, see the imucal library.
ignore_file_not_found: If True this function will not raise an error, but rather return an empty list, if no calibration files were found for the specific sensor_type.

See also

nilspodlib.calibration_utils.find_calibrations_for_sensor

find_closest_calibration(folder: Optional[path_t] = None, recursive: bool = True, filter_cal_type: Optional[str] = None, before_after: Optional[str] = None, ignore_file_not_found: Optional[bool] = False)[source]#

Apply Dataset.find_closest_calibration to all datasets of the session.

See nilspodlib.dataset.Dataset.find_closest_calibration for more details. The docstring of this method is included below:

Find the closest calibration info to the start of the measurement.: closest calibration info to the start of the measurement.

As this only checks the filenames, this might return a false positive depending on your folder structure and naming.

Parameters:

folder: Basepath of the folder to search. If None, tries to find a default calibration
recursive: If the folder should be searched recursive or not.
filter_cal_type: Whether only files obtain with a certain calibration type should be found. This will look for the CalType inside the json file and hence cause performance problems. If None, all found files will be returned. For possible values, see the imucal library.
before_after: Can either be ‘before’ or ‘after’, if the search should be limited to calibrations that were either before or after the specified date.
warn_thres: If the distance to the closest calibration is larger than this threshold, a warning is emitted
ignore_file_not_found: If True this function will not raise an error, but rather return None, if no calibration files were found for the specific sensor_type.

See also

nilspodlib.calibration_utils.find_calibrations_for_sensor
nilspodlib.calibration_utils.find_closest_calibration_to_date

classmethod from_file_paths(paths: Iterable[path_t], legacy_support: str = 'error', force_version: Optional[Version] = None, tz: Optional[str] = None) → Self[source]#

Create a new session from a list of files pointing to valid .bin files.

Parameters:

paths: List of paths pointing to files to be included
legacy_support: This indicates how to deal with old firmware versions. If error: An error is raised, if an unsupported version is detected. If warn: A warning is raised, but the file is parsed without modification If resolve: A legacy conversion is performed to load old files. If no suitable conversion is found, an error is raised. See the legacy package and the README to learn more about available conversions.
force_version: Instead of relying on the version provided in the session header, the legacy support will be determined based on the version provided here. This is only used, if legacy_support="resolve". This option can be helpful, when testing with development firmware images that don’t have official version numbers.
tz: Optional timezone str of the recording. This can be used to localize the start and end time. Note, this should not be the timezone of your current PC, but the timezone relevant for the specific recording.

classmethod from_folder_path(base_path: path_t, filter_pattern: str = '*.bin', legacy_support: str = 'error', force_version: Optional[Version] = None, tz: Optional[str] = None) → Self[source]#

Create a new session from a folder path containing valid .bin files.

Parameters:

base_path: Path to the folder
filter_pattern: regex that can be used to filter the files in the folder. This is passed to Pathlib.glob()
legacy_support: This indicates how to deal with old firmware versions. If error: An error is raised, if an unsupported version is detected. If warn: A warning is raised, but the file is parsed without modification If resolve: A legacy conversion is performed to load old files. If no suitable conversion is found, an error is raised. See the legacy package and the README to learn more about available conversions.
force_version: Instead of relying on the version provided in the session header, the legacy support will be determined based on the version provided here. This is only used, if legacy_support="resolve". This option can be helpful, when testing with development firmware images that don’t have official version numbers.
tz: Optional timezone str of the recording. This can be used to localize the start and end time. Note, this should not be the timezone of your current PC, but the timezone relevant for the specific recording.

get_dataset_by_id(sensor_id: str) → Dataset[source]#

Get a specific dataset by its sensor_type id.

Parameters:

sensor_id: Four letter/digit unique id of the sensor

imu_data_as_df(index: Optional[str] = None) → Tuple[pd.DataFrame][source]#

Apply Dataset.imu_data_as_df to all datasets of the session.

See nilspodlib.dataset.Dataset.imu_data_as_df for more details. The docstring of this method is included below:

Export the acc and gyro datastreams of the dataset in a single pandas DataFrame. he acc and gyro datastreams of the dataset in a single pandas DataFrame.

Parameters:

index: Specify which index should be used for the dataset. The options are: “counter”: For the actual counter “time”: For the time in seconds since the first sample “utc”: For the utc time stamp of each sample “utc_datetime”: for a pandas DateTime index in UTC time “local_datetime”: for a pandas DateTime index in the timezone set for the session None: For a simple index (0…N)
include_units: If True the column names will have the unit of the datastream concatenated with an _ Notes:
include_units: If True the column names will have the unit of the datastream concatenated with an _ Notes: This method calls the data_as_df methods of each Datastream object and then concats the results.
include_units: If True the column names will have the unit of the datastream concatenated with an _

Raises:

ValueError: If any other than the allowed index values are used.

See also

nilspodlib.dataset.Dataset.data_as_df

Notes

This method calls the data_as_df methods of each Datastream object and then concats the results. Therefore, it will use the column information of each datastream.