Geometric Processing

The following modules group operations on geometric structures returned by the readAndFilter module. These operations are not intended to improve visualization, but to produce data for the user which can be used in statistical analyses or in other applications.

Structure metrics

Polydata metrics

get_mult_struct_metric(reader, struct_names, code, metric='volume')[source]

Aggregates a metric across multiple structures

The supported metrics are:

  • volume: Total volume of the structures, read from freesurfer files
  • area: Sum of the surface areas of each structure
  • nfibers: Number of fibers that cross the structure, or number of fibers in the bundle if structure is Fibs:*
  • lfibers: Mean length of fibers going through structure or in bundle
  • fa_fibers: Mean fa of fibers crossing the structure or in bundle
  • fa_inside: Mean fa inside the structures
  • md_inside: Mean md inside the structures

if metric is nfiber,lfibers or fa_fibers get_fibers_metric() is used

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • struct_names (list) – List of structure names
  • code – Subject id
  • metric (str) – Metric to calculate, options are volume, area (surface area), nfibers, lfibers md_inside and fa_inside
Returns:

A float number with the requested metric
get_struct_metric(reader, struct_name, code, metric='volume')[source]

Calculates a metric for a specific structure

The supported metrics are:

  • volume: Volume of the structure, read from freesurfer files
  • area: Surfrace area of the structure
  • nfibers: Number of fibers that cross the structure, or number of fibers in the bundle if structure is Fibs:*
  • lfibers: Mean length of fibers going through structure or in bundle
  • fa_fibers: Mean fa of fibers crossing the structure or in bundle
  • fa_inside: Mean fa inside the structure
  • md_inside: Mean md inside the structure
Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • struct_name (str) – Name of an structure or of a named bundle (should start with Fibs:)
  • cod – Subject id
  • metric (str) – Look above for the options
Returns:

A float number with the requested metric
get_fibers_metric(reader, struct_name, code, metric='number')[source]

Calculates metrics for groups of fibers

struct_name can be the name of a freesurfer model, in which case the bundle will be the fibers that cross it, if struct_name is a list of structures, the fibers crossing any of those structures will be used finally struct_name can be a named fiber, which will be used as a bundle

metrics are number, mean_length and mean_fa, see get_struct_metric()

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • struct_name (str) – Name of an structure or of a named bundle (should start with Fibs:)
  • cod – Subject id
  • metric (str) – Options are number, mean_length, and mean_fa
Returns:

A float number with the requested metric
cached_get_struct_metric_col(reader, codes, struct_name, metric, state_variables=None, force_reload=False, laterality_dict=None)[source]

calculates a structure metrics for all subjects in a list of codes

It has a disk cache which is used to try to save results, and reload them instead of calculating again if force_reload is True, a cached result will be ignored, and the column will be calculated again

A laterality_dict may be used for solving dominant and non dominant structures specifications

It has a dictionary of state_variables which can be used to monitor or cancel the calculation from a different thread The states variables are:

  • ‘struct_name’: the requested structure name
  • ‘metric’ ; the requested metric
  • ‘working’ : Set to true at start of function, and to false just before returning
  • ‘output’ : A partial list of results will be stored here, this is the same object that will be returned
  • ‘number_calculated’ : number of metrics calculated
  • ‘number_requested’ : number of metrics requested (length of codes list)
  • ‘cancel’ : Set this to True, to cancel the operation and return before the next iteration
Parameters:
Returns:

A list of floats of the same length as codes with the respective metrics for each subject
get_scalar_from_fiber_ploydata(poly_data, scalar)[source]

Calculates the number of lines, mean length or mean color from a polydata bundle

Parameters:
  • poly_data (vtkPolyData) – Poly Data containing only lines
  • scalar (str) – may be “number”,”mean_length”, or “mean_color”
Returns:

The requested scalar
get_fiber_scalars_from_db(reader, subj_id, db_id, scalar)[source]

Calculates the number of lines, mean length mean fa or mean md from a database fiber

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • subj_id – Subject id
  • db_id – Bundle database id
  • scalar (str) – may be “number”,”mean_length”, or “mean_fa” or “mean_md”
Returns:

The requested scalar, or ‘nan’ if there was an error
get_fiber_scalars_from_waypoints(reader, subj_id, waypoints, operation, scalar)[source]

