skneuromsi.ndcollection.collection module

Implementation of NDCollection.

The ndcollection module implements the NDCollection class, which is a collection of NDResult objects.

class skneuromsi.ndcollection.collection.NDResultCollection(name, compressed_results, *, tqdm_cls=None)[source]

Bases: Sequence

Collection of NDResult objects.

Note that NDResult objects can be very memory hungry, so the NDResultCollection is designed to store the data in a compressed format. This is why the compressed_results parameter is an iterable of CompressedNDResult objects.

Check NDResultCollection.from_ndresults if you want to create an instance from a list of uncompressed NDResult objects.

Parameters:

  • name (str) – Name of the NDResultCollection.

  • compressed_results (iterable) – Iterable containing CompressedNDResult objects.

classmethod from_ndresults(name, results, *, compression_params=('lz4', 9), tqdm_cls=None)[source]

Create an instance of NDResultCollection from a list of NDResult objects.

Parameters:

  • name (str) – The name of the NDResultCollection.

  • results (List[NDResult]) – The list of NDResult objects to be compressed and stored in the collection.

  • compression_params (Tuple[str, int], optional) –

    The compression parameters for the NDResult objects. Defaults to

    core.DEFAULT_COMPRESSION_PARAMS.

  • tqdm_cls (tqdm.tqdm, optional) – The tqdm class to use. Defaults to None.

Returns:

An instance of NDResultCollection containing the compressed NDResult objects.

Return type:

NDResultCollection

property name

Name of the NDResultCollection.

property tqdm_cls

The tqdm class to use.

property modes_

Modes of all the results in the NDResultCollection.

property dims_

Dimensions of all the results in the NDResultCollection.

property output_mode_

Output mode of all the results in the NDResultCollection.

property run_parameters_

Run parameters of all the results in the NDResultCollection.

property causes_

Causes of all the results in the NDResultCollection.

property run_parameters_values

Run parameters values of all the results in the NDResultCollection.

property input_modes_

Input modes of all the results in the NDResultCollection.

Returns all modes that are not the output mode.

disparity_matrix()[source]

Generate a disparity matrix from run parameters values.

The resulting DataFrame has iterations as rows and parameters as columns.

Returns:

A DataFrame representing the disparity matrix.

Return type:

pandas.DataFrame

changing_parameters()[source]

Determine run parameters wich has multiple values.

This method calculates parameters that exhibit changing values across the disparity matrix. It identifies parameters for which the unique values are not consistent across all data points.

Returns:

A series indicating whether each parameter has changing values across the disparity matrix.

Return type:

pandas.Series

coerce_parameter(prefer=None)[source]

Coerce the provided run parameter or select a preferred one.

If ‘prefer’ is None, this method selects a run parameter based on which parameter is called with more than one value. If multiple changing parameters are available, The method fails.

If ‘prefer’ is provided, it is validated against the available run parameters.

Parameters:

prefer (str or None, optional) – The run parameter to be coerced or selected.

Returns:

The coerced or preferred run parameter.

Return type:

str

Raises:

ValueError – If the value of ‘parameter’ is ambiguous due to multiple candidates or if the provided run parameter is not in the available run parameters.

modes_variance_sum()[source]

Get the sum of variances for modes.

This method returns the sum of variances associated with modes.

Returns:

The sum of variances for modes.

Return type:

pandas.Series

coerce_mode(prefer=None)[source]

Coerces the provided preferred mode or selects a mode with maximum variance.

If ‘prefer’ is None, this method selects the mode with the maximum variance from available modes. If multiple modes have the same variance, the method fails.

If ‘prefer’ is provided, it is validated against the available modes.

Parameters:

prefer (str or None, optional) – The mode to be validated or selected.

Returns:

The validate or selected mode.

Return type:

str

Raises:

ValueError – If the value of ‘prefer’ is ambiguous due to multiple candidates with the same variance or if the provided preferred mode is not in the available modes.

coerce_dimension(prefer=None)[source]

Coerce and validate the provided preferred dimension or select the default dimension if None.

If no dimension is provided, the method prefers to use the ‘time’ dimension; otherwise, it check if the provided dimension exists criteria.

Parameters:

prefer (str or None, optional) – The dimension to be coerced, or the default dimension if None is provided.

Returns:

The coerced or selected dimension.

Return type:

str

Raises:

ValueError – If the provided preferred dimension is not in the available dimensions.

property causes

Accessor for NDResultCausesAcc providing access to causes analysis.

property bias

Accessor for NDResultBiasAcc providing access to bias analysis.

property plot

Accessor for NDResultCollectionPlotter providing access to plotting utilities.

to_ndc(path_or_stream, metadata=None, quiet=False, **kwargs)[source]

Store the NDResultCollection in a NMSI Collection (NDC) format.

Parameters:

  • path_or_stream (str or file-like) – File path or file-like object to save the NDC file.

  • metadata (dict, optional) – Additional metadata to include in the NDC file.

  • quiet (bool, optional) – If True, suppress tqdm progress bar. Defaults to False.

  • **kwargs – Additional keyword arguments passed to store_ndrcollection function.