bluepyefe.extract¶

Efeature extraction functions

Functions

`cells_pickle_output_path`(output_directory)	Returns the cells.pkl output file path
`compute_rheobase`(cells, protocols_rheobase)	For each cell, finds the smallest current inducing a spike (rheobase).
`convert_legacy_targets`(targets)	Convert targets of the form.
`create_feature_protocol_files`(cells, protocols)	Save the efeatures and protocols for each protocol/target combo in json file.
`extract_efeatures`(output_directory, ...[, ...])	Extract efeatures.
`extract_efeatures_at_targets`(cells, targets)	Extract efeatures from recordings following the protocols, amplitudes and efeature names specified in the targets.
`extract_efeatures_per_cell`(files_metadata, ...)
`group_efeatures`(cells, targets[, ...])	Group the recordings and their efeatures and associate them to the EFeature Targets and Protocols they belong to.
`plot_recordings`(files_metadata[, ...])	Plots recordings.
`protocols_pickle_output_path`(output_directory)	Returns the protocols.pkl output file path
`read_recordings`(files_metadata[, ...])	Read recordings from a group of files.

cells_pickle_output_path(output_directory)[source]¶

Returns the cells.pkl output file path

Parameters:: output_directory (Path) – the output directory

compute_rheobase(cells, protocols_rheobase, rheobase_strategy='absolute', rheobase_settings=None)[source]¶

For each cell, finds the smallest current inducing a spike (rheobase). This currents are then use it to compute the relative amplitude of the stimuli.

Parameters:

cells (list) – list of Cells containing for which the rheobase will be computed
protocols_rheobase (list) – names of the protocols that will be used to compute the rheobase of the cells. E.g: [‘IDthresh’].
rheobase_strategy (str) – function used to compute the rheobase. Can be ‘absolute’ (amplitude of the lowest amplitude inducing at least a spike) or ‘majority’ (amplitude of the bin in which a majority of sweeps induced at least one spike).
rheobase_settings (dict) – settings related to the rheobase computation. Keys have to match the arguments expected by the rheobase computation function.

convert_legacy_targets(targets)[source]¶

Convert targets of the form:

.. code-block:: python

    protocol_name: {
        "amplitudes": [50, 100],
        "tolerances": [10, 10],
        "efeatures": {"Spikecount": {'Threshold': -10.}},
        "location": "soma"
    }

To ones of the form:

.. code-block:: python

    [{
        "efeature": "AP_amplitude",
        "protocol": "IDRest",
        "amplitude": 150.,
        "tolerance": 10.,
        "efel_settings": {
            "stim_start": 200.,
            "stim_end": 500.,
            "Threshold": -10.
        }
    }]

create_feature_protocol_files(cells, protocols, output_directory=None, threshold_nvalue_save=1, write_files=True, save_files_used=False, default_std_value=0.001)[source]¶

Save the efeatures and protocols for each protocol/target combo in json file.

Parameters:

cells (list) – list of Cells.
protocols (list) – list of Protocols.
output_directory (str) – path of the directory to which the features, protocols and currents will be saved.
threshold_nvalue_save (int) – minimum number of values needed for an efeatures to be averaged and returned in the output.
write_files (bool) – if True, the efeatures, protocols and currents will be saved in .json files in addition of being returned.
save_files_used (bool) – if True, the name of the recording files used in the computation of the features will be added to the efeatures.
default_std_value (float) – default value used to replace the standard deviation if the standard deviation is 0.

Returns:

feat (dict) stim (dict) currents (dict)

extract_efeatures(output_directory, files_metadata, targets=None, threshold_nvalue_save=1, protocols_rheobase=None, absolute_amplitude=False, recording_reader=None, map_function=<class 'map'>, write_files=False, plot=False, low_memory_mode=False, protocol_mode='mean', efel_settings=None, extract_per_cell=False, rheobase_strategy='absolute', rheobase_settings=None, auto_targets=None, pickle_cells=False, default_std_value=0.001)[source]¶

Extract efeatures.

Parameters:

output_directory (str) – path to the output directory
files_metadata (dict) –
define from files to read the data as well as the name of the cells and protocols to which these data are related. Of the form:
```
.. code-block:: python

    {
        cell_id: {
            protocol_name: [
                {file_metadata1},
                {file_metadata1}
            ]
        }
    }
```
The entries required in the file_metadata are specific to each recording_reader (see bluepyemodel/reader.py to know which one are needed for your recording_reader). As the file_metadata contain file paths, a same file path might need to be present in the file metadata of different protocols if the path contains data coming from different stimuli (eg: for NWB).

targets (list) –

define the efeatures to extract as well as which protocols and current amplitude (expressed either in % of the rheobase if absolute_amplitude if False or in nA if absolute_amplitude is True) they should be extracted. If targets are not provided, automatic targets will be used. Of the form:

.. code-block:: python

    [{
        "efeature": "AP_amplitude",
        "protocol": "IDRest",
        "amplitude": 150.,
        "tolerance": 10.,
        "efel_settings": {
            "stim_start": 200.,
            "stim_end": 500.,
            "Threshold": -10.
        }
    }]

threshold_nvalue_save (int) – minimum number of values needed for an efeatures to be averaged and returned in the output.
protocols_rheobase (list) – names of the protocols that will be used to compute the rheobase of the cells. E.g: [‘IDthresh’].
absolute_amplitude (bool) – if True, will use the absolute amplitude instead of the relative amplitudes of the recordings when checking if a recording has to be used for a given target.
recording_reader (function) – custom recording reader function. It’s inner working has to match the metadata entered in files_metadata.
map_function (function) – Function used to map (parallelize) the recording reading and feature extraction operations.
write_files (bool) – if True, the efeatures, protocols and currents will be saved in .json files in addition of being returned.
plot (bool) – if True, the recordings and efeatures plots will be created.
low_memory_mode (bool) – if True, minimizes the amount of memory used during the data reading and feature extraction steps by performing additional clean up. Not compatible with map_function.
protocol_mode (str) – protocol_mode (mean): if a protocol matches several recordings, the mode set the logic of how the output will be generating. Must be ‘mean’, ‘median’ or ‘lnmc’
efel_settings (dict) –
eFEL settings in the form {setting_name: setting_value}. If settings are also informed in the targets per efeature, the latter will have priority. If None, will be set to:
```
.. code-block:: python

    {
        "strict_stiminterval": True,
        "Threshold": -20.,
        "interp_step": 0.025
    }
```
extract_per_cell (bool) – if True, also generates the features.json and protocol.json for each individual cells.
rheobase_strategy (str) – function used to compute the rheobase. Can be ‘absolute’ (amplitude of the lowest amplitude inducing at least a spike) or ‘majority’ (amplitude of the bin in which a majority of sweeps induced at least one spike).
rheobase_settings (dict) – settings related to the rheobase computation. Keys have to match the arguments expected by the rheobase computation function.
auto_targets (list of AutoTarget) – targets with more flexible goals.
pickle_cells (bool) – if True, the cells object will be saved as a pickle file.
default_std_value (float) – default value used to replace the standard deviation if the standard deviation is 0.

extract_efeatures_at_targets(cells, targets, map_function=<class 'map'>, efel_settings=None)[source]¶

Extract efeatures from recordings following the protocols, amplitudes and efeature names specified in the targets.

Parameters:

cells (list) – list of Cells containing the recordings from which the efeatures will be extracted.

targets (dict) –

define the efeatures to extract as well as which protocols and current amplitude they should be extracted for. Of the form:

[{
    "efeature": "AP_amplitude",
    "protocol": "IDRest",
    "amplitude": 150.,
    "tolerance": 10.,
    "efel_settings": {
        "stim_start": 200.,
        "stim_end": 500.,
        "Threshold": -10.
    }
}]

map_function (function) – Function used to map (parallelize) the feature extraction operations. Note: the parallelization is done across cells an not across efeatures.
efel_settings (dict) – eFEL settings in the form {setting_name: setting_value}. If settings are also informed in the targets per efeature, the latter will have priority.

group_efeatures(cells, targets, absolute_amplitude=False, use_global_rheobase=True, protocol_mode='mean', efel_settings=None)[source]¶

Group the recordings and their efeatures and associate them to the EFeature Targets and Protocols they belong to.

Parameters:

cells (list) – list of Cells containing for which the rheobase will be computed

targets (dict) –

define the efeatures to extract as well as which protocols and current amplitude they should be extracted for. Of the form:

[{
    "efeature": "AP_amplitude",
    "protocol": "IDRest",
    "amplitude": 150.,
    "tolerance": 10.,
    "efel_settings": {
        "stim_start": 200.,
        "stim_end": 500.,
        "Threshold": -10.
    }
}]

absolute_amplitude (bool) – if True, will use the absolute amplitude instead of the relative amplitudes of the recordings when checking if a recording has to be used for a given target.
use_global_rheobase (bool) – As the final amplitude of a target is the mean of the amplitude of the cells, a global rheobase can be used to avoid issues when a cell matches a target but not another one. Which can result in situations where the second target is higher but it’s amp in amperes is lower. e.g: target1 = 100%, target2 = 150% but target1_amp = 0.2 and target2_amp = 0.18
protocol_mode (mean) – if a protocol matches several recordings, the mode set the logic of how the output will be generating. Must be ‘mean’, ‘median’ or ‘lnmc’
efel_settings (dict) – eFEL settings in the form {setting_name: setting_value}. If settings are also informed in the targets per efeature, the latter will have priority.

plot_recordings(files_metadata, output_directory='./figures/', recording_reader=None, map_function=<class 'map'>)[source]¶

Plots recordings.

Parameters:

files_metadata (dict) –
define for which cell and protocol each file has to be used. Of the form:
{ cell_id: { protocol_name: [ {file_metadata1}, {file_metadata1} ] } }
A same file path might be present in the file metadata for different protocols. The entries required in the file_metadata are specific to each recording_reader (see bluepyemodel/reader.py to know which one are needed for your recording_reader).
output_directory (str) – path to the output directory where the plots will be saved.
recording_reader (function) – custom recording reader function. It’s inner working has to match the metadata entered in files_metadata
map_function (function) – Function used to map (parallelize) the recording reading and feature extraction operations.

protocols_pickle_output_path(output_directory)[source]¶

Returns the protocols.pkl output file path

Parameters:: output_directory (Path) – the output directory

read_recordings(files_metadata, recording_reader=None, map_function=<class 'map'>, efel_settings=None)[source]¶

Read recordings from a group of files. The files are expected to be identified by both a cell id and a protocol name (see files_metadata).

Parameters:

files_metadata (dict) –
define for which cell and protocol each file has to be used. Of the form:
{ cell_id: { protocol_name: [ {file_metadata1}, {file_metadata1} ] } }
A same file path might be present in the file metadata for different protocols. The entries required in the file_metadata are specific to each recording_reader (see bluepyemodel/reader.py to know which one are needed for your recording_reader).
recording_reader (function) – custom recording reader function. It’s inner working has to match the metadata entered in files_metadata.
map_function (function) – Function used to map (parallelize) the recording reading operations. Note: the parallelization is done across cells an not across files.
efel_settings (dict) – eFEL settings in the form {setting_name: setting_value}.

Returns:

list of Cell objects containing the data of the recordings

Return type:

cells (list)