Reference API

nispace.api - NiSpace main class

nispace.api

alias of <module ‘nispace.api’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/nispace/checkouts/stable/nispace/api.py’>

NiSpace(x[, y, z, x_labels, y_labels, ...])

The NiSpace class.

nispace.datasets - Dataset fetchers

nispace.datasets.fetch_collection(collection, dataset=None, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)

Fetch a collection to subset a map dataset.

Parameters:

• dataset (str | None) – str

• collection (str | Path | ndarray | DataFrame | Series | list) – Union[str, pathlib.Path, np.ndarray, pd.DataFrame, pd.Series, list]

• nispace_data_dir (str | Path | None) – Union[str, pathlib.Path]

• verbose (bool) – bool

• overwrite (bool) –

• check_file_hash (bool) –

nispace.datasets.fetch_example(example, parcellation=None, return_associated_data=True, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)

Fetch an example dataset.

Parameters:

• example (str) –

• parcellation (str | None) –

• return_associated_data (bool) –

• nispace_data_dir (str | Path | None) –

• overwrite (bool) –

• check_file_hash (bool) –

• verbose (bool) –

nispace.datasets.fetch_metadata(dataset, maps=None, collection=None, overwrite=False, check_file_hash=True, nispace_data_dir=None)

Parameters:

• dataset (str) –

• maps (str | list | None) –

• collection (str | None) –

• overwrite (bool) –

• check_file_hash (bool) –

• nispace_data_dir (str | Path | None) –

nispace.datasets.fetch_parcellation(parcellation='Schaefer200', space=None, hemi=['L', 'R'], return_labels=True, return_space=False, return_resolution=False, return_symmetric=False, return_l2rmap=False, return_dist_mat=False, return_loaded=True, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)

Fetch a parcellation.

Parameters:

• parcellation (str) –

• space (str | None) –

• hemi (List[str] | str) –

• return_labels (bool) –

• return_space (bool) –

• return_resolution (bool) –

• return_symmetric (bool) –

• return_l2rmap (bool) –

• return_dist_mat (bool) –

• return_loaded (bool) –

• nispace_data_dir (str | Path | None) –

• overwrite (bool) –

• check_file_hash (bool) –

• verbose (bool) –

nispace.datasets.fetch_reference(dataset, maps=None, space='MNI152NLin2009cAsym', collection=None, set_size_range=None, parcellation=None, standardize_parcellated=False, return_metadata=False, print_references=True, osf_config_file=None, github_config_file=None, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)

Parameters:

• dataset (str) –

• maps (None | str | List[str] | Dict[str, str | list]) –

• space (str) –

• collection (str | None) –

• set_size_range (None | Tuple[int, int]) –

• parcellation (str | None) –

• standardize_parcellated (bool) –

• return_metadata (bool) –

• print_references (bool) –

• osf_config_file (str | None) –

• github_config_file (str | None) –

• nispace_data_dir (str | Path | None) –

• overwrite (bool) –

• check_file_hash (bool) –

• verbose (bool) –

nispace.datasets.fetch_template(template='MNI152NLin2009cAsym', res=None, desc=None, hemi=['L', 'R'], nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)

Fetch a brain template.

Parameters:

• template (str, optional) – The template to fetch. Default is “MNI152NLin2009cAsym”.

• res (str, optional) – The resolution of the template to fetch. If None, will default to “1mm” for MNI152 and “10k” for fsaverage.

• desc (str, optional) – The description of the template to fetch. If None, will default to “T1w” for MNI152 and “pial” for fsaverage.

• hemi (list of str, optional) – The hemispheres to fetch. Default is [“L”, “R”].

• nispace_data_dir (str or pathlib.Path, optional) – The directory containing the NiSpace data. Default is None.

• overwrite (bool) –

• check_file_hash (bool) –

• verbose (bool) –

Return type:

The template.

nispace.datasets.keys2list(dct)

nispace.datasets.keys2str(dct, sep=', ')

fetch_template([template, res, desc, hemi, ...])	Fetch a brain template.
fetch_parcellation([parcellation, space, ...])	Fetch a parcellation.
fetch_reference(dataset[, maps, space, ...])
fetch_metadata(dataset[, maps, collection, ...])
fetch_example(example[, parcellation, ...])	Fetch an example dataset.

nispace.workflows - Workflows

nispace.workflows.group_comparison(y, design, x='PET', z=None, x_collection=None, standardize='xz', parcellation='Schaefer200', parcellation_labels=None, colocalization_method='spearman', comparison_method=None, paired=False, plot_design=True, combat=False, plot=True, n_perm=10000, seed=None, n_proc=1, verbose=True, nispace_object=None, fetch_x_kwargs={}, init_kwargs={}, clean_y_kwargs={}, transform_y_kwargs={}, colocalize_kwargs={}, permute_kwargs={}, correct_p_kwargs={}, plot_kwargs={})

nispace.workflows.simple_colocalization(y, x='PET', z=None, x_collection=None, standardize='xz', parcellation='Schaefer200', parcellation_labels=None, y_covariates=None, colocalization_method='spearman', p_from_average_y=False, plot=True, combat=False, n_perm=10000, seed=None, n_proc=1, verbose=True, nispace_object=None, fetch_x_kwargs={}, init_kwargs={}, clean_y_kwargs={}, colocalize_kwargs={}, permute_kwargs={}, correct_p_kwargs={}, plot_kwargs={})

Simple colocalization workflow.

Parameters:

• y (array-like or pandas DataFrame or list) – Input Y data to colocalize with X. Can be a numpy array, pandas DataFrame, (list of) path(s) to a file(s) or list of image objects.

• x (str or array-like, default="PET") – Input X data. Can be a string indicating a reference dataset (“PET”, “mRNA”, …), or inputs types as listed for y.

• z (array-like or None, default=None) – Optional confound data to regress out. Can be “gm”, or input types as listed for y.

• x_collection (str or None, default=None) – If x is a string reference dataset, specifies which collection to use.

• standardize (str, default="xz") – Which data to standardize. Can contain “x”, “y”, and/or “z”.

• parcellation (str or int, default=_PARC_DEFAULT) – Brain parcellation to use. Can be a string name or integer ID.

• parcellation_labels (array-like or None, default=None) – Optional labels for the parcellation regions.

• y_covariates (array-like or None, default=None) – Optional covariates to regress from Y data.

• colocalization_method (str or list, default="spearman") – Method(s) to use for colocalization. Can be “spearman”, “pearson”, etc.

• p_from_average_y (bool, default=False) – Whether to compute p-values from averaged Y values.

• plot (bool, default=True) – Whether to generate visualization plots.

• combat (bool, default=False) – Whether to apply ComBat harmonization.

• n_perm (int, default=10000) – Number of permutations for null distribution.

• seed (int or None, default=None) – Random seed for reproducibility.

• n_proc (int, default=-1) – Number of processes for parallel computation. -1 uses all CPUs.

• verbose (bool, default=True) – Whether to print progress messages.

• nispace_object (NiSpace or None, default=None) – Optional pre-initialized NiSpace object to use.

• fetch_x_kwargs (dict, default={}) – Additional arguments for fetching X data.

• init_kwargs (dict, default={}) – Additional arguments for NiSpace initialization.

• clean_y_kwargs (dict, default={}) – Additional arguments for Y data cleaning.

• colocalize_kwargs (dict, default={}) – Additional arguments for colocalization.

• permute_kwargs (dict, default={}) – Additional arguments for permutation testing.

• correct_p_kwargs (dict, default={}) – Additional arguments for p-value correction.

• plot_kwargs (dict, default={}) – Additional arguments for plotting.

Returns:

• colocs (dict or array) – Colocalization values for each method.

• p_values (dict or array) – Uncorrected p-values for each method.

• p_fdr_values (dict or array) – FDR-corrected p-values for each method.

• nsp (NiSpace) – The NiSpace object containing all results.

nispace.workflows.simple_xsea(y, x='mRNA', z=None, x_collection=None, x_background=None, standardize='xz', parcellation='Schaefer200', parcellation_labels=None, y_covariates=None, colocalization_method='spearman', xsea_aggregation_method='mean', permute_sets=False, p_from_average_y=False, plot=True, combat=False, n_perm=10000, seed=None, n_proc=1, verbose=True, nispace_object=None, fetch_x_kwargs={}, init_kwargs={}, clean_y_kwargs={}, colocalize_kwargs={}, permute_kwargs={}, correct_p_kwargs={}, plot_kwargs={})

simple_colocalization(y[, x, z, ...])	Simple colocalization workflow.
group_comparison(y, design[, x, z, ...])
simple_xsea(y[, x, z, x_collection, ...])

nispace.stats.coloc - Colocalization statistics

nispace.stats.coloc.beta(x, y, intercept=True)

Compute beta coefficients for Regression of predictor(s) x on target y. Requires numpy arrays with columns as predictors/target.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• intercept (bool, optional) – Return intercept in leading position of beta array or omit

Returns:

1D array of beta coefficients (w or w/o intercept)

Return type:

numpy.ndarray

nispace.stats.coloc.corr(x, y, rank=False)

Compute Pearson or Spearman correlation for two 1D arrays.

nispace.stats.coloc.dominance(x, y, adj_r2=False, verbose=True)

nispace.stats.coloc.elasticnet(x, y, cv=None, seed=None, **kwargs)

nispace.stats.coloc.lasso(x, y, cv=None, seed=None, kwargs={})

nispace.stats.coloc.mlr(x, y, adj_r2=True, intercept=True)

Compute Regression of predictor(s) x on target y. Requires numpy arrays with columns as predictors/target.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• adj_r2 (bool, optional) – Calculate adjusted R2. Defaults to True.

• intercept (bool, optional) – Return intercept in leading position of beta array or omit

Returns:

(adjusted) R2 array: parameters, starting with or w/o intercept

Return type:

float

nispace.stats.coloc.mutualinfo(x, y, n_neighbors=3)

Compute mutual information between x and y using sklearn.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• n_neighbors (int, optional) – Number of neighbors for MI estimation. Defaults to 3.

Returns:

mutual information between x and y

Return type:

float

nispace.stats.coloc.partialcorr(x, y, z, rank=False)

Computes partial correlation between {x} and {y} controlled for {z}

Parameters:

• x (array-like) – input vector 1

• y (array-like) – input vector 2

• z (array-like) – input vector to be controlled for

• rank (bool, optional) – True or False. Defaults to False. -> Pearson correlation

Returns:

(ranked) partial correlation coefficient between x and y

Return type:

rp (float)

nispace.stats.coloc.pcr(x, y, adj_r2=True, n_components=inf, **kwargs)

nispace.stats.coloc.pls(x, y, n_components=inf, **kwargs)

nispace.stats.coloc.r2(x, y, adj_r2=True)

Compute R2 for Regression of predictor(s) x on target y. Requires numpy arrays with columns as predictors/target.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• adj_r2 (bool, optional) – Calculate adjusted R2. Defaults to True.

Returns:

(adjusted) R2

Return type:

float

nispace.stats.coloc.rank_array(array)

Rank an array. CAVE: Cannot really deal with nan’s!

nispace.stats.coloc.ridge(x, y, cv=None, seed=None, kwargs={})

rank_array(array)	Rank an array.
corr(x, y[, rank])	Compute Pearson or Spearman correlation for two 1D arrays.
partialcorr(x, y, z[, rank])	Computes partial correlation between {x} and {y} controlled for {z}
mlr(x, y[, adj_r2, intercept])	Compute Regression of predictor(s) x on target y.
r2(x, y[, adj_r2])	Compute R2 for Regression of predictor(s) x on target y.
beta(x, y[, intercept])	Compute beta coefficients for Regression of predictor(s) x on target y.
dominance(x, y[, adj_r2, verbose])
pls(x, y[, n_components])
pcr(x, y[, adj_r2, n_components])
elasticnet(x, y[, cv, seed])
lasso(x, y[, cv, seed, kwargs])
ridge(x, y[, cv, seed, kwargs])

nispace.stats.effectsize - Effect size calculation

nispace.stats.effectsize.cohen(a, b)

nispace.stats.effectsize.cohen_nan(a, b)

nispace.stats.effectsize.cohen_paired(a, b)

nispace.stats.effectsize.cohen_paired_nan(a, b)

nispace.stats.effectsize.hedges(a, b)

nispace.stats.effectsize.hedges_nan(a, b)

nispace.stats.effectsize.hedges_paired(a, b)

nispace.stats.effectsize.prc(a, b)

nispace.stats.effectsize.zscore(a, b=None)

nispace.stats.effectsize.zscore_nan(a, b=None)

cohen(a, b)
cohen_nan(a, b)
cohen_paired(a, b)
cohen_paired_nan(a, b)
hedges(a, b)
hedges_nan(a, b)
hedges_paired(a, b)
zscore(a[, b])
zscore_nan(a[, b])
prc(a, b)

nispace.stats.misc - Miscellaneous stats functions

nispace.stats.misc.mc_correction(p_array, alpha=0.05, method='fdr_bh', how='array', dtype=None)

nispace.stats.misc.np_any_axis1(x)

Numba compatible version of np.any(x, axis=1).

nispace.stats.misc.null_to_p(test_value, null_array, tail='two', fit_norm=False)

Return p-value for test value(s) against null array.

Adopted from NiMARE v0.0.12: https://zenodo.org/record/6600700 (NiMARE/nimare/stats.py)

Parameters:

• test_value (1D array_like) – Values for which to determine p-value.

• null_array (1D array_like) – Null distribution against which test_value is compared.

• tail ({'two', 'upper', 'lower'}, optional) – Whether to compare value against null distribution in a two-sided (‘two’) or one-sided (‘upper’ or ‘lower’) manner. If ‘upper’, then higher values for the test_value are more significant. If ‘lower’, then lower values for the test_value are more significant. Default is ‘two’.

• fit_norm (boolean) – Whether to fit a normal distribution to null_array data and compute p values from that. Might be useful if the relative order of multiple highly significant p values is of interest, but the number of null values cannot be increased sufficiently.

Returns:

p_value – P-value(s) associated with the test value when compared against the null distribution. Return type matches input type (i.e., a float if test_value is a single float, and an array if test_value is an array).

Return type:

float

Notes

P-values are clipped based on the number of elements in the null array, if fit_norm=False. In this case, no p-values of 0 or 1 should be produced.

nispace.stats.misc.permute_groups(groups, strategy='proportional', paired=False, subjects=None, n_perm=1, n_proc=1, seed=None, verbose=False)

nispace.stats.misc.residuals(x, y, decenter=False)

Compute residuals for Regression with dependent variable y and independent variable(s) x. Requires numpy arrays with columns as independent variables.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• decenter (bool, optional) – add mean of y to residuals before return

Returns:

1D array of residuals w or w/o added mean of y

Return type:

numpy.ndarray

nispace.stats.misc.residuals_nan(x, y, decenter=False)

Compute residuals for Regression with dependent variable y and independent variable(s) x. Requires numpy arrays with columns as independent variables.

Parameters:

• x (numpy.ndarray) – shape (n_values, n_predictors)

• y (numpy.ndarray) – shape (n_values, 1) or (n_values,)

• decenter (bool, optional) – add mean of y to residuals before return

Returns:

1D array of residuals w or w/o added mean of y

Return type:

numpy.ndarray

nispace.stats.misc.rho_to_z(array, replace_1=np.float64(0.9999999999999998))

Fisher’s z-transformation of correlation coefficients.

nispace.stats.misc.zscore_df(df, along='cols', force_df=True)

Z-standardizes array and returns pandas dataframe.

Parameters:

• df (pandas dataframe) – input dataframe

• along (str, optional) – Either “cols” or “rows”. Defaults to “cols”.

Returns:

standardized dataframe/series

Return type:

pd.DataFrame or pd.Series

np_any_axis1(x)	Numba compatible version of np.any(x, axis=1).
residuals(x, y[, decenter])	Compute residuals for Regression with dependent variable y and independent variable(s) x.
residuals_nan(x, y[, decenter])	Compute residuals for Regression with dependent variable y and independent variable(s) x.
rho_to_z(array[, replace_1])	Fisher's z-transformation of correlation coefficients.
zscore_df(df[, along, force_df])	Z-standardizes array and returns pandas dataframe.
permute_groups(groups[, strategy, paired, ...])
null_to_p(test_value, null_array[, tail, ...])	Return p-value for test value(s) against null array.
mc_correction(p_array[, alpha, method, how, ...])

nispace.io - Imaging data input

nispace.io.from_pickle(filepath, use_dill=False)

Unpickle a python object.

nispace.io.load_distmat(distmat)

nispace.io.load_img(img, override_file_format=False)

nispace.io.load_l2rmap(l2rmap, header=0, index=0)

nispace.io.load_labels(labels, concat=True, header=None, index=None)

nispace.io.parcellate_data(data, data_labels=None, data_space=None, parcellation=None, parc_labels=None, parc_space=None, parc_hemi=None, resampling_target='data', drop_background_parcels=True, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None, return_parc=False, dtype=None, n_proc=1, verbose=True, ignore_zero_division_warning=True)

Parcellates given imaging data using a specified parcellation.

Parameters:

• parcellation (str, os.PathLike, nib.Nifti1Image, nib.GiftiImage, or tuple) – The parcellation image or surfaces, where each region is identified by a unique integer ID.

• parc_labels (list) – Labels for the parcellation regions.

• parc_space (str) – The space in which the parcellation is defined.

• parc_hemi (list of str) – Hemispheres to consider for parcellation, e.g., [“L”, “R”].

• resampling_target ({'data', 'parcellation'}) – Specifies which image gives the final shape/size.

• data (list, dict, pd.DataFrame, pd.Series, or np.ndarray) – The imaging data to be parcellated.

• data_labels (list) – Labels for the input data.

• data_space (str) – The space in which the input data is defined.

• drop_background_parcels (bool) – Whether to drop parcels that contain only background intensity.

• min_num_valid_datapoints (int, optional) – Minimum number of valid datapoints required per parcel.

• min_fraction_valid_datapoints (float, optional) – Minimum fraction of valid datapoints required per parcel.

• n_proc (int) – Number of processors to use for parallel processing.

• dtype (data-type) – Desired data type of the output.

Returns:

Parcellated data in a DataFrame.

Return type:

pd.DataFrame

Raises:

• TypeError – If the input data type is not recognized.

• ValueError – If the resampling target is invalid.

Notes

This function handles different types of input data, including lists, DataFrames, Series, and ndarrays. It also manages different parcellation formats and resampling targets.

nispace.io.read_json(json_path)

nispace.io.to_pickle(obj, filepath, use_dill=False)

Pickle, compress, and save to a file.

Parameters:

• obj (object) – Any python object to be pickled.

• filepath (str) – File path destination.

nispace.io.write_json(json_dict, json_path)

parcellate_data(data[, data_labels, ...])	Parcellates given imaging data using a specified parcellation.
read_json(json_path)
write_json(json_dict, json_path)
load_img(img[, override_file_format])
load_labels(labels[, concat, header, index])
load_distmat(distmat)

nispace.parcellate - Parcellation class

Functionality for parcellating data, copied from neuromaps 0.0.4 and adapted for convenient use in NiSpace

class nispace.parcellate.Parcellater(parcellation, space, resampling_target='data', hemi=None)

Bases: object

Class for parcellating arbitrary volumetric / surface data. Copied from neuromaps 0.0.4 and adapted for convenient use in NiSpace.

Parameters:

• parcellation (str or os.PathLike or Nifti1Image or GiftiImage or tuple) – Parcellation image or surfaces, where each region is identified by a unique integer ID. All regions with an ID of 0 are ignored.

• space (str) – The space in which parcellation is defined

• resampling_target ({'data', 'parcellation', None}, optional) – Gives which image gives the final shape/size. For example, if resampling_target is ‘data’, the parcellation is resampled to the space + resolution of the data, if needed. If it is ‘parcellation’ then any data provided to .fit() are transformed to the space + resolution of parcellation. Providing None means no resampling; if spaces + resolutions of the parcellation and data provided to .fit() do not match a ValueError is raised. Default: ‘data’

• hemi ({'L', 'R'}, optional) – If provided parcellation represents only one hemisphere of a surface atlas then this specifies which hemisphere. If not specified it is assumed that parcellation is (L, R) hemisphere. Ignored if space is ‘MNI152’. Default: None

• labels (list, optional) – List of labels corresponding to indices in parcellation file

fit()

Prepare parcellation for data extraction

fit_transform(data, space, ignore_background_data=True, background_value=None, hemi=None, fill_dropped=True, background_parcels_to_nan=True, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None)

Prepare and perform parcellation of data

inverse_transform(data)

Project data to space + density of parcellation

Parameters:

data (array_like) – Parcellated data to be projected to the space of parcellation

Returns:

data – Provided data in space + resolution of parcellation

Return type:

Nifti1Image or tuple-of-nib.GiftiImage

transform(data, space, ignore_background_data=True, background_value=None, hemi=None, fill_dropped=True, background_parcels_to_nan=True, min_num_valid_datapoints=None, min_fraction_valid_datapoints=None)

Applies parcellation to data in space

Parameters:

• data (str or os.PathLike or Nifti1Image or GiftiImage or tuple) – Data to parcellate

• space (str) – The space in which data is defined

• hemi ({'L', 'R'}, optional) – If provided data represents only one hemisphere of a surface dataset then this specifies which hemisphere. If not specified it is assumed that data is (L, R) hemisphere. Ignored if space is ‘MNI152’. Default: None

• ignore_background_data (bool) – Specifies whether the background data values should be ignored when computing the average data within each parcel. If set to True and background_value is set to None, the background_value is estimated from the data: if there are NaNs in the data, the background value is set to NaN. Otherwise, it is estimated as the median of the values on the border of the images for volumetric images or as the median of the values within the medial wall for surface images. The background value can also be set manually using the background_value parameter. Default: False

• background_value (float) – Specifies the background value to ignore when computing the averages and when ignore_background_data is True. Default: None

Returns:

parcellated – Parcellated data

Return type:

np.ndarray

Parcellater(parcellation, space[, ...])

Class for parcellating arbitrary volumetric / surface data.

nispace.nulls - Null map generation

nispace.nulls.correlate_hemis_parc(data, parc_idc_lh=None, parc_idc_rh=None, l2rmap=None, rank=False)

nispace.nulls.find_surf_parc_centroids(parc, parc_hemi, parc_density='10k')

nispace.nulls.find_vol_parc_centroids(parc, affine=None, parcel_idc=None, return_data_space=False)

nispace.nulls.generate_null_maps(method, data, parcellation, dist_mat=None, parc_space=None, parc_hemi=None, parc_symmetric=False, n_nulls=1000, parc_resample=2, centroids=False, parc_idc_lh=None, parc_idc_rh=None, parc_idc_sc=None, lr_mirror_dist_mat=False, lr_mirror_null_maps=False, l2rmap=None, match_interhemi_correlation=True, report_interhemi_correlation=False, cx_sc_minmax_scale=False, dtype=<class 'float'>, n_proc=1, seed=None, verbose=True, **kwargs)

nispace.nulls.get_distance_matrix(parc, parc_space, parc_hemi=['L', 'R'], parc_resample=2, centroids=False, surf_euclidean=False, n_proc=1, verbose=True, dtype=<class 'numpy.float32'>)

nispace.nulls.nulls_burt2018(data_1d, dist_mat, n_nulls=1000, seed=None, **kwargs)

nispace.nulls.nulls_burt2020(data_1d, dist_mat, n_nulls=1000, seed=None, **kwargs)

nispace.nulls.nulls_moran(data_1d, dist_mat, n_nulls=1000, seed=None, **kwargs)

nispace.nulls.nulls_random(data_1d, dist_mat=None, n_nulls=1000, seed=None)

generate_null_maps(method, data, parcellation)
nulls_moran(data_1d, dist_mat[, n_nulls, seed])
nulls_burt2020(data_1d, dist_mat[, n_nulls, ...])
nulls_burt2018(data_1d, dist_mat[, n_nulls, ...])
get_distance_matrix(parc, parc_space[, ...])
find_surf_parc_centroids(parc, parc_hemi[, ...])

nispace.plotting - Plotting functions

nispace.plotting.catplot(fig, ax, data_long, categorical_var='variable', continuous_var='value', group_var=None, categorical_axis='x', sort_categories=False, category_order=None, color_how='continuous', color_which='auto', color_center=None, labels={}, limits={}, bars={}, violins={}, scatters={}, dots={}, errorbars={}, hline={}, vline={}, legend={})

nispace.plotting.colors_from_values(values, palette_name)

nispace.plotting.heatmap(ax, data_colors=None, data_sizes=None, data_shapes=None, mapping_shapes=None, annotation=None, mask=None, cmap='auto', symmetric_cmap=True, size_scale=(0.2, 1), shape='square', color='tab:blue', edgecolor='k', linewidth=0.075, square=True, spines=False, spinewidth=0.1, spinecolor='k', xy_pad=0.1, xtick_labels=None, ytick_labels=None, legend_orientation='vertical', legend_colors=True, legend_colors_kwargs={}, legend_sizes=True, legend_sizes_kwargs={}, legend_shapes=True, legend_shapes_kwargs={})

nispace.plotting.hide_empty_axes(axes)

nispace.plotting.linewidth_from_data_units(linewidth, axis, reference='x')

Convert a linewidth in data units to linewidth in points.

Parameters:

• linewidth (float) – Linewidth in data units of the respective reference-axis

• axis (matplotlib axis) – The axis which is used to extract the relevant transformation data (data limits and size must not change afterwards)

• reference (string) – The axis that is taken as a reference for the data width. Possible values: ‘x’ and ‘y’. Defaults to ‘y’.

Returns:

linewidth – Linewidth in points

Return type:

float

nispace.plotting.move_legend_fig_to_ax(fig, ax, loc, bbox_to_anchor=None, no_legend_error=False, **kwargs)

nispace.plotting.nice_stats_labels(string, add_dollars=True)

nispace.plotting.nullplot(fig, ax, data_long, categorical_var='variable', continuous_var='value', categorical_axis='x', category_order=None, color_which='viridis_r', quantiles_below_median=[0.01, 0.05, 0.25], bands={}, median_line={}, violins={}, labels={}, limits={}, legend={})

nispace.plotting.print_significance(ax, p_values, q_values=None, coloc_values=None, bold_labels=True, pq_symbols=['☆', '★'], pq_size=12, pq_positions=None, pq_positions_pad=0, categorical_axis='y')

nispace.plotting.view_surf(data=None, parcellation=None, hemi='L', template='fsaverage', replace_nan=0, template_kwargs={}, parcellation_kwargs={}, verbose=False, **kwargs)

catplot(fig, ax, data_long[, ...])
nullplot(fig, ax, data_long[, ...])
heatmap(ax[, data_colors, data_sizes, ...])
move_legend_fig_to_ax(fig, ax, loc[, ...])
colors_from_values(values, palette_name)
hide_empty_axes(axes)
linewidth_from_data_units(linewidth, axis[, ...])	Convert a linewidth in data units to linewidth in points.

nispace.utils - Utility functions

class nispace.utils.utils.CriticalRaiseLogger(name, level=0)

Bases: Logger

addFilter(filter)

Add the specified filter to this handler.

addHandler(hdlr)

Add the specified handler to this logger.

callHandlers(record)

Pass a record to all relevant handlers.

Loop through all handlers for this logger and its parents in the logger hierarchy. If no handler was found, output a one-off error message to sys.stderr. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger whose handlers are called.

critical(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

critical_raise(message, error=<class 'Exception'>)

Log a critical message and raise an error.

Parameters: - message: Message to log - error: Exception class to raise

debug(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

error(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

exception(msg, *args, exc_info=True, **kwargs)

Convenience method for logging an ERROR with exception information.

fatal(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

filter(record)

Determine if a record is loggable by consulting all the filters.

The default is to allow the record to be logged; any filter can veto this and the record is then dropped. Returns a zero value if a record is to be dropped, else non-zero.

Changed in version 3.2: Allow filters to be just callables.

findCaller(stack_info=False, stacklevel=1)

Find the stack frame of the caller so that we can note the source file name, line number and function name.

getChild(suffix)

Get a logger which is a descendant to this one.

This is a convenience method, such that

logging.getLogger(‘abc’).getChild(‘def.ghi’)

is the same as

logging.getLogger(‘abc.def.ghi’)

It’s useful, for example, when the parent logger is named using __name__ rather than a literal string.

getEffectiveLevel()

Get the effective level for this logger.

Loop through this logger and its parents in the logger hierarchy, looking for a non-zero logging level. Return the first one found.

handle(record)

Call the handlers for the specified record.

This method is used for unpickled records received from a socket, as well as those created locally. Logger-level filtering is applied.

hasHandlers()

See if this logger has any handlers configured.

Loop through all handlers for this logger and its parents in the logger hierarchy. Return True if a handler was found, else False. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger which is checked for the existence of handlers.

info(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

isEnabledFor(level)

Is this logger enabled for level ‘level’?

log(level, msg, *args, **kwargs)

Log ‘msg % args’ with the integer severity ‘level’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.log(level, “We have a %s”, “mysterious problem”, exc_info=1)

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

A factory method which can be overridden in subclasses to create specialized LogRecords.

manager = <logging.Manager object>

removeFilter(filter)

Remove the specified filter from this handler.

removeHandler(hdlr)

Remove the specified handler from this logger.

root = <RootLogger root (WARNING)>

setLevel(level)

Set the logging level of this logger. level must be an int or a str.

warn(msg, *args, **kwargs)

warning(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)

nispace.utils.utils.correlate_hemispheres(img, mask=None)

nispace.utils.utils.correlated_vector(data_1d, correlation=1, seed=None)

nispace.utils.utils.fill_nan(data, idx, idx_label=None, which='col')

nispace.utils.utils.get_background_value(img, border_size=2)

nispace.utils.utils.get_column_names(df_or_series, force_list=False)

Get column names from a DataFrame, the name from a Series, or None if input is a numpy array.

Parameters: df_or_series (pd.DataFrame, pd.Series, or np.ndarray): The DataFrame, Series, or numpy array to get the names from.

Returns: list or None: List of column names if input is a DataFrame, str if input is a Series, or None if input is a numpy array. If force_list is True, will always return a list.

nispace.utils.utils.lower(str_list)

nispace.utils.utils.mean_by_set_df(df, mean_by_set=True, weighted=True, mean_median='mean')

nispace.utils.utils.merge_parcellations(parcellations, labels=None, quick=False)

nispace.utils.utils.mirror_gifti(img, direction='left_to_right', match_r=False, mask=None)

nispace.utils.utils.mirror_nifti(img, affine=None, direction='left_to_right', match_r=False, mask=None)

nispace.utils.utils.nan_detector(*arrays)

nispace.utils.utils.parc_vect_to_vol(vect, parc)

nispace.utils.utils.print_arg_pairs(**kwargs)

nispace.utils.utils.relabel_gifti_parc(parc, new_labels=None)

nispace.utils.utils.relabel_nifti_parc(parc, new_order=None, new_labels=None, dtype=None)

nispace.utils.utils.remove_nan(data, which='col')

nispace.utils.utils.set_log(lgr, verbose=True)

nispace.utils.utils.vect_to_vol_arr(vect, parc_arr, parc_idc, bg_value=0)

nispace.utils.utils.vol_to_vect_arr(vol_arr, parc_arr, parc_idc, bg_value=0)

set_log(lgr[, verbose])
nan_detector(*arrays)
remove_nan(data[, which])
fill_nan(data, idx[, idx_label, which])
print_arg_pairs(**kwargs)
get_column_names(df_or_series[, force_list])	Get column names from a DataFrame, the name from a Series, or None if input is a numpy array.
lower(str_list)
get_background_value(img[, border_size])
parc_vect_to_vol(vect, parc)
relabel_gifti_parc(parc[, new_labels])