pynibs.regression package¶

This holds methods for the TMS-based cortical localization approach as published in [1] and [2].

References

[1]

Numssen, O., Zier, A. L., Thielscher, A., Hartwigsen, G., Knösche, T. R., & Weise, K. (2021). Efficient high-resolution TMS mapping of the human motor cortex by nonlinear regression. NeuroImage, 245, 118654.

[2]

Jing, Y., Numssen, O., Weise, K., Kalloch, B., Buchberger, L., Haueisen, J., Hartwigsen, G., Knösche, T. (2023). Modeling the Effects of Transcranial Magnetic Stimulation on Spatial Attention. Physics in Medicine & Biology. doi: 10.1088/1361-6560/acff34

Submodules¶

pynibs.regression.dual_node_detection module¶

Contains functions for applying and testing single and dual node network detection. The two main functions are - network_detection_algorithm_application(): to apply the NDA to experimental TMS data, and - network_detection_algorithm_testing(): to generate artificial data and apply the NDA for testing reasons. Details to all settings and options can be found in data/network mapping configuration/configuration guide.md.

pynibs.regression.dual_node_detection.assign_found_hotspot_single(fn_geo, hotspot_idcs, found_idx)¶

Assigns the found hotspot to the nearest real hotspot if there is only one hotspot found.

Parameters:

fn_geo (str) – Path to the geo.hdf5-file.
hotspot_idcs (list) – A list of length 2 containing the indices of the real hotspots.
found_idx (int) – The index of the found hotspot.

Returns:

A tuple containing the rounded distance between the real hotspot and the found hotspot, and the index indicating which real hotspot is assigned to the found hotspot.

Return type:

tuple

pynibs.regression.dual_node_detection.assign_found_hotspots(fn_geo, hotspot_idcs, found_idcs)¶

Assigns the found hotspots to the real hotspots if there are two hotspots.

Parameters:

fn_geo (str) – Path to the geo.hdf5-file.
hotspot_idcs (list) – A list of length 2 containing the indices of the real hotspots.
found_idcs (list) – A list of length 2 containing the indices of the found hotspots.

Returns:

A tuple containing the rounded distances between the real hotspots and the found hotspots, and the updated list of found hotspot indices in the order they were assigned to the real hotspots.

Return type:

tuple

pynibs.regression.dual_node_detection.binarize_real_meps(meps, method='kde')¶

Binarizes real MEP measurements.

Parameters:

meps (np.ndarray) – (n_zaps) The MEP measurements.
method (str) –
The method for determining the binarization threshold. Valid options are:
- kde: Determine the threshold based on the density of the measurement points. The point density is low when the value of the MEPs is rapidly changing.
- slope: Determine the threshold based on the derivative/slope.

Returns:

An array of the same shape as meps with 1 for data points below the determined threshold, and 0 otherwise.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.binarize_response_data(response_values, method, bin_factor)¶

Binarizes the response data according to the selected method.

Parameters:

response_values (np.ndarray) – (n_zaps) Response data.
method (str) – Method of calculating the binarization threshold. (“mean”, “slope”, “median”)
bin_factor (float) – Factor multiplied with threshold for splitting the data. (bin_factor * method(response)) is the threshold used for categorizing the data.

Returns:

response_bin – (n_zaps) Binarized response data, where values greater than the threshold are set to 1, and values less than or equal to the threshold are set to 0.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.calc_dist_pairwise(fn_geo, idx0, idx1)¶

Returns the geodesic distance from ROI element idx0 to idx1. In some rare cases at the border of the ROI, the geodesic distance cannot be measured or rather is infinite. In this case, the euclidean measure is used as an approximation.

Parameters:

fn_geo (str) – Path to the geo.hdf5-file.
idx0 (int) – Index of the first ROI element.
idx1 (int) – Index of the second ROI element.

Returns:

distance – Geodesic distance between the two ROI elements.

Return type:

float

pynibs.regression.dual_node_detection.compute_correlation_with_all_elements(e_subset, elm_idx)¶

Calculate the Pearson correlation coefficient of elm_idx with every other element.

Parameters:

e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
elm_idx (int) – The index of the element to compute the correlation with.

Returns:

corr_coeff – (n_elms) Array containing the absolute Pearson correlation coefficients of elm_idx with each other element.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.compute_scores_with_all_elements(efields, data, weights=None, scoring_idcs=None, scoring_method='clf')¶

Computes the classifier (DecisionTree) score of each combination of ROI elements (upper triangle matrix of the score matrix).

Parameters:

efields (np.ndarray of float) – (n_zaps, n_elms) The efields in the ROI of all investigated coil positions.
data (np.ndarray) – (n_zaps) The response corresponding to each zap.
weights (np.ndarray, optional) – (n_zaps) Weights to weight the data points.
scoring_idcs (np.ndarray, optional) – Indices of ROI elements to compute scores for. Decreasing the number of elements significantly enhances runtime. If None, scores will be computed for all ROI elements.
scoring_method (str, optional) – Select ‘clf’ for Decision Tree Classifier, ‘regression’ for multivariable regression method, ‘regress_data’ for one-dimensional regression method.

Returns:

(n_elms, n_elms) An upper triangle matrix containing the scores of each ROI element with all others.

Return type:

np.ndarray of float

pynibs.regression.dual_node_detection.compute_scores_with_all_elements_MP(efields, data, weights=None, scoring_idcs=None, scoring_method='clf')¶

Computes the classifier (DecisionTree) score of each combination of ROI elements (multi-core enabled, upper triangle matrix of the score matrix).

Parameters:

efields (np.ndarray of float) – (n_zaps, n_elms) The efields in the ROI of all investigated coil positions.
data (np.ndarray of float) – (n_zaps) The response corresponding to each coil position.
weights (np.ndarray, optional) – (n_zaps) Weights to weight the data points.
scoring_idcs (np.ndarray, optional) – Indices of ROI elements to compute scores for. Decreasing the number of elements significantly enhances runtime. If None, scores will be computed for all ROI elements.
scoring_method (str, optional) – Select ‘clf’ for Decision Tree Classifier, ‘regression’ for multivariable regression method, ‘regress_data’ for one-dimensional regression method.

Returns:

An upper triangle matrix containing the scores of each ROI element with all others.

Return type:

np.ndarray of float