Calculates the number of lines, mean length mean fa or mean md from a fiber created using waypoints

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • subj_id – Subject id
  • waypoints (list) – List of structure names
  • operation (str) – “and” if it required for lines to pass through all waypoints, “or” if they can pass through any of them
  • scalar (str) – may be “number”,”mean_length”, or “mean_fa” or “mean_md”
Returns:

The requested scalar, or ‘nan’ if there was an error

Image metrics

mean_inside(reader, subject, structures, img2, paradigm=None, contrast=1)[source]

Calculate the mean value of img2 values inside of the structures listed

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • subject – Subject id
  • structures (list) – List of structure names
  • img2 (str) – Modality in which to calculate mean, must be FA, MD, MRI or fMRI
  • paradigm (str) – In case img2 is fMRI, the paradigm to use
  • contrast (int) – In case img2 is fMRI, the contrast to use
Returns:

The mean value of the image voxels that lay inside any of the listed structures
aggregate_in_roi(reader, subject, roi_ctr, roi_radius, roi_space, img2, paradigm=None, contrast=None, mean=True)[source]

Aggregate values from an image inside a spherical roi

Parameters:
  • reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
  • subject – subject id
  • roi_ctr (tuple) – Coordinates of the roi center
  • roi_radius (float) – Sphere radius
  • roi_space (str) – Coordinate system in which the roi is defined
  • img2 (str) – Modality in which to calculate mean or mode.
  • paradigm (str) – In case img2 is fMRI, the paradigm to use
  • contrast (int) – In case img2 is fMRI, the contrast to use
  • mean (bool) – If will return the mean inside the roi, otherwise it will return the mode.
Returns:

Mean or mode of the image inside a sphere
class AggregateInRoi(reader)[source]

A class for doing repeated aggregations of image values inside different rois

Parameters:reader (braviz.readAndFilter.base_reader.BaseReader) – Reader object used to read the data
get_value(roi_ctr, roi_radius)[source]

Get mean or mode from the image inside an spherical roi

Parameters:
  • roi_ctr (tuple) – Coordinates of the roi center
  • roi_radius (float) – Sphere radius
Returns:

The mean or mode of the image inside the sphere, according to the data set using load_image()
load_image(subject, space, img_class, img_name, contrast=1, mean=True)[source]

Loads an image into the class

Parameters:
  • subject – subject id
  • space (str) – Coordinate system in which the roi is defined
  • img_class (str) – Image class in which to calculate mean or mode.
  • img_name (str) – Image name in the given img_class
  • contrast (int) – In case img_class is fMRI, the contrast to use
  • mean (bool) – If True get_value() will return the mean inside the roi, otherwise it will return the mode.

latearlity helpers

get_right_or_left_hemisphere(hemisphere, laterality)[source]

Translates ‘d’ (dominant) and ‘n’ (non-dominant) into ‘r’ (right) or ‘l’ (left) using laterality,

laterality should be r (right handed) or l (left handed) hemisphere can also be ‘r’ or ‘l’; in this case the same letters will be returned

Parameters:
  • hemisphere (str) – Should be ‘d’ for dominant, ‘n’ for non-dominant, ‘r’ for right or ‘l’ for left
  • laterality (str) – Should be ‘l’ for left handed subjects or ‘r’ otherwise
Returns:

‘r’ or ‘l’
solve_laterality(laterality, names)[source]

translates dominant and nondominant freesurfer names into right and left names,

laterality should be ‘l’ (left handed) or ‘r’ names is a list of names to translate currently wm-[d|n|r|l]h-* , ctx-[d|n|r|l]h-* and fiber bundles ending in _[d|n|r|l] are supported

Parameters:
  • laterality (str) – Laterality of subject, ‘l’ for left handed, ‘r’ otherwise
  • names (list) – List of structure names, possibly with ‘d’ and ‘n’ sides, to translate to ‘l’ and ‘r’ sides. Only cortical structures and named fibers are supported, read above.

Geometric descriptors

get_descriptors(aseg, labels, draw=False)[source]

Calculate the longest axis in a structure, the second longest axis perpendicular to it, and the third axis perpendicular to both

Parameters:
Returns:

A tuple with the lengths of the three axes

Roi operations

generate_roi_image(subject, roi_id, space, reader=None, out_format='nii')[source]

Generates an image representation of an spherical ROI

Parameters:
Returns:

A numpy array and a numpy affine transform by default. If out_format="vtk" a vtkImageData
export_roi(subject, roi_id, space, out_file, reader=None)[source]

Save an image from a roi into a file

Parameters: