conpagnon.utils package

Submodules

conpagnon.utils.array_operation module

Created on Thu Sep 28 09:58:24 2017

@author: Dhaif BEKHA

Useful operation on arrays.

conpagnon.utils.array_operation.append_masks(subjects_connectivity_dictionnary, kinds, discard_diagonal, vectorize)

Append a new key called ‘masked_array’ in the subjects connectivity matrices dictionnary and stock as values a boolean mask array accounting for discarded rois.

Parameters

• subjects_connectivity_dictionnary (dict) –

  A multi-levels dictionnary organised as follow :

  • The first keys levels is the different groupes in the study.

  • The second keys levels is the subjects IDs

  • The third levels is the different kind matrices

  for each subjects, a ‘discarded_rois’ key for the discarded rois array index.

• kinds (list) – List of present kinds in the subjects connectivity matrices dictionnary.

• discard_diagonal (bool) – If True, the mask diagonal is discarded in the vectorization process. This argument is passed to masked_void_rois_connectivity_matrix

• vectorize (bool) – If True, the returned mask is vectorized. This argument is passed to masked_void_rois_connectivity_matrix

Returns

output – The modified subjects connectivity matrices with a new key for each subjects containing the boolean mask array for the discarded ROIs. A new keys is added too, which contain the diagonal array of the mask.

Return type

dict

Notes

If the discarded rois keys do not exist, that is no labels ‘void’ is found in the atlas labels file of each subjects, then all roi are included in the analysis, and we append a boolean mask array of False values.

conpagnon.utils.array_operation.array_rebuilder(vectorized_array, array_type, diagonal=None)

Reconstruct a square array assuming a it is symmetric

Parameters

• vectorized_array (numpy.array) – The one dimensional array you want to rebuild.

• diagonal (numpy.array, optional) – The one dimensional array containing the diagonal of the non-vectorized array. If None, we assume that the diagonal was kept in the vectorization process.

• array_type (str) – The type of the array. Choices are: numeric, bool.

Returns

output 1 – The reconstructed array, shape (n_features, n_features).

Return type

numpy.array

See also

vectorizer()

This function vectorized a two dimensional numeric or boolean array

nilearn.connectome.vec_to_sym_matrix()

This function reconstruct a symmetric array from a one dimensional array.

conpagnon.utils.array_operation.check_2d(numpy_array)

Check if an array is two dimensional.

Parameters

numpy_array (numpy.array of any shape.) –

:raises ValueError : if the passed array is NOT two dimensional, a Value Error: :raises is raised.:

conpagnon.utils.array_operation.concatenate_imgs_in_order(imgs_directory, index_roi_number, filename, save_directory)

Concatenate 3D NifTi images into a single 4D NifTi files, given a user order.

Parameters

• imgs_directory (string) – The directory containing the list of images. Each file, must contain a number identifying the file.

• index_roi_number (list of int) – The list of file number in the order you want to ordered the images before concatenation

• filename (string) – The final name of the 4D file containing the images.

• save_directory (string) – The directory where to save the 4D generated 4D file.

Returns

• output (list) – Return the list of the pull path to roi files, in the order of concatenation. It should exactly follow the order you provide via the variable index_roi_number.

• See Also

• ——–

• nilearn.image.concat_img (This function concatenate a list of 3D NifTi images.) – We use this function to concatenate the images.

Notes

Each file you want to concatenate, must have a pattern to identifying them. Indeed, we use it to search the entire path corresponding to the file, and append it in a list containing all the path to the files in the right order before concatenation. The pattern is simply a number in the file name.

conpagnon.utils.array_operation.mask_array_std(arrays, masked_array, axis)

Compute the standard deviation of a ndimensional numpy array.

Parameters

• arrays (ndimensional numpy.array, shape (number of subjects, number of regions, number of regions)) – The ndimensional array you want to compute the mean.

• masked_array (ndimensional numpy.array, shape (.., numbers_of_regions, numbers_of_regions)) – The ndimensional boolean masked accounting for the values you want to discard. True for masked values, False elsewhere.

• axis (int) – The direction for computing the standard deviation.

Returns

output – The standard deviation array excluding some value in the direction along axis.

Return type

numpy.array shape (number of regions, number of regions)

See also

masked_void_rois_connectivity_matrix()

This function compute the boolean mask for accounting the discarded rois.

conpagnon.utils.array_operation.masked_arrays_mean(arrays, masked_array, axis)

Compute the arithmetic mean of a ndimensional numpy masked array.

Parameters

• arrays (ndimensional numpy.array, shape (.., number of regions, number of regions)) – The ndimensional array you want to compute the mean.

• masked_array (ndimensional numpy.array, shape (.., numbers_of_regions, numbers_of_regions)) – The ndimensional boolean masked accounting for the values you want to discard. True for masked values, False elsewhere.

• axis (int) – The direction for computing the mean.

Returns

output – The mean array excluding some value in the direction along axis.

Return type

numpy.array shape (number of regions, number of regions)

See also

masked_void_rois_connectivity_matrix()

This function compute the boolean mask for accounting the discarded rois.

conpagnon.utils.array_operation.masked_void_rois_connectivity_matrix(subject_kinds_connectivity, kinds, discard_diagonal=False, vectorize=False)

Compute a boolean mask array for discarded rois

Parameters

• subject_kinds_connectivity (dict) –

  The individual subject dictionnary containing as keys:

  • The different kinds

  • A keys called ‘discarded_rois’ for ROIs to discard during analysis

• kinds (list) – List of present kinds in the subjects connectivity matrices dictionnary.

• discard_diagonal (bool, optional) – If True, the diagonal are discarded in the vectorization process. Default is False, the diagonal is kept.

• vectorize (bool, optional) – If True, the returned mask is vectorized. Default is False

Returns

output – A boolean array : True when rois are considered discarded, False elsewhere See notes concerning the discarded roi

Return type

numpy.array, shape (number of regions, number of regions)

See also

compute_connectivity_matrices.individual_connectivity_matrices()

This is the function which compute the connectivity matrices for the chosen kinds, and return a structured dictionnary containing all the connectivity matrices for each subjects and kinds

Notes

A discarded rois, is a ROI where the corresponding labels is ‘void’ in the individual atlas of a given subject. This information is automatically gathered when you extract time series with an individual atlas for each subjects. We account for discarded rois when computing arithmetic mean, or performing t-test for examples by excluding them during the computation.

Excluding the discarded rois, is possible via the numpy.ma structure which build a numpy masked array that is a couple of a numerical array and a boolean array where True are masked values, and False are un-masked values.

Please refer to the numpy documentation for further details.

conpagnon.utils.array_operation.truncate(f, n)

Truncates/pads a float f to n decimal places without rounding

conpagnon.utils.array_operation.vec_to_matrix_boolean_mask(vectorized_mask, diagonal=None)

Reconstruct a ndim symmetrical boolean mask array giving a boolean vectorized mask.

Parameters

vectorized_mask (numpy.ndarray, shape(.., number of regions, number of regions)) – The vectorized boolean mask.

diagonalnumpy.array of shape(number of regions), optional

The diagonal to reconstruct if you discard the diagonal when you first vectorize the ndimensional mask array

Returns

output – The reconstruct ndimensional array of shape (…, numbers of regions, numbers of regions)

Return type

numpy.ndarray

See also

nilearn.connectome.sym_matrix_to_vec(), vec_to_sym_matrix()

vectorize_boolean_mask()

This function flatten a boolean ndimensional array.

conpagnon.utils.array_operation.vectorize_boolean_mask(symmetric_boolean_mask, discard_diagonal=False)

Vectorize the lower part of symmetric boolean mask.

Parameters

• symmetric_boolean_mask (numpy.array, shape(.., numbers of regions, numbers of regions)) – A ndimensional boolean numpy array.

• discard_diagonal (bool, optional) – If True, the values of the diagonal are not returned. Default is False.

Returns

output – The flatten ndimensional boolean mask of shape (…, n_features * (n_features + 1) / 2) if discard_diagonal is False and (…, (n_features - 1) * n_features / 2) otherwise.

Return type

numpy.ndarray

See also

nilearn.connectome.sym_matrix_to_vec(), vec_to_sym_matrix()

vec_to_matrix_boolean_mask()

This function reconstruct a flatten boolean ndimensional array.

conpagnon.utils.array_operation.vectorizer(numpy_array, discard_diagonal=False, array_type='numeric')

Vectorize a numerical or boolean numpy array

Parameters

• numpy_array (numpy.array, shape (n_features, n_features)) – A two-dimensional numerical, or boolean data type array.

• discard_diagonal (bool, optional) – If True, the lower triangle of the array is flatten without the diagonal. Default is False.

• array_type (string, optional) – Precise the array type, choices are {‘numeric’, boolean’}, default is ‘numeric’.

Returns

• output 1 (numpy.array, shape(n_features)) – The diagonal of the entered array.

• output 2 (numpy.array, shape( (n_features*(n_features+1))/2 ))

• is discard_diagonal is True, (n_features*(n_features-1))/2 else. – The vectorized array.

conpagnon.utils.folders_and_files_management module

Created on Thu Sep 21 13:34:12 2017

@author: db242421

Utilitary modules.

conpagnon.utils.folders_and_files_management.append_pdf(input, output)

Append a input pdf file to an output empty pdf file.

conpagnon.utils.folders_and_files_management.check_directories_existence(root_directory, directories_list)

Check if all directories supplied exist, raises an exception if not.

Parameters

• root_directory (str) – The full path to a root directory, containing multiple folders.

• directories_list (list) – List of directories you want to check for, in root_directory.

Raises

Exception – Raise an exception if one of the directories supplied do not exist.

conpagnon.utils.folders_and_files_management.create_directory(directory, erase_previous=False)

Create a directory, erase it and create it if it exist.

conpagnon.utils.folders_and_files_management.load_object(full_path_to_object)

Load a python object saved by a pickler operator.

Parameters

full_path_to_object (str) – The full path to the saved python object, including the .pkl extension.

Returns

output – The loaded python object.

Return type

python object

See also

save_object()

This function save a python object using the pickle module.

conpagnon.utils.folders_and_files_management.merge_pdfs(pdfs, output_filename)

Merge together a list of pdf files.

conpagnon.utils.folders_and_files_management.remove_empty_directories(root_directory)

Erase all empty directory at a root location.

Parameters

root_directory (str) – The full path to a directory.

conpagnon.utils.folders_and_files_management.save_object(object_to_save, saving_directory, filename)

Save a python object in pickle format.

Parameters

• object_to_save (a Python object structure) – A python that can be pickled : list, dict, integer, tuples, etc…

• saving_directory (str) – Full path to a saving directory.

• filename (str) – Filename of the saved object, including the extension .pkl.

See also

load_object()

This function load a python object save by this function.

Notes

See the pickle module for python object to see a exhausting list of what object can be saved.

conpagnon.utils.pre_preprocessing module

Created on Fri Oct 6 17:04:32 2017

@author: db242421 (dhaif.bekha@cea.fr)

Useful pre-processing step before doing statistical test.

conpagnon.utils.pre_preprocessing.fisher_transform(symmetric_array)

Return the Fisher transform of all coefficient in a symmetric array.

Parameters

symmetric_array (numpy.ndarray, shape(.., number of regions, numbers of regions)) – A symmetric numpy array, typically correlation, or partial correlation subject connectivity matrices.

Returns

output – The fisher transform of the ndimensional array.

Return type

numpy.ndarray, shape(.., number of regions, numbers of regions)

Notes

The fisher transform is classically computed according to the formula :

\[z = arctanh(r)\]

For r = 1, the Fisher transform is not defined, typically on the diagonal of connectivity matrices. Then we fill diagonal value with np.nan values.

conpagnon.utils.pre_preprocessing.stacked_connectivity_matrices(subjects_connectivity_matrices, kinds)

Stacked the connectivity matrices for each group and for each kinds.

If a masked array exist, i.e a ‘masked_array’ key in each subjects dictionnary, we stacked them too.

Parameters

• subjects_connectivity_matrices (dict) –

  A multi-levels dictionnary organised as follow :

  • The first keys levels is the different groupes in the study.

  • The second keys levels is the subjects IDs

  • The third levels is the different kind matrices

  for each subjects, a ‘discarded_rois’ key for the discarded rois array index, a ‘masked_array’ key containing the array of Boolean of True for the discarded_rois index, and False elsewhere.

• kinds (list) – List of kinds you are interrested in.

Returns

ouput – A dictionnary with two keys : kinds and masked_array. The values is respectively the stacked matrices for one kind in a ndimensional array of shape (…, numbers of regions, numbers of regions), and the ndimensional boolean mask array of the same shape (…, numbers of regions, numbers of regions).

Return type

dict

Module contents

Created on Thu Sep 21 14:08:13 2017

@author: db242421