pynibs.regression.dual_node_detection.compute_scores_with_single_element_clf(element_idx, efields, data, weights=None, scoring_idcs=None)¶

Computes the classifier (DecisionTree) score of element ‘element_idx’ with all other elements within the ROI.

Parameters:

element_idx (int) – The index of the element whose score with all other elements should be computed.
efields (np.ndarray) – (n_zaps, n_elms) The efields in the ROI of all investigated coil positions.
data (np.ndarray) – (n_zaps) The response corresponding to each coil position.
weights (np.ndarray, optional) – (n_zaps) Weights to weight the data points.
scoring_idcs (np.ndarray, optional) – Indices of ROI elements to compute scores for. Decreasing the number of elements significantly enhances runtime. If None, scores will be computed for all ROI elements.

Returns:

A tuple with the index of the investigated element and an array containing the scores of this element with each other array element.

Return type:

tuple

pynibs.regression.dual_node_detection.compute_scores_with_single_element_regression(element_idx, efields, data, weights=None, scoring_idcs=None)¶

Computes the multivariate regression R2-score of element ‘element_idx’ with all other elements within the ROI.

Parameters:

element_idx (int) – The index of the element whose score with all other elements should be computed.
efields (np.ndarray) – (n_zaps, n_elms) The efields in the ROI of all investigated coil positions.
data (np.ndarray) – (n_zaps) The response corresponding to each coil position.
weights (np.ndarray, optional) – (n_zaps) Weights to weight the data points.
scoring_idcs (np.ndarray, optional) – Indices of ROI elements to compute scores for. Decreasing the number of elements significantly enhances runtime. If None, scores will be computed for all ROI elements.

Returns:

A tuple with the index of the investigated element and an array containing the scores of this element with each other array element.

Return type:

tuple

pynibs.regression.dual_node_detection.create_response_data(efields, config)¶

Create response data mimicking a chosen network. The mean of the used distribution is computed based on the e-field values of the chosen network, the deviation depends on the chosen noise level.

Parameters:

efields (ndarray of float) – (n_zaps, n_elms) Efield generated by used coil positions.
config (dict) – YAML-configuration file content as dictionary

Returns:

data – (n_zaps) Artificially generated response data array.

Return type:

ndarray of float

pynibs.regression.dual_node_detection.determine_coil_position_idcs(num_idcs, all_efields, rn_seed)¶

Select coil positions from the set of all positions.

Parameters:

num_idcs (int) – How many coil positions to select (sample size).
all_efields (ndarray of float) – (n_zaps_available, n_elms) Efields generated by all available coil positions.
rn_seed (int) – Random seed used in selection.

Returns:

selection – (n_zaps_used) Indices of chosen coil positions.

Return type:

ndarray of int

pynibs.regression.dual_node_detection.determine_detectable_hotspots(e_subset, rn_seed)¶

From a given e-field matrix, two possible hotspots are picked, with the requirements that both e-fields (their maximum value) reach values higher than 1.0 and that they are not too close to each other (corr_coef < 0.5) Returns the indices of the hotspots to be.

Parameters:

e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
rn_seed (int) – Random_seed used for hotspot selection.

Returns:

idx0 (int) – index of chosen hotspot element 0.
idx1 (int) – index of chosen hotspot element 1.

pynibs.regression.dual_node_detection.determine_scoring_idcs(e_subset, scoring_emag_thr=0, scoring_interval=22, method='optimized', fn_geo=None, required_idcs=None)¶

Computes which elements to consider in the score calculations.

Parameters:

e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
scoring_emag_thr (float, default: 0) –

Threshold to control stimulation accessibility of the scored elements. Elements with a stimulation peak
below this threshold are ignored.(high thr -> only gyral elements are scored). (method ‘optimized’ not possible with an active threshold in place.)
scoring_interval (int, default: 22) – The resolution for selecting elements. Only every scoring_interval-th element is considered.
method (str, default: 'optimized') –
Specify method for selecting scoring indices.
- random: Random elements across the ROI are picked (‘random’),
- optimized: Optimal elements are chosen by maximizing the distances between them. (‘optimized’) (Only applicable without scoring emag threshold. Requires fn_geo.)
fn_geo (str, optional) – Required to compute element distances if method=’optimized’.
required_idcs (np.ndarray of int, optional) – Any indices that should definitely be included in scoring process, regardless of subsampling. (e.g. hotspots)

Returns:

Array of indices representing the elements to consider in the score calculations.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.evaluate_network_identification(hotspot_dist, real_network_type, found_network_type)¶

Returns 1 if found_network_type is correct, 0 if not.

Parameters:

hotspot_dist (float) – Distance between hotspots.
real_network_type (int) – Real network type.
found_network_type (int) – Found network type.

Returns:

eval – Evaluation value indicating the accuracy of network identification.

Return type:

float

pynibs.regression.dual_node_detection.find_distinct_hotspots(scorematrix, hotspot_mask, e_subset, acc_thr, corr_thr)¶

Returns the potential hotspots according to the scores on the ROI. The two elements with the highest scores whose e-fields are not too correlated to each other are chosen. If one score is very high, a single-hotspot case is assumed.

Parameters:

scorematrix (np.ndarray) – (n_elms, n_elms) Upper triangle score matrix containing the scores of each ROI element with all others.
hotspot_mask (np.ndarray) – (n_elms) Hotspot score of every element, derived from the scorematrix.
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
acc_thr (float) – Threshold for accuracy criterion.
corr_thr (float) – Threshold for correlation criterion.

Returns:

hotspot_idcs (list) – List containing the indices of the potential hotspots.
hotspot_scores (list) – List containing the scores of the potential hotspots.
hotspot_acc (list) – List containing the accuracy values of the potential hotspots.
found_bool (list) – List indicating whether each potential hotspot was found.

pynibs.regression.dual_node_detection.find_distinct_single_hotspot(hotspot_mask, acc_thr)¶

Returns the potential hotspot according to the scores on the ROI. The element with the highest score is chosen. If one score is very high, a single-hotspot case is assumed.

Parameters:

hotspot_mask (np.ndarray) – (n_elms) Hotspot score of every element, derived from the scorematrix.
acc_thr (float) – Threshold for accuracy criteria.

Returns:

hotspot_idcs (list) – List containing the indices of the potential hotspots.
hotspot_scores (list) – List containing the scores of the potential hotspots.
hotspot_acc (list) – List containing the accuracy values of the potential hotspots.
found_bool (list) – List indicating whether each potential hotspot was found.

pynibs.regression.dual_node_detection.get_quadrant_samples(e_field0, e_field1)¶

Returns one point in each of the four representative stimulation states based on the provided electric field values. The stimulation states for two elements are all four possible combinations of the states “stimulated” and “not stimulated”.

Parameters:

e_field0 (np.ndarray) – (n_zaps) The electric field values of element 0.
e_field1 (np.ndarray) – (n_zaps) The electric field values of element 1.

Returns:

A 2D np.ndarray containing the x and y coordinates of the chosen point in the quadrant.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.hotspots_by_score_cumulative(scores)¶

Determine the hotspot elements within the ROI based on the cumulative scores. Mark the elements with the highest cumulative scores as hotspots.

Parameters:: scores (np.ndarray) – (n_elms, n_elms) Upper triangle matrix of the scores.
Returns:: hotspots – Array with dimensions equal to the number of ROI elements, where elements are marked as hotspots.
Return type:: np.ndarray

pynibs.regression.dual_node_detection.hotspots_by_score_percentiles(scores, accumulated=False)¶

Determine the hotspot elements within the ROI based on the upper percentile of scores. Mark the top elements as hotspot elements.

Parameters:

scores (np.ndarray) – Upper triangle matrix of the scores.
accumulated (bool, optional) – Whether to accumulate the number of interacting hotspot elements. If True, the number in the hotspot array at location i denotes the number of other hotspot elements this element is associated with. If False, hotspots are marked with a value of 1. Default is False.

Returns:

hotspots – Array with dimensions equal to the number of ROI elements, where elements are marked as hotspots.

Return type:

np.ndarray

pynibs.regression.dual_node_detection.identify_network_type(found_idcs, scorematrix, e_subset, response)¶

Identifies the most probable network type for the found indices using the function identify_shape(). The network type vectors are called shape_0 and shape_1.

Parameters:

found_idcs (list) – A list containing the indices of the found hotspots.
scorematrix (np.ndarray) – (n_elms, n_elms) Upper triangle score matrix containing the scores of each ROI element with all others.
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
response (np.ndarray) – (2, n_zaps) Response data: first entry original value, second entry binarized value.

Returns:

found_network_type (int) – The identified network type.
network_type_certainty (float) – The certainty level of the network type identification. (shape value of most probable network divided by value of the second most probable network)

pynibs.regression.dual_node_detection.identify_shape(idx, scorematrix, e_subset, response)¶

Network type vectors are computed to determine most probable network type (vectors called shape_0 and shape_1). The predictions of decision tree classifiers trained on elements with high scores are used here to compute the most probable network type the hotspot element idx_h is involved in. At most 500 element pairs are considered.

Parameters:

idx (int) – Index of the hotspot element in question.
scorematrix (np.ndarray of float) – (n_elms, n_elms) Upper triangle score matrix containing one score for every combination of elements.
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
response (np.ndarray) – (2, n_zaps) Response data: first entry original value, second entry binarized value.

Returns:

shape – Vector indicating shape of decision trees used in scoring the element in question (network type vector).

Return type:

np.ndarray of int

pynibs.regression.dual_node_detection.network_detection_algorithm_application(e_matrix, response_values, roi_surf, fn_geo, base_path, config)¶

The network detection algorithm is applied to given data. Based on the e-field values and response values provided, a dual node network is identified (type (1)-(8), for further explanation see config file) and active network nodes (hotspots) are localized (specified by the element IDs). The results are saved in a .csv-file specified in the config file. An “effect map” of the ROI can be created, showing where to expect the highest stimulation effects.

Parameters:

e_matrix (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of all available coil positions across all ROI elements.
response_values (np.ndarray) – (n_zaps) Response values (MEPs, reaction times, …) corresponding to the coil configurations.
roi_surf (ROI obj) – ROI surface object
fn_geo (str) – Path to the geo.hdf5-file.
base_path (str) – Path to the folder where results should end up.
config (dict) – YAML configuration file content as a dictionary.

pynibs.regression.dual_node_detection.network_detection_algorithm_testing(e_matrix, roi_surf, fn_geo, base_path, config)¶

For testing reasons, experimental TMS data is generated and the network detection algorithm is applied to it. The e-field values are not generated but needed as input. The response values are computed based on the chosen network and the e-field values. A comparison between the algorithm output and the input settings is then saved in a .csv-file and can be used to assess the algorithm’s performance.

Parameters:

e_matrix (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of all available coil positions across all ROI elements.
roi_surf (ROI obj) – ROI surface object
fn_geo (str) – Path to the geo.hdf5-file.
base_path (str) – Path to the folder where results should end up.
config (dict) – YAML configuration file content as a dictionary.

pynibs.regression.dual_node_detection.plot_data_bin(response_data_bin, e_field0, e_field1)¶

Plot the binarized response data within axes representing the efields of the respective hotspots.

Parameters:

response_data_bin (np.ndarray) – (n_zaps) The binarized response data.
e_field0 (np.ndarray) – The efields of hotspot 0.
e_field1 (np.ndarray) – The efields of hotspot 1.

Returns:

The matplotlib.pyplot object containing the plot.

Return type:

plt.pyplot

pynibs.regression.dual_node_detection.plot_data_clf(response_data_bin, e_field0, e_field1)¶

Plot the binarized response data within axes representing the efields of the respective hotspots. The background of the scatterplot will be colored according to the trained classifier’s predictions for the data. Also plots the structure of the decision tree used to classify the data.

Parameters:

response_data_bin (np.ndarray) – (n_zaps) The binarized response data.
e_field0 (np.ndarray) – The efields of hotspot 0.
e_field1 (np.ndarray) – The efields of hotspot 1.

Returns:

A tuple containing the matplotlib.pyplot objects for the decision tree and the for the scatterplot.

Return type:

Tuple[plt.pyplot, plt.pyplot]

pynibs.regression.dual_node_detection.plot_data_std(response_data, e_field0, e_field1)¶

Plot the response data within axes representing the efields of the respective hotspots.

Parameters:

response_data (np.ndarray) – (n_zaps) The response data values.
e_field0 (np.ndarray) – The efields of hotspot 0.
e_field1 (np.ndarray) – The efields of hotspot 1.

Returns:

The matplotlib.pyplot object containing the plot.

Return type:

plt.pyplot

pynibs.regression.dual_node_detection.whole_network_detection(e_subset, response_data, scorematrix, hotspot_mask, base_path, config)¶

Based on the hotspot scores, 0-2 hotspot candidates are chosen. (Localization) If 0 are viable to be a hotspot, the result is a pseudonetwork. If only 1 viable hotspot was found, it is a single hotspot (type 4/6). If 2 hotspot candidates are found, the network type (1)-(8) is identified. (Identification)

Parameters:

e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
response_data (np.ndarray of float) – (2, n_zaps) Two arrays, data[0] contains the response corresponding to each coil position, data[1] contains its binarization (1: response affected, 0: response not affected).
scorematrix (np.ndarray) – (n_elms, n_elms) Upper triangle score matrix containing the scores of each ROI element with all others.
hotspot_mask (np.ndarray) – (n_elms) Hotspot score of every element, derived from the scorematrix.
base_path (str) – The base path for the files.
config (dict) – A dictionary containing the configuration parameters.

Returns:

runtime_detection (float) – Running time of network detection.
detection_result (np.ndarray) –

(7) contains the result of the detection, consisting of (found_network_type, found_idcs, found_acc, found_distance, found_scores, network_type_certainty, shape_vector).

pynibs.regression.dual_node_detection.write_effect_map_hdf5(datatype, e_matrix, roi_surf, detection_result, base_path, config)¶

Create effect maps for result validation. The idea is that given a detection result, especially the hotspot_idcs and network_type, a prediction can be made about where the response is supposed to be affected most. Comparing these predictions and real response measurements is a possibility for result validation. See output_documentation.md for more.

Parameters:

datatype (str) – Whether the response data is “real” or “artificial”.
e_matrix (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of all available coil positions across all ROI elements.
roi_surf (ROI obj) – ROI surface object.
detection_result (np.ndarray) – (7) contains the result of the detection, consisting of (found_network_type, found_idcs, found_acc, found_distance, found_scores, network_type_certainty, shape_vector).
base_path (str) – Path to the folder where results should end up.
config (dict) – YAML configuration file content as a dictionary.

pynibs.regression.dual_node_detection.write_hotspot_scoremap_hdf5(datatype, e_subset, data, roi_surf, fn_geo, base_path, config, required_idcs=None)¶

Calculate the hotspot scores for given TMS experimental data and save scoremap and hotspot scores in hdf5. The hotspot scores indicate which ROI elements are most likely to be involved in the effect on the response variable. How they are computed depends on the scoring_method specified in the configuration file.

Parameters:

datatype (str) – Whether the response data is ‘real’ or ‘artificial’.
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
data (np.ndarray of float) – (2, n_zaps) Two arrays, data[0] contains the response corresponding to each coil position, data[1] contains its binarization (1: response affected, 0: response not affected).
roi_surf (ROI obj) – ROI surface object
fn_geo (str) – Path to the geo.hdf5-file.
base_path (str) – Path to the folder where results should end up.
config (dict) – YAML configuration file content as a dictionary.
required_idcs (np.ndarray of int, optional) – Any indices that should definitely be included in scoring process, regardless of subsampling. (e.g. hotspots)

Returns:

runtime_gen – Running time of data generation.

Return type:

float

pynibs.regression.dual_node_detection.write_nda_application_results_csv(runtimes, e_subset, response_data, hotspot_mask, detection_result, fn_geo, config)¶

Writes network detection results to a CSV file based on the provided parameters and configuration for real data. See output_documentation.md for more.

Parameters:

runtimes (np.ndarray of float) – (3), The runtimes in s for (generation, scoring, detection).
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
response_data (np.ndarray of float) – (2, n_zaps) Two arrays, data[0] contains the response corresponding to each coil position, data[1] contains its binarization (1: response affected, 0: response not affected).
hotspot_mask (np.ndarray) – (n_elms) Hotspot score of every element, derived from the scorematrix.
detection_result (np.ndarray) – (7) contains the result of the detection, consisting of (found_network_type, found_idcs, found_acc, found_distance, found_scores, network_type_certainty, shape_vector).
fn_geo (str) – Path to the geo.hdf5-file.
config (dict) – A dictionary containing the configuration parameters.

pynibs.regression.dual_node_detection.write_nda_test_results_csv(runtimes, e_subset, response_data, hotspot_mask, detection_result, fn_geo, config)¶

Evaluate network detection test results. Found networks are compared to the used settings for data generation. Then all used parameters and evaluation results are saved in a CSV file. See output_documentation.md for details about the output file.

Parameters:

runtimes (np.ndarray of float) –
1. The runtimes in s for (generation, scoring, detection).
detection_result (np.ndarray) – (7) contains the result of the detection, consisting of (found_network_type, found_idcs, found_acc, found_distance, found_scores, network_type_certainty, shape_vector).
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements .
response_data (np.ndarray of float) – (2, n_zaps) Two arrays, data[0] contains the response corresponding to each coil position, data[1] contains its binarization (1: response affected, 0: response not affected).
hotspot_mask (np.ndarray) – (n_elms) Hotspot score of every element, derived from the scorematrix.
detection_result – (7) contains the result of the detection, consisting of (found_network_type, found_idcs, found_acc, found_distance, found_scores, network_type_certainty, shape_vector).
fn_geo (str) – Path to the geo.hdf5-file.
config (dict) – A dictionary containing the configuration parameters.

pynibs.regression.dual_node_detection.write_network_detection_data_hdf5(datatype, e_matrix, response_values, base_path, config)¶

Preprocessing experimental data for the network detection algorithm. Either artificial response data is generated or real response data used. In the YAML files in the bin_configuration folder, the parameters or real measurements are used. In either case, the data is binarized (classified into 1: affected, and 0: not affected). Different data plotting options are included.

Parameters:

datatype (str) – Whether response data needs to be generated (‘artificial’) or real experimental data is available (‘real’).
e_matrix (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of all available coil positions across all ROI elements.
response_values (np.ndarray) – Real response values if available, or ‘None’ in artificial case.
base_path (str) – Path to the folder where results should end up.
config (dict) – YAML configuration file content as a dictionary.

Returns:

runtime_gen (float) – Running time of data generation.
e_subset (np.ndarray of float) – (n_zaps, n_elms) The efield magnitudes of the used coil positions across all ROI elements.
response (np.ndarray) – (2, n_zaps) Response values and binarized values in the form [response_values, response_binarized].

pynibs.regression.regression module¶

class pynibs.regression.regression.Element(x, y, ele_id, fun=None, score_type='R2', select_signed_data=False, constants=None, **kwargs)¶

Bases: object

Fit Element object class

calc_score()¶: Determine goodness-of-fit score.

run_fit(max_nfev=1000)¶: Perform data fit with lmfit.

run_select_signed_data()¶: Selects positive or negative data by performing an initial linear fit by comparing the resulting p-values, slopes and R2 values. Either positive or negative data (w.r.t. x-axis) yielding a fit with a p-value < 0.05, a positive slope and the higher R2 value is used and the remaining data with the other sign is omitted from the analysis

set_constants(value)¶: Sets constants in self.constants and gmodel instance

set_init_vals(value)¶: Sets initial values in self.init_vals and gmodel instance

set_limits(value)¶

Sets limits in self.limits and gmodel instance

Parameters:: value (dict) – Parameters (keys) to set in self as limits.

set_random_init_vals()¶: Set random initial values

setup_model()¶: Setup model parameters (limits, initial values, etc. …)

pynibs.regression.regression.fit_elms(elm_idx_list, e_matrix, mep, zap_idx=None, fun=<function sigmoid4>, init_vals=None, limits=None, log_scale=False, constants=None, max_nfev=None, bad_elm_idx=None, score_type='R2', verbose=False)¶

Workhorse for Mass-univariate nonlinear regressions on raw MEP_{AMP} ~ E. That is, for each element in elm_idx_list, it’s E (mag | norm | tan) for each zap regressed on the raw MEP amplitude. An element wise r2 score is returned.

Parameters:

elm_idx_list (list of int or np.ndarray) – List containing the element indices the fit is performed for.
e_matrix (np.ndarray of float) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float) – (n_zaps) Motor evoked potentials for every stimulation.
zap_idx (np.ndarray, optional) – (n_zaps) Indices of zaps the congruence factor is calculated with (default: all).
fun (str) – A function name of pynibs.exp.Mep (exp0, sigmoid).
init_vals (np.ndarray of dict) – (len(elm_idx_list)) Dictionary containing the initial values for each element as np.ndarray. The keys are the free parameters of fun, e.g. “x0”, “amp”, etc.
limits (pd.DataFrame) – Dictionary containing the limits of each parameter for each element e.g.: limits[“x0”][elm_idx] = [min, max].
log_scale (bool, default: False) – Log-transform data before fit (necessary for functions defined in the log domain).
constants (dict of <string>:<num>, optional) – key:value pair of model parameters not to optimize.
max_nfev (int, optional) – Max fits, passed to model.fit() as max_nfev=max_nfev*len(x).
bad_elm_idx (np.ndarray, optional) – Indices of elements not to fit, with indices corresponding to indices (not values) of elm_idx_list.
score_type (str, default: "R2") –
Goodness of fit measure; Choose SR for nonlinear fits and R2 or SR for linear fits:
- ”R2”: R2 score (Model variance / Total variance) [0, 1] for linear models; 0: bad fit; 1: perfect fit
- ”SR”: Relative standard error of regression (1 - Error 2-norm / Data 2-norm) [-inf, 1]; 1: perfect fit
verbose (bool, default: False) – Print verbosity information

Returns:

r2 (np.ndarray of float) – (n_roi, 1) R2 for each element in elm_idx_list.
best_values (np.ndarray of object) – Fit parameters returned from the optimizer.

pynibs.regression.regression.get_bad_elms(x, y, method='lstsq', verbose=False)¶

This does an element-wise fast linear regression fit to identify bad elements. Bad is defined here as a negative slope.

xnp.ndarray of float: (n_zaps, n_ele) Electric field matrix.
ynp.ndarray of float: (n_zaps) Motor evoked potentials for every stimulation.
methodstr, default: “lstsq”: Which method to use. (numpy.linalg.)lstsq, (scipy.stats.)linregress, or pinv
verbosebool, default: False: Indicating verbosity of messages.

Returns:: idx – Indices of bad elements.
Return type:: np.ndarray

pynibs.regression.regression.get_model_init_values(fun, elm_idx_list, e_matrix, mep, mask_e_field=None, rem_empty_hints=True)¶

Calc appropriate init, limit, and max values for models fits depending on the data. If negative and positive x-data is present in case of e.g. normal component values are set according to the side (positive or negative) where more values are present. When more positive x-axis values are present, negative x-axis values will be ignored. When more negative x-axis values are present, the absolute values will be taken and the positive values are ignored. Only parameters for sigmoid* are optimized.

Parameters:

fun (pyfempp.exp.Mep) – IO curve function object.
elm_idx_list (np.ndarray of int) – (n_used_elms) Array containing the element indices the fit is performed for.
e_matrix (np.ndarray of float) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float) – (n_zaps) Motor evoked potentials for every stimulation.
mask_e_field (np.ndarray of bool, optional) – (n_zaps, n_ele) Mask indicating for which e-field (and mep) values the fit is performed for. Changes for normal component in each element because of the sign and p-values. If None, all data is used in each element.
rem_empty_hints (bool, default: True) – Remove any non-filled param hints from limits dict.

Returns:

log_scale (bool) – Log scale.
limits (dict of list) – (n elm_index_list) Element-wise limit values for function fitting.
init_vals (dict of list) – (n elm_index_list) Element-wise init values for function fitting.
max_vals_refit (dict of list) – (n elm_index_list) Element-wise perturbation range for refitting function.

pynibs.regression.regression.init(l, zap_lists, res_fn)¶

Pool init function to use with regression_nl_hdf5_single_core_write().

Parameters:

l (multiprocessing.Lock()) –
zap_lists (list of list of int) – Which zaps to compute.
res_fn (str) – .hdf5 fn

pynibs.regression.regression.logistic_regression()¶

Some ideas on how to improve regression approach

De-log data

Data range has to be transformed to a reasonable range. For a full sigmoid, -10:10 looks ok

sig <- function(z) {
  return( 1 / (1 + exp(-z)))
}

desig <- function(x) {
  return(- log((1/x) - 1))
}

This might be a reasonable fast approach, but the parameter range has to be estimated. Maybe remove some outliters?

2. fit logistic regression to raw data scipy.optimize provides fit_curve(), which does OLS-ish fitting to a given function https://stackoverflow.com/questions/54376900/fit-sigmoid-curve-in-python

I expect this to be rather slow.

3. Use the sklearn logistic_regression classifyer and access raw fit data The logistic_regression is implemented as a classifyer, maybe it’s possible to use its regression fit results. Implementation should be pretty fast.

pynibs.regression.regression.nl_hdf5(elm_idx_list=None, fn_reg_hdf5=None, qoi_path_hdf5=None, e_matrix=None, mep=None, zap_idx=None, fun=<function sigmoid4>, n_cpu=4, con=None, n_refit=50, return_fits=False, score_type='R2', verbose=False, pool=None, refit_discontinuities=True)¶

Mass-univariate nonlinear regressions on raw MEP_{AMP} ~ E. That is, for each element in elm_idx_list, it’s E (mag | norm | tan) for each zap regressed on the raw MEP amplitude. An element wise r2 score is returned. The function reads the precomputed array of E-MEP data from an .hdf5 file.

Parameters:

elm_idx_list (np.ndarray of int, optional) – List containing the element indices the fit is performed for, if not all.
fn_reg_hdf5 (str, optional) – Filename (incl. path) containing the precomputed E-MEP dataframes.
qoi_path_hdf5 (Union[str, list[str]], optional) – Path in .hdf5 file to dataset of electric field qoi e.g.: [“E”, “E_norm”, “E_tan”]
e_matrix (np.ndarray of float, optional) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float) – (n_zaps) Motor evoked potentials for every stimulation.
zap_idx (np.ndarray, optional) – (n_used_zaps) Indices of zaps the congruence factor is calculated with, if not all.
fun (pynibs.exp.Mep function, default: sigmoid4) – A function of pynibs.exp.Mep (exp0, sigmoid).
n_cpu (int, default: 4) – Number of threads to use.
con (np.ndarray of float, optional) – (n_roi, 3 or 4) Connectivity matrix of ROI (needed in case of refit because of discontinuity check).
n_refit (int, default: 50) – Maximum number of refits of zero elements. No refit is applied in case of n_refit = 0.
return_fits (bool, default: False) – Return fit objects containing the parameter estimates.
score_type (str, default: "R2") –
Error measure of fit:
- ”R2”: R2 score (Model variance / Total variance); linear fits: [0, 1], 1 … perfect fit
- ”SR”: Relative standard error of regression (1 - Error 2-norm / Data 2-norm); [-Inf, 1], 1 … perfect fit
verbose (bool, default: False) – Plot output messages.
pool (multiprocessing.Pool(), optional) – Pool instance to use.
refit_discontinuities (bool, default: True) – Run refit for discontinuous elements at the end.

Returns:

r2 – (n_roi, n_qoi) R2 for each element in elm_idx_list.

Return type:

np.ndarray of float

pynibs.regression.regression.nl_hdf5_single_core(zap_idx, elm_idx_list, fn_reg_hdf5=None, qoi_path_hdf5=None, e_matrix=None, mep=None, fun=<function sigmoid4>, con=None, n_refit=50, return_fits=False, constants=None, verbose=False, seed=None, rem_bad_elms=True, return_e_field_stats=True)¶

Parameters:

zap_idx (np.ndarray of int) – (n_zaps_used) Indices of zaps the congruence factor is calculated with.
elm_idx_list (np.ndarray of int) – List containing the element indices the fit is performed for.
fn_reg_hdf5 (str, optional) – Filename (incl. path) containing the precomputed E-MEP dataframes
qoi_path_hdf5 (str or list of str, optional) – Path in .hdf5 file to dataset of electric field qoi e.g.: [“E”, “E_norm”, “E_tan”].
e_matrix (np.ndarray of float, optional) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float, optional) – (n_zaps) Motor evoked potentials for every stimulation.
fun (function object, default: sigmoid4) – A function of pynibs.exp.Mep (exp0, sigmoid).
con (np.ndarray of float, optional) – (n_roi, 3 or 4) Connectivity matrix of ROI (needed in case of refit because of discontinuity check).
n_refit (int, default: 50) – Maximum number of refits of zero elements. No refit is applied in case of n_refit = 0.
return_fits (bool, default: False) – Return fit objects containing the parameter estimates
constants (dict of <string>:<num>, optional) – key:value pair of model parameters not to optimize.
verbose (bool, default: False) – Plot output messages.
seed (int, optional) – Seed to use.
rem_bad_elms (bool, default: True) – Remove elements based on a fast linear regression slope estimation.
return_e_field_stats (bool, default: True) – Return some stats on the efield variance

Returns:

r2 – (n_roi, n_qoi) R2 for each element in elm_idx_list.

Return type:

np.ndarray of float

pynibs.regression.regression.nl_hdf5_single_core_write(i, elm_idx_list, fn_reg_hdf5=None, qoi_path_hdf5=None, e_matrix=None, mep=None, fun=<function sigmoid4>, con=None, n_refit=50, return_fits=False, constants=None, verbose=False, seed=None, stepdown=False, score_type='R2', return_progress=False, geo=None)¶

Perform single-core processing for non-linear optimization and write results to an HDF5 file.

Parameters:

i (int) – The index of the subset of data to process.
elm_idx_list (list of int) – List of element indices.
fn_reg_hdf5 (str, optional) – Path to the registration HDF5 file.
qoi_path_hdf5 (str, optional) – Path to the HDF5 file containing the quantity of interest (QOI) data.
e_matrix (np.ndarray, optional) – The electromagnetic forward matrix.
mep (pandas.DataFrame, optional) – The motor evoked potential (MEP) data.
fun (function, default: sigmoid4) – The non-linear optimization function to use (default: pynibs.expio.sigmoid4).
con (object, optional) – Constraints for optimization, if applicable.
n_refit (int, default: 50) – Number of refitting iterations.
return_fits (bool, default: False) – If True, return fits alongside the coefficients.
constants (dict, optional) – Constants used in the optimization function.
verbose (bool, default: False) – If True, print verbose messages.
seed (int, optional) – The random seed for optimization.
stepdown (bool, default: False) – If True, use a stepdown approach for optimization.
score_type (str, default: 'R2') – The type of score to use for optimization.
return_progress (bool, default: False) – If True, return progress data.
geo (object, optional) – Geometry data.

Returns:

A dictionary containing the following elements:

’progress_data’: Progress data if ‘return_progress’ is True.
’best_values’: Best optimization values if ‘return_fits’ is True.

Return type:

dict

pynibs.regression.regression.regress_data(e_matrix, mep, elm_idx_list=None, element_list=None, fun=<function sigmoid4>, n_cpu=4, con=None, n_refit=50, zap_idx=None, return_fits=False, score_type='R2', verbose=False, pool=None, refit_discontinuities=True, select_signed_data=False, mp_context='fork', **kwargs)¶

Mass-univariate nonlinear regressions on raw MEP_{AMP} ~ E. That is, for each element in elm_idx_list, it’s E (mag | norm | tan) for each zap regressed on the raw MEP amplitude. An element wise R2 score is returned. The function reads the precomputed array of E-MEP data from an .hdf5 file.

Parameters:

e_matrix (np.ndarray of float) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float) – (n_zaps,) Motor evoked potential for each stimulation.
elm_idx_list (np.ndarray of int or list of int) – (n_zaps,) List containing the element indices the fit is performed for.
element_list (list of Element object instances, optional) – [n_ele] pynibs.Element objects ot skip initialization here.
fun (pynibs.exp.Mep, default: pynibs.expio.sigmoid4) – A pynibs.exp.Mep function (exp0, sigmoid, sigmoid4, …).
n_cpu (int, default: 4) – Number of threads, if n_cpu=1 no parallel pool will be opened and all calculations are done in serial.
con (np.ndarray of float, optional) – (n_ele, 3 or 4) Connectivity matrix of ROI. Needed in case of refit for discontinuity checks.
n_refit (int, default: 50) – Maximum number of refits of zero elements. No refit is applied in case of n_refit = 0.
zap_idx (np.ndarray of int or list of int, optional) – Which e/mep pairs to use.
return_fits (bool, optional) – Return fit objects containing the parameter estimates.
score_type (str, default: "R2") –
Error measure of fit:
- ”R2”: R2 score (Model variance / Total variance); linear fits: [0, 1], 1 … perfect fit
- ”SR”: Relative standard error of regression (1 - Error 2-norm / Data 2-norm); [-Inf, 1], 1 … perfect fit
- ”rho”: Spearman correlation coefficient [-1, 1]; finds any monotonous correlation (0 means no correlation)
verbose (bool, default: False) – Plot output messages.
pool (multiprocessing.Pool()) – pool instance to use.
refit_discontinuities (bool, default: True) – Refit discontinuous elements. If True, provide _con_.
mp_context (str, default: "fork") –
Controls the method the sub-processes of the multiprocessing pool (in case of n_cpu > 1) are launched.
- fork: (only supported by Unix) mp processes diverge from the main process, the entire stack, variables and other resources are copied over. From the docs: “The child process, when it begins, is effectively identical to the parent process. All resources of the parent are inherited by the child process. Note that safely forking a multithreaded process is problematic.”
- spawn: (supported by Window and Unix) mp processes are launched in an entirely new Python interpreter as separate processes. Variables are copied other resources are freshly instantiated. From the docs: “In particular, unnecessary file descriptors and handles from the parent process will not be inherited. Starting a process using this method is rather slow compared to using fork or forkserver.”
**kwargs – Passed on to pynibs.Element() to set fit parameters.

Returns:

score (np.ndarray of float) – (n_roi, n_qoi) Score for each element.
best_values (list of dict) – (n_ele) List of parameter fits. Only returned if return_fits=True.

pynibs.regression.regression.ridge_from_hdf5(elm_idx_list, fn_reg_hdf5, qoi_path_hdf5, zap_idx=None)¶

Mass-univariate ridge regressions on raw MEP_{AMP} ~ E. That is, for each element in elm_idx_list, it’s E (mag | norm | tan) for each zap regressed on the raw MEP amplitude. An element wise sklearn.metrics.regression.r2_score is returned. The function reads the precomputed array of E-MEP data from an .hdf5 file. Always uses all cores of a machine!

elm_idx_listlist of int: List containing the element indices the fit is performed for.
fn_hdf5str: Filename (incl. path) containing the precomputed E-MEP dataframes.
qoi_path_hdf5str: Path in .hdf5 file to dataset of electric field qoi.
zap_idxnp.ndarray, optional: (n_zaps) Indices of zaps the congruence factor is calculated with (default: all).

Returns:: r2 – (n_roi, n_datasets) R^2 for each element in elm_idx_list.
Return type:: np.ndarray of float

pynibs.regression.regression.sing_elm_fitted(elm_idx_list, mep_lst, mep_params, e, alpha=1000, n_samples=100)¶

Mass-univariate ridge regressions on fitted MEP_{AMP} ~ E. That is, for each element in elm_idx_list, it’s E (mag | norm | tan) for each zap regressed on the raw MEP amplitude. An element wise sklearn.metrics.regression.r2_score is returned.

Parameters:

elm_idx_list (np.ndarray) – (n_used_ele) List of element indices, the congruence factor is computed for.
mep_lst (list of Mep object instances) – (n_conds) List of fitted Mep object instances for all conditions (see exp.py for more information).
mep_params (np.ndarray of float) – (n_mep_params_total) List of all mep parameters of curve fits used to calculate the MEP accumulated into one array.(e.g.: [mep_#1_para_#1, mep_#1_para_#2, mep_#1_para_#3, mep_#2_para_#1, mep_#2_para_#1, …])
e (np.ndarray of float) – (n_elm, n_cond, n_qoi) Electric field to compute the r2 factor for, e.g. (e_mag, e_norm, e_tan).
n_samples (int, default=100) – Number of data points to generate discrete mep and e curves.

Returns:

r2 – (n_roi, n_datasets) R^2 for each element in elm_idx_list.

Return type:

np.ndarray of float

pynibs.regression.regression.sing_elm_raw(elm_idx_list, mep_lst, mep_params, e, alpha=1000)¶

elm_idx_listnp.ndarray: (chunksize) List of element indices, the congruence factor is computed for.
mep: list of Mep object instances: (n_cond) List of fitted Mep object instances for all conditions (see exp.py for more information of Mep class).
mep_params: np.ndarray of float: (n_mep_params_total) List of all mep parameters of curve fits used to calculate the MEP (accumulated into 1 array) (e.g.: [mep_#1_para_#1, mep_#1_para_#2, mep_#1_para_#3, mep_#2_para_#1, mep_#2_para_#1, …])
e: np.ndarray of float: (n_elm, n_cond, n_qoi) array of the electric field to compute the r2 factor for, e.g. (e_mag, e_norm, e_tan).

Returns:: r2 – (n_roi, n_datasets) R^2 for each element in elm_idx_list.
Return type:: np.ndarray of float

pynibs.regression.regression.single_fit(x, y, fun)¶

Performs a single fit and returns fit object.

Parameters:

x (ndarray of float) – x-values.
y (ndarray of float) – y-values.
fun (function) – Function for fitting.

Returns:

fit – Fit object.

Return type:

gmodel fit object

pynibs.regression.regression.stepdown_approach(zap_idx, elm_idx_list, fn_reg_hdf5=None, qoi_path_hdf5=None, e_matrix=None, mep=None, fun=<function sigmoid4>, con=None, n_refit=50, return_fits=False, constants=None, verbose=False, seed=None, rem_bad_elms=True, return_e_field_stats=True, score_type='R2', return_progress=False, smooth_data=True, geo=None)¶

Mass-univariate nonlinear regressions on raw MEP_{AMP} ~ E in a stepdown manner to speed up computation.

Initially, one set of fits is done for the complete dataset. Afterwards, the best 1% of the elements are used as initial fitting parameters for their neighboring elements. Then, neighboring elements are fitted accordingly and iteratively. Finally, discontinuous elements are refitted until a smooth map is found or n_refit is hit. Can be sped up with rem_bad_elms that computes a fast linear fit to identify elements with a negative slope. The function reads the precomputed array of E-MEP data from an .hdf5 file.

Parameters:

elm_idx_list (np.ndarray of int) – List containing the element indices the fit is performed for.
fn_reg_hdf5 (str) – Filename (incl. path) containing the precomputed E-MEP dataframes.
qoi_path_hdf5 (str or list of str, optional) – Path in .hdf5 file to dataset of electric field qoi e.g.: [“E”, “E_norm”, “E_tan”].
e_matrix (np.ndarray of float) – (n_zaps, n_ele) Electric field matrix.
mep (np.ndarray of float) – (n_zaps) Motor evoked potentials for every stimulation.
zap_idx (np.ndarray, optional) – (n_zaps) Indices of zaps the congruence factor is calculated with (default: all).
fun (function object) – A function of pynibs.exp.Mep (exp0, sigmoid).
con (np.ndarray of float, optional) – (n_elm_roi, 3 or 4) Connectivity matrix of ROI (needed in case of refit because of discontinuity check)
n_refit (int, default: 50) – Maximum number of refits of zero elements. No refit is applied in case of n_refit = 0.
return_fits (bool, default: False) – Return fit objects containing the parameter estimates
constants (dict of <string>:<num>, optional) – key:value pair of model parameters not to optimize.
verbose (bool, default: False) – Plot output messages.
seed (int, optional) – Seed to use.
rem_bad_elms (bool, default: True) – Remove elements based on a fast linear regression slope estimation.
return_e_field_stats (bool, default: True) – Return some stats on the efield variance
score_type (str, default: "R2") –
Error measure of fit:
- ”R2”: R2 score (Model variance / Total variance); linear fits: [0, 1], 1 … perfect fit
- ”SR”: Relative standard error of regression (1 - Error 2-norm / Data 2-norm); [-Inf, 1], 1 … perfect fit
- ”rho”: Spearman correlation coefficient [-1, 1]; finds any monotonous correlation (0 means no correlation)
return_progress (bool, default: False) – Return c maps for all steps to allow visualization over e-fitting over timesteps.
smooth_data (bool, default: False) – Smooth c-map as final step.
geo (object, optional) – Geometry data.

Returns:

A dictionary containing the following elements:

r2np.ndarray of float
(n_roi, n_qoi) R2 for each element in elm_idx_list.
best_values: list of dict
Fit information, if requested.
statsdict
If requested:

mc: float
Mutual coherence for e fields.

sv_ratfloat
SVD singular value ratio.
progress : cmaps for each step.

Return type:

dict

pynibs.regression.regression.workhorse_element_init(ele_id, e_matrix, mep, fun, score_type, select_signed_data, constants, **kwargs)¶: Workhorse to initialize Elements.

pynibs.regression.regression.workhorse_element_run_fit(element, max_nfev=10)¶: Workhorse to run single Element fit. If status is False, the element will not be fitted.

pynibs.regression.regression.write_regression_hdf5(fn_exp_hdf5, fn_reg_hdf5, qoi_path_hdf5, qoi_phys, e_results_folder, qoi_e, roi_idx, conds_exclude)¶

Reads the stimulation intensities from the experiment.hdf5 file. Reads the qoi from the experiment.hdf5 file. Reads the electric fields from the electric field folder. Weights the electric field voxel wise with the respective intensities and writes an .hdf5 file containing the preprocessed data (pandas dataframe).

fn_exp_hdf5str: Filename of the experiment.hdf5 file.
fn_reg_hdf5str: Filename of output regression.hdf5 file.
qoi_path_hdf5str: Path in experiment.hdf5 file pointing to the pandas dataframe containing the qoi. (e.g.: “phys_data/postproc/EMG”)
qoistr: Name of QOI the congruence factor is calculated with. (e.g.: “p2p”)
fn_e_resultsstr: Folder containing the electric fields. (e.g.: “/data/pt_01756/probands/13061.30/results/electric_field/1”)
qoi_estr or list of str: Quantities of the electric field used to calculate the congruence factor (e.g. [“E”, “E_norm”, “E_tan”] Has to be included in e.hdf5 -> e.g.: “data/midlayer/roi_surface/1/E”.
roi_idxint: ROI index.
conds_excludestr or list of str: Conditions to exclude.

Returns:: <File> – File containing the intensity (current) scaled E-fields of the conditions in the ROI. Saved in datasets with the same name as qoi_e [“E”, “E_norm”, “E_tan”]
Return type:: .hdf5 file

pynibs.regression package

pynibs.regression package¶

Submodules¶

pynibs.regression.dual_node_detection module¶

pynibs.regression.regression module¶

Table of Contents

Previous topic

Next topic

This Page