helpers

pipeline helpers

The helpers module includes convenience utilities.

bolus_arrival

exception qipipe.helpers.bolus_arrival.BolusArrivalError

Bases: exceptions.Exception

Error calculating the bolus arrival.

qipipe.helpers.bolus_arrival.bolus_arrival_index(time_series)

Determines the DCE bolus arrival time point index. The bolus arrival is the first occurence of a difference in average signal larger than double the difference from first two points.

Parameters:time_series – the 4D NIfTI scan image file path
Returns:the bolus arrival time point index
Raises:BolusArrivalError – if the bolus arrival could not be determined

colors

qipipe.helpers.colors.colorize(lut_file, *inputs, **opts)

Transforms each input voxel value to a color lookup table reference.

The input voxel values are uniformly partitioned for the given colormap LUT. For example, if the voxel values range from 0.0 to 3.0, then the a voxel value of 0 is transformed to the first LUT color, 3.0 is transformed to the last LUT color, and the intermediate values are transformed to intermediate colors.

The voxel -> reference output file name appends _color to the input file basename and preserves the input file extensions, e.g. the input file k_trans_map.nii.gz is transformed to k_trans_map_color.nii.gz in the output directory.

Parameters:
  • lut_file – the color lookup table file location
  • inputs – the image files to transform
  • opts – the following keyword arguments:
Option dest:

the destination directory (default current working directory)
Option threshold:
 

the threshold in the range 0 to nvalues (default 0)
qipipe.helpers.colors.create_lookup_table(ncolors, colormap='jet', out_file=None)

Generates a colormap lookup table with the given number of colors.

Parameters:
  • ncolors – the number of colors to generate
  • colormap – the matplotlib colormap name
  • out_file – the output file path (default is the colormap name followed by _colors.txt in the current directory)
qipipe.helpers.colors.label_map_basename(location)
Parameters:location – the input file path
Returns:the corresponding color file name

command

Command qipipe command options.

qipipe.helpers.command.configure_log(**opts)

Configure the logger for the qi* modules.

constants

qipipe.helpers.constants.CONF_DIR = '/home/docs/checkouts/readthedocs.org/user_builds/qipipe/checkouts/stable/qipipe/conf'

The common configuration directory.

qipipe.helpers.constants.MASK_FILE = 'mask.nii.gz'

The XNAT mask file name with extension.

qipipe.helpers.constants.MASK_RESOURCE = 'mask'

The XNAT mask resource name.

qipipe.helpers.constants.SCAN_TS_BASE = 'scan_ts'

The XNAT scan time series file base name without extension.

qipipe.helpers.constants.SCAN_TS_FILE = 'scan_ts.nii.gz'

The XNAT scan time series file name with extension.

qipipe.helpers.constants.SESSION_FMT = 'Session%02d'

The XNAT session name format with argument session number.

qipipe.helpers.constants.SUBJECT_FMT = '%s%03d'

The XNAT subject name format with argument collection and subject number.

qipipe.helpers.constants.VOLUME_DIR_PAT = <_sre.SRE_Pattern object>

The volume directory name pattern. The directory name is volume``*number*, where *number* is the zero-padded, one-based volume number matched as the ``volume_number group, as determined by the qipipe.pipeline.staging.volume_format() function.

qipipe.helpers.constants.VOLUME_FILE_PAT = <_sre.SRE_Pattern object>

The volume file name pattern. The image file name is the VOLUME_DIR_PAT pattern followed by the extension .nii.gz.

distributable

qipipe.helpers.distributable.DISTRIBUTABLE = False

Flag indicating whether the workflow can be distributed over a cluster. This flag is True if qsub is in the execution path, False otherwise.

image

qipipe.helpers.image.discretize(in_file, out_file, nvalues, start=0, threshold=None, normalizer=<function normalize>)

Transforms the given input image file to an integer range with the given number of values. The range starts at the given start value. The input values are uniformly mapped into the output range. For example, if the input values range from 0.0 to 3.0 nvalues is 101, and the start is 0, then an input value of 0 is transformed to 0, 3.0 is transformed to 100, and the intermediate input values are proportionately transformed to the output range.

If a threshold is specified, then every input value which maps to an output value less than (threshold * nvalues) - start is transformed to the output start value. For example, if the input values range from 0.0 to 3.0, then:

discretize(in_file, out_file, 1001, threshold=0.5)

transforms input values as follows:

  • If the input value maps to the first half of the output range, then the output value is 0.
  • Otherwise, the input value v maps to the output value (v * 1000) / 3.
Parameters:
  • in_file – the input file path
  • out_file – the output file path
  • nvalues – the number of output entries
  • start – the starting output value (default 0)
  • threshold – the threshold in the range start to nvalues (default start)
  • normalize – an optional function to normalize the input value (default normalize())
Raises:

IndexError – if the threshold is not in the color range
qipipe.helpers.image.normalize(value, vmin, vspan)

Maps the given input value to [0, 1].

Parameters:
  • value – the input value
  • vmin – the minimum input range value
  • vspan – the value range span (maxium - minimum)
Returns:

(in_val - vmin) / vspan

logging

qipipe.helpers.logging.NIPYPE_LOG_DIR_ENV_VAR = 'NIPYPE_LOG_DIR'

The environment variable used by Nipype to set the log directory.

qipipe.helpers.logging.configure(**opts)

Configures the logger as follows:

  • If there is a log option, then the logger is a conventional qiutil.logging logger which writes to the given log file.
  • Otherwise, the logger delegates to a mock logger that writes to stdout.

Note

In a cluster environment, Nipype kills the dispatched job log config. Logging falls back to the default. For this reason, the default mock logger level is DEBUG rather than INFO. The dispatched node’s log is the stdout captured in the file work/batch/node_name.onode_id, where work the execution work directory.

Parameters:opts – the qiutil.command.configure_log options
Returns:the logger factory
qipipe.helpers.logging.logger(name)

This method overrides qiutil.logging.logger to work around the following Nipype bug:

  • Nipype stomps on any other application’s logging. The work-around is to mock a “logger” that writes to stdout.
Parameters:name – the caller’s context __name__
Returns:the logger facade

metadata

qipipe.helpers.metadata.EXCLUDED_OPTS = set(['plugin_args', 'run_without_submitting'])

The config options to exclude in the profile.

exception qipipe.helpers.metadata.MetadataError

Bases: exceptions.Exception

Metadata parsing error.

qipipe.helpers.metadata.create_profile(configuration, sections, dest, **opts)

Creates a metadata profile from the given configuration. The configuration input is a {section: {option: value}} dictionary. The target profile is a Python configuration file which includes the given sections. The section content is determined by the input configuration and the keyword arguments. The keyword item overrides a matching input configuration item. The resulting profile is written to a new file.

Parameters:
  • configuration – the configuration dictionary
  • sections – the target profile sections
  • dest – the target profile file location
  • opts – additional {section: {option: value}} items
Returns:

the target file location

roi

ROI utility functions.

class qipipe.helpers.roi.Extent(points, scale=None)

Bases: object

The line segments which span the largest volume or area between a set of points.

Parameters:
  • points – the points array
  • scale (tuple) – the anatomical dimension scaling factors (default unit scale)
__init__(points, scale=None)
Parameters:
  • points – the points array
  • scale (tuple) – the anatomical dimension scaling factors (default unit scale)
boundary = None

The convex hull boundary in image space.

bounding_box()

Returns the (least, most) points of a rectangle circumscribing the extent.

Returns:the (least, most) rectangle points
Return type:tuple
scale = None

The anatomical dimension scaling factors (default unit scale).

segments = None

The orthogonal extent segments.

show()

Displays the ROI boundary points and extent segments.

class qipipe.helpers.roi.ExtentSegmentFactory(points)

Bases: object

A utility factory class that computes the extent line segments from a set of convex hull vertex points.

Parameters:points – the convex hull vertex points
__init__(points)
Parameters:points – the convex hull vertex points
create()

Returns the orthogonal segments end point indexes as the tuple (longest, widest, deepest), where each of the tuple elements is a (from, to) segment end point pair of indexes into the points, e.g.:

>>> points.shape
(128, 3)
>>> factory = ExtentSegmentFactory(points)
>>> segment_indexes = factory.create()
>>> segment_indexes
((34, 12), (122, 14), (48, 111))
>>> segments = points[segments]
>>> np.all(np.equal(segments[0][0], points[34]))
True
>>> np.all(np.equal(segments[0][1], points[12]))
True

The bounding segments procedure is as follows:

  • Find the length segment (r1, r2) which maximizes the Cartesian distance between points.
  • Find the point r3 furthest from r1 and r2.
  • Compute the point o orthogonal to r3 on the segment (r1, r2).
  • The width segment is then (r3, r4), where the point r4 minimizes the angle between the segments (r3, p) and (r3, o) for all points p.
  • Iterate on a generalization of the above algorithm to find the depth segment (r5, r6), where:
    • r5 maximizes the distance to the plane formed by the
      length segment (r1, r2) and the width segment (r3, r4).
    • r6 is the point which is most orthogonal to the length
      and width segments.
Returns:the orthogonal segment end point index tuples
Return type:list
distances = None

The N x N point distance array, where N is the number of points and self.distances[i][j] is the distance from self.points[i] to self.points[j].

points = None

The ndarray of boundary points.

class qipipe.helpers.roi.ROI(points, scale=None)

Bases: object

Summary information for a 3D ROI mask.

Parameters:
  • points – the ROI mask points
  • scale (tuple) – the (x, y, z) scaling factors
__init__(points, scale=None)
Parameters:
  • points – the ROI mask points
  • scale (tuple) – the (x, y, z) scaling factors
extent = None

The 3D Extent.

maximal_slice_index()
Returns:the zero-based slice index with maximal planar extent
slices = None

The {z: Extent} dictionary for the 2D (x, y) points grouped by z value.

qipipe.helpers.roi.load(location, scale=None)

Loads a ROI mask file.

Parameters:
  • location – the ROI mask file location
  • scale (tuple) – the (x, y, z) scaling factors
Returns:

the ROI encapsulation
Return type:

ROI
qipipe.helpers.roi.reorder_bolero_mask(in_file, out_file=None)

Since the OHSU Bolero ROI is drawn over DICOM slice displays, the converted NIfTI file x and y must be transposed and flipped to match the time series. The mask data shape is assumed to be [x, y, slice].

Parameters:
  • in_file – the input Bolero mask file path
  • out_file – the optional output file path
Returns:

the reordered mask ndarray data