scilpy.io package
scilpy.io.btensor module
- scilpy.io.btensor.convert_bdelta_to_bshape(b_deltas)[source]
Convert an array of b_deltas to an array of b_shapes.
- Parameters:
b_deltas (array of floats) – b_deltas to convert. Floats can only be 1, 0, -0.5 or 0.5.
- Returns:
b_shapes – Converted b_shapes, such that LTE = 1, STE = 0, PTE = -0.5, CTE = 0.5.
- Return type:
array of strings
- scilpy.io.btensor.convert_bshape_to_bdelta(b_shapes)[source]
Convert an array of b_shapes to an array of b_deltas.
- Parameters:
b_shapes (array of strings) – b_shapes to convert. Strings can only be LTE, PTE, STE or CTE.
- Returns:
b_deltas – Converted b_deltas, such that LTE = 1, STE = 0, PTE = -0.5, CTE = 0.5.
- Return type:
array of floats
- scilpy.io.btensor.generate_btensor_input(in_dwis, in_bvals, in_bvecs, in_bdeltas, do_pa_signals=False, tol=20, skip_b0_check=False)[source]
Generate b-tensor input from an ensemble of data, bvals and bvecs files. This generated input is mandatory for all scripts using b-tensor encoding data. Also generate the powder-averaged (PA) data if set.
For the moment, this does not enable the use of a b0_threshold different than the tolerance.
- Parameters:
in_dwis (list of strings (file paths)) – Diffusion data files for each b-tensor encodings.
in_bvals (list of strings (file paths)) – All of the bvals files associated.
in_bvecs (list of strings (file paths)) – All of the bvecs files associated.
in_bdeltas (list of floats) – All of the b_deltas (describing the type of encoding) files associated.
do_pa_signals (bool, optional) – If set, will compute the powder_averaged input instead of the regular one. This means that the signal is averaged over all directions for each bvals.
tol (int) – tolerance gap for b-values clustering. Defaults to 20
skip_b0_check (bool) – (See full explanation in io.utils.add_skip_b0_check_arg.) If true, script will continue even if no b-values are found below the tolerance (no b0s found).
- Returns:
gtab_full (GradientTable) – A single gradient table containing the information of all encodings.
data_full (np.ndarray (4d)) – All concatenated diffusion data from the different encodings.
ubvals_full (array) – All the unique bvals from the different encodings, but with a single b0. If two or more encodings have the same bvalue, then they are differentiate by +1.
ub_deltas_full (array) – All the b_delta values associated with ubvals_full.
pa_signals (np.ndarray (4d) (if do_pa_signals)) – Powder-averaged diffusion data.
gtab_infos (np.ndarray (if do_pa_signals)) – Contains information about the gtab, such as the unique bvals, the encoding types, the number of directions and the acquisition index.
scilpy.io.deprecator module
scilpy.io.fetcher module
- scilpy.io.fetcher.download_file_from_google_drive(url, destination)[source]
Download large file from Google Drive. :param id: id of file to be downloaded :type id: str :param destination: path to destination file with its name and extension :type destination: str
- scilpy.io.fetcher.fetch_data(files_dict, keys=None)[source]
Fetch data. Typical use would be with gdown. But with too many data accesses, downloaded become denied. Using trick from https://github.com/wkentaro/gdown/issues/43.
scilpy.io.gradients module
- scilpy.io.gradients.fsl2mrtrix(fsl_bval_filename, fsl_bvec_filename, mrtrix_filename)[source]
Convert a fsl dir_grad.bvec/.bval files to mrtrix encoding.b file. Saves the result.
- Parameters:
fsl_bval_filename (str) – path to input fsl bval file.
fsl_bvec_filename (str) – path to input fsl bvec file.
mrtrix_filename (str) – path to output mrtrix encoding.b file.
- scilpy.io.gradients.mrtrix2fsl(mrtrix_filename, fsl_filename)[source]
Convert a mrtrix encoding.b file to fsl dir_grad.bvec/.bval files. Saves the result.
- Parameters:
mrtrix_filename (str) – path to mrtrix encoding.b file.
fsl_filename (str) – path to the output fsl files. Files will be named fsl_bval_filename.bval and fsl_bval_filename.bvec.
- scilpy.io.gradients.save_gradient_sampling_fsl(bvecs, shell_idx, bvals, filename_bval, filename_bvec)[source]
Save table gradient (FSL format)
- Parameters:
bvecs (numpy.array) – bvecs normalized to 1.
shell_idx (numpy.array) – Shell index for bvecs.
bvals (numpy.array)
filename_bval (str) – output bval filename.
filename_bvec (str) – output bvec filename.
------
scilpy.io.image module
- scilpy.io.image.assert_same_resolution(images)[source]
Check the resolution of multiple images. :param images: List of images or an image. :type images: list of string or string
- scilpy.io.image.get_data_as_mask(mask_img, dtype=<class 'numpy.uint8'>)[source]
Get data as mask (force type np.uint8 or bool), check data type before casting.
- Parameters:
mask_img (nibabel.nifti1.Nifti1Image) – Mask image.
dtype (type or str) – Data type for the output data (default: uint8)
- Returns:
data – Data (dtype : np.uint8 or bool).
- Return type:
numpy.ndarray
- scilpy.io.image.merge_labels_into_mask(atlas, filtering_args)[source]
Merge labels into a mask.
- Parameters:
atlas (np.ndarray) – Atlas with labels as a numpy array (uint16) to merge.
filtering_args (str) – Filtering arguments from the command line.
- Returns:
mask – Mask obtained from the combination of multiple labels.
- Return type:
nibabel.nifti1.Nifti1Image
scilpy.io.streamlines module
- scilpy.io.streamlines.check_tracts_same_format(parser, tractogram_1, tractogram_2)[source]
Assert that two filepaths have the same valid extension. :param parser: argparse.ArgumentParser object :param tractogram_1: Tractogram filename #1 :param tractogram_2: Tractogram filename #2
- scilpy.io.streamlines.ichunk(sequence, n)[source]
Yield successive n-sized chunks from sequence.
- Parameters:
sequence (numpy.ndarray) – streamlines
n (int) – amount of streamlines to load
- Returns:
chunk – subset of streamlines
- Return type:
list
- scilpy.io.streamlines.load_dpp_files_as_dpp(parser, dpp_files, sft, keys=None, overwrite=False)[source]
Load dpp information. They must be scalar values.
- Parameters:
parser (parser)
dpp_files (list[str]) – Either .npy or .txt files.
sft (StatefulTractogram)
keys (list[str]) – If None, use the filenames as keys.
overwrite (bool) – If True, allow overwriting an existing dpp key.
- Returns:
sft (StatefulTractogram) – The modified SFT. (Note that it is modified in-place even if the returned variable is not used!)
new_keys (list[str]) – Added keys.
- scilpy.io.streamlines.load_dps_files_as_dps(parser, dps_files, sft, keys=None, overwrite=False)[source]
Load dps information. They must be scalar values.
- Parameters:
parser (parser)
dps_files (list[str]) – Either .npy or .txt files.
sft (StatefulTractogram)
keys (list[str]) – If None, use the filenames as keys.
overwrite (bool) – If True, allow overwriting an existing dps key.
- Returns:
sft (StatefulTractogram) – The modified SFT. (Note that it is modified in-place even if the returned variable is not used!)
new_keys (list[str]) – Added keys.
- scilpy.io.streamlines.load_tractogram_with_reference(parser, args, filepath, arg_name=None)[source]
- Parameters:
parser (Argument Parser) – Used to print errors, if any.
args (Namespace) – Parsed arguments. Used to get the ‘reference’ and ‘bbox_check’ args. See scilpy.io.utils to add the arguments to your parser.
filepath (str) – Path of the tractogram file.
arg_name (str, optional) – Name of the reference argument. By default the args.ref is used. If arg_name is given, then args.arg_name_ref will be used instead.
- scilpy.io.streamlines.reconstruct_streamlines(data, offsets, lengths, indices=None)[source]
Function to reconstruct streamlines from its data, offsets and lengths (from the nibabel tractogram object).
- Parameters:
data (np.ndarray) – Nx3 array representing all points of the streamlines.
offsets (np.ndarray) – Nx1 array representing the cumsum of length array.
lengths (np.ndarray) – Nx1 array representing the length of each streamline.
indices (list) – List of int representing the indices to reconstruct.
- Returns:
streamlines – List of streamlines.
- Return type:
list of np.ndarray
- scilpy.io.streamlines.reconstruct_streamlines_from_memmap(memmap_filenames, indices=None, strs_dtype='float32')[source]
Function to reconstruct streamlines from memmaps, mainly to facilitate multiprocessing and decrease RAM usage.
- Parameters:
memmap_filenames (tuple) – Tuple of 3 filepath to numpy memmap (data, offsets, lengths).
indices (list) – List of int representing the indices to reconstruct.
- Returns:
streamlines – List of streamlines.
- Return type:
list of np.ndarray
- scilpy.io.streamlines.streamlines_to_memmap(input_streamlines, strs_dtype='float32')[source]
Function to decompose on disk the array_sequence into its components. :param input_streamlines: All streamlines of the tractogram to segment. :type input_streamlines: ArraySequence
- Returns:
tmp_obj – Temporary directory and tuple of filenames for the data, offsets and lengths.
- Return type:
tuple
- scilpy.io.streamlines.verify_compatibility_with_reference_sft(ref_sft, files_to_verify, parser, args)[source]
Verifies the compatibility of a reference sft with a list of files.
Params
- ref_sft: StatefulTractogram
A tractogram to be used as reference.
- files_to_verify: List[str]
List of files that should be compatible with the reference sft. Files can be either other tractograms or nifti files (ex: masks).
- parser: argument parser
Will raise an error if a file is not compatible.
- args: Namespace
Should contain a args.reference if any file is a .tck, and possibly a args.bbox_check (set to True by default).
scilpy.io.tensor module
- scilpy.io.tensor.convert_tensor_format(tensor, initial_format, final_format)[source]
See description of formats at the top of this file.
scilpy.io.utils module
- scilpy.io.utils.add_compression_arg(p, additional_msg='')[source]
- Parameters:
p (ArgumentParser) – Paser
additional_msg (str) – Any additional message to be displayed after explanation on the compress arg.
- scilpy.io.utils.add_default_screenshot_args(parser, slice_ids_mandatory=True, transparency_mask_mandatory=True, disable_annotations=False, slicing_parsing_group=None, annotation_parsing_group=None, cmap_parsing_group=None, opacity_parsing_group=None)[source]
Add default arguments for nifti screenshotting.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
slice_ids_mandatory (bool, optional) – Whether the slice_ids argument is mandatory.
transparency_mask_mandatory (bool, optional) – Whether the transparency mask argument is mandatory.
disable_annotations (bool, optional) – Whether to disable annotations arguments.
slicing_parsing_group (argparse.ArgumentParser object, optional) – Group to add slicing arguments to, defaults to parser.
annotation_parsing_group (argparse.ArgumentParser object, optional) – Group to add annotation arguments to, defaults to parser.
cmap_parsing_group (argparse.ArgumentParser object, optional) – Group to add colormap arguments to, defaults to parser.
opacity_parsing_group (argparse.ArgumentParser object, optional) – Group to add opacity arguments to, defaults to parser.
- scilpy.io.utils.add_labelmap_screenshot_args(parser, default_cmap=None, default_alpha=0.5, cmap_parsing_group=None, opacity_parsing_group=None)[source]
Add default arguments for labelmap screenshotting.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
default_cmap (str, optional) – Default colormap name.
default_alpha (float, optional) – Default opacity value.
cmap_parsing_group (argparse.ArgumentParser object, optional) – Group to add colormap arguments to, defaults to parser.
opacity_parsing_group (argparse.ArgumentParser object, optional) – Group to add opacity arguments to, defaults to parser.
- scilpy.io.utils.add_overlays_screenshot_args(parser, default_alpha=0.5, rendering_parsing_group=None)[source]
Add default arguments for overlays screenshotting.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
default_alpha (float, optional) – Default opacity value.
rendering_parsing_group (argparse.ArgumentParser object, optional) – Group to add rendering arguments to, defaults to parser.
- scilpy.io.utils.add_peaks_screenshot_args(parser, default_width=3.0, default_alpha=1.0, rendering_parsing_group=None)[source]
Add default arguments for peaks screenshotting.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
default_width (float, optional) – Default peak linewidth value.
default_alpha (float, optional) – Default opacity value.
rendering_parsing_group (argparse.ArgumentParser object, optional) – Group to add rendering arguments to, defaults to parser.
- scilpy.io.utils.add_sh_basis_args(parser, mandatory=False, input_output=False)[source]
Add spherical harmonics (SH) bases argument. For more information about the bases, see https://docs.dipy.org/stable/theory/sh_basis.html.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
mandatory (bool, optional) – Whether this argument is mandatory.
input_output (bool) – Whether this argument should expect both input and output bases or not. If set, the sh_basis argument will expect first the input basis, followed by the output basis.
- scilpy.io.utils.add_skip_b0_check_arg(parser, will_overwrite_with_min, b0_tol_name='--b0_threshold')[source]
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
will_overwrite_with_min (bool) – If true, the help message will explain that b0_threshold could be overwritten.
b0_tol_name (str) – Name of the argparse parameter acting as b0_threshold. Should probably be either ‘–b0_threshold’ or ‘–tolerance’.
- scilpy.io.utils.add_volume_screenshot_args(parser, input_name, mandatory=True, descriptor='3D Nifti', default_cmap=None, default_alpha=1.0, cmap_parsing_group=None, opacity_parsing_group=None)[source]
Add default arguments for volume screenshotting.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
input_name (str) – Name of the principal input volume and argument.
mandatory (bool, optional) – Whether the input argument is mandatory.
descriptor (str, optional) – Descriptor for the input volume. Will be used in help messages.
default_cmap (str, optional) – Default colormap name.
default_alpha (float, optional) – Default opacity value.
cmap_parsing_group (argparse.ArgumentParser object, optional) – Group to add colormap arguments to, defaults to parser.
opacity_parsing_group (argparse.ArgumentParser object, optional) – Group to add opacity arguments to, defaults to parser.
- scilpy.io.utils.assert_fsl_options_exist(parser, options_args, command)[source]
Assert that all options for topup or eddy exist. If not, print parser’s usage and exit.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
options_args (string) – Options for fsl command
command (string) – Command used (eddy or topup).
- scilpy.io.utils.assert_gradients_filenames_valid(parser, filename_list, input_is_fsl)[source]
Validate if gradients filenames follow BIDS or MRtrix convention
- Parameters:
parser (parser) – Parser.
filename_list (list) – list of gradient paths.
input_is_fsl (bool) – Whether the input is in FSL format or MRtrix format.
- scilpy.io.utils.assert_headers_compatible(parser, required, optional=None, reference=None)[source]
Verifies the compatibility between the first item in the required argument and the remaining ones, as well as with those in optional. If any .tck is present, a reference must be provided.
- Parameters:
parser (argument parser) – Will raise an error if a file is not compatible.
required (str or List[str]) – List of files to test, the first one is used as base for comparison.
optional (str or List[str or None], optional) – List of files. May contain None, they will be discarted.
reference (str, optional) – Reference for any .tck passed.
- scilpy.io.utils.assert_inputs_exist(parser, required, optional=None)[source]
Assert that all inputs exist. If not, print parser’s usage and exit.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
required (string or list of paths) – Required paths to be checked.
optional (string or list of paths) – Optional paths to be checked.
- scilpy.io.utils.assert_output_dirs_exist_and_empty(parser, args, required, optional=None, create_dir=True)[source]
Assert that all output directories exist. If not, print parser’s usage and exit. If exists and not empty, and -f used, delete dirs.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
args (argparse namespace) – Argument list.
required (string or list of paths to files) – Required paths to be checked.
optional (string or list of paths to files) – Optional paths to be checked.
create_dir (bool) – If true, create the directory if it does not exist.
- scilpy.io.utils.assert_outputs_exist(parser, args, required, optional=None, check_dir_exists=True)[source]
Assert that all outputs don’t exist or that if they exist, -f was used. If not, print parser’s usage and exit.
- Parameters:
parser (argparse.ArgumentParser object) – Parser.
args (argparse namespace) – Argument list.
required (string or list of paths to files) – Required paths to be checked.
optional (string or list of paths to files) – Optional paths to be checked.
check_dir_exists (bool) – Test if output directory exists.
- scilpy.io.utils.assert_roi_radii_format(parser)[source]
Verifies the format of the inputed roi radii.
- Parameters:
parser (argument parser) – Will raise an error if the –roi_radii format is wrong.
- Returns:
roi_radii – Roi radii as a scalar or an array of size (3,).
- Return type:
int or numpy array
- scilpy.io.utils.get_acq_parameters(json_path, args_list)[source]
Function to extract acquisition parameters from json file.
- Parameters:
file (json_path Path to the json)
parameters (args_list List of keys corresponding to)
- Return type:
Returns a list of values matching the list of keys.
- scilpy.io.utils.get_default_screenshotting_data(args, peaks=True)[source]
Load the data required for screenshotting from the argument parser.
- Parameters:
args (argparse.Namespace) – Argument parser namespace.
peaks (bool, optional) – Whether peaks are included in the inputs or not.
- Returns:
volume_img (nibabel.Nifti1Image) – Volume image.
transparency_img (nibabel.Nifti1Image) – Transparency image.
labelmap_img (nibabel.Nifti1Image) – Labelmap image.
ovl_imgs (List[nibabel.Nifti1Image]) – List of overlay images.
ovl_colors (np.ndarray) – Colors for the overlays.
peaks_imgs (List[nibabel.Nifti1Image]) – List of peaks images.
- scilpy.io.utils.link_bundles_and_reference(parser, args, input_tractogram_list)[source]
Associate the bundle to their reference (if they require a reference). :param parser: Parser as created by argparse. :type parser: argparse.ArgumentParser object :param args: Args as created by argparse. :type args: argparse namespace :param input_tractogram_list: List of tractogram paths. :type input_tractogram_list: list
- Returns:
list
- Return type:
List of tuples, each matching one tractogram to a reference file.
- scilpy.io.utils.parse_sh_basis_arg(args)[source]
Parser the input from args.sh_basis. If two SH bases are given, both input/output sh_basis and is_legacy are returned.
- Parameters:
args (ArgumentParser.parse_args) – ArgumentParser.parse_args from a script.
- Returns:
if args.sh_basis is a list of one string –
- sh_basisstring
Spherical harmonic basis name.
- is_legacybool
Whether the SH basis is in its legacy form.
else ((args:sh_basis is a list of two strings)) – Returns a Tuple of 4 values: (sh_basis_in, is_legacy_in, sh_basis_out, is_legacy_out)
- scilpy.io.utils.parser_color_type(arg)[source]
Validate that a color component is between RBG values, else return an error From https://stackoverflow.com/a/55410582
- scilpy.io.utils.ranged_type(value_type, min_value=None, max_value=None)[source]
Return a function handle of an argument type function for ArgumentParser checking a range: min_value <= arg <= max_value.
- Parameters:
value_type (Type) – Value-type to convert the argument.
min_value (scalar) – Minimum acceptable argument value.
max_value (scalar) – Maximum acceptable argument value.
- Returns:
Function handle of an argument type function for ArgumentParser.
Usage
—– – ranged_type(float, 0.0, 1.0)
- scilpy.io.utils.validate_nbr_processes(parser, args)[source]
Check if the passed number of processes arg is valid.
- Valid values are considered to be in the [0, CPU count] range:
Raises a parser.error if an invalid value is provided.
Returns the maximum number of cores retrieved if no value (or a value of 0) is provided.
- Parameters:
parser (argparse.ArgumentParser object) – Parser as created by argparse.
args (argparse namespace) – Args as created by argparse.
- Returns:
nbr_cpu – The number of CPU to be used.
- Return type:
int
scilpy.io.varian_fdf module
- scilpy.io.varian_fdf.add_gradient_info(procpar_path, header)[source]
Extract gradients information from the procpar file and puts it in the header. The X values of the gradient are flipped due a LAS encoding.
- Parameters:
procpar_path (Path to the procpar file.)
header (Header to add gradient info.)
- Return type:
None
- scilpy.io.varian_fdf.correct_procpar_intensity(dwi_data, dwi_path, b0_path)[source]
Applies a linear value correction based on gain difference found in procpar files. The basic formulae provided by Luc Tremblay Luc.Tremblay@usherbrooke.ca is:
Ldb = 20log(P1/P0)
- Where:
Ldb is the gain difference between B0 and dwi. P1 is the B0 image intensity factor. P0 is the dwi image intensity factor.
Since we only seek an intensity correction factor between B0 and dwi, we fix P0 at 1. The equation becomes:
Ldb = 20log(P1)
P1 is the factor we are looking for. Isolating P1 gives us the final equation:
P1 = 10**(Ldb/20)
- scilpy.io.varian_fdf.format_raw_header(header)[source]
Format the header to a Nifti1Image format.
- Parameters:
header (Raw dictionary of header information)
- Returns:
nifti1_header
- Return type:
Header to save in the nifti1 file.
- scilpy.io.varian_fdf.get_gain(procpar_path)[source]
Extract gain fromm procpar file
- Parameters:
procpar_path (Path to the procpar folder.)
- Return type:
float
- scilpy.io.varian_fdf.load_fdf(file_path)[source]
Load a Varian FDF file.
- Parameters:
file_path (Path to the fdf file or directory)
- Returns:
data (FDF raw data)
header (Dictionary of the fdf header info.)
- scilpy.io.varian_fdf.read_directory(path)[source]
- Parameters:
method (Read a directory containing multiple 2D .fdf files. The)
empty. (should return None if the directory is)
path (Path to the input directory)
- Returns:
data (Numpy array containing data)
final_header (Header information)
- scilpy.io.varian_fdf.read_file(file_path)[source]
Read a single fdf file.
- Parameters:
file_path (Path to the fdf file)
- Returns:
raw_header (Dictionary of header information)
data (Numpy array of the fdf data)
- scilpy.io.varian_fdf.save_babel(dwi_data, dwi_header, b0_data, b0_header, bval_path, bvec_path, out_path, affine=None, flip=None, swap=None)[source]
Save a loaded fdf file to nifti.
- Parameters:
dwi_data (Raw data to be saved)
dwi_header (Raw header from fdf files)
b0_data (Raw b0)
b0_header (Raw header for b0)
bval_path (Path to the bval file to be saved)
bvec_path (Path to the bvec file to be saved)
out_path (Path of the nifti file to be saved)
affine (Affine transformation to save with the data)
flip
swap
- Return type:
None
- scilpy.io.varian_fdf.write_gradient_information(dwi_header, b0_header, bval_path=None, bvec_path=None, flip=None, swap=None)[source]
Write gradient information in present in the header.
- Parameters:
dwi_header (The header with gradient info.)
b0_header (The header of b0)
bval_path (Path to the bval file to be saved.)
bvec_path (Path to the bvec path to be saved.)
flip
swap
- Return type:
None