catheter_utils package

catheter_utils package#

Submodules#

catheter_utils.cathcoords module#

Manipulate cathcoords files.

class catheter_utils.cathcoords.Cathcoords(coords, snr, times, trigs, resps)#

Bases: tuple

Object representing all the data that goes into a cathcoords file.

coords#: Alias for field number 0

resps#: Alias for field number 4

snr#: Alias for field number 1

times#: Alias for field number 2

trigs#: Alias for field number 3

catheter_utils.cathcoords.discover_files(dirname)#: Search the given directory for cathcoords files.

catheter_utils.cathcoords.get_centroid_mean(coords)#: Return the centroid of the given coordinate array. Uses the mean.

catheter_utils.cathcoords.get_centroid_median(coords)#: Return the centroid of the given coordinate array. Uses the median.

catheter_utils.cathcoords.get_distances_from_centroid(coords, use_mean=True)#: Return a list of distances from the centroid, and centroid, using the mean centroid by default. Set use_mean to False to use median centroid.

catheter_utils.cathcoords.get_tip_variance(distal_file, proximal_file, geometry=None, dof=1)#

returns the variance of the tip coordinates

From distal and proximal coordinate files: computes the tip locations and the centroid of the tip locations

Returns the variance of the euclidean distances between tip locations and their centroid. This gives an estimate for the spread of the tip points.

distal_file: text file of distal coordinates: proximal_file: text file of proximal coordinates geometry: the geometry of the coils, estimated if not passed in

dof: degrees of freedom for variance calculation, 1 by default

catheter_utils.cathcoords.make_filename(index, coil)#: Format a cathcoords filename.

catheter_utils.cathcoords.read_file(filename)#: Extract data from a cathcoords file.

catheter_utils.cathcoords.read_pair(dist_filename, prox_filename)#

Extract data from a pair of cathcoords files and do simple checks for consistency.

Different coil files may have a different number of rows for the same recording. This will match rows using timestamps so that coords, snr, etc are paired up correctly.

catheter_utils.cathcoords.write_file(filename, obj)#: Write catheter coil data to the specified file.

catheter_utils.geometry module#

This module contains things related to the geometry of our MR compatible catheters. Calculations involving specific information about their measurements can be put in here. E.g., extrapolating the tip from observations of the tracking coil locations.

catheter_utils.geometry.GEOMETRY = ((9.41, 17.97), (9.07, 16.84))#: Measurements of each of our models of catheter in the order that we received them.

class catheter_utils.geometry.Geometry(tip_to_distal, tip_to_proximal)#

Bases: _GeometryBase

The measurements that describe the geometry of a catheter.

class FitFromCoilsResult(tip, distal, proximal)#

Bases: tuple

The various methods of fitting catheter coordinate locations from coil observations all return the same kind of data.

distal#: Alias for field number 1

proximal#: Alias for field number 2

tip#: Alias for field number 0

property distal_to_midpoint#

property distal_to_proximal#

fit_from_coils_distal_offset(distal, proximal)#: Extrapolate the tip location from the distal and proximal coil locations by adding an offset to the distal coil location. This is the method used historically by our realtime pipeline.

fit_from_coils_mse(distal, proximal)#: Extrapolate the tip location from the distal and proximal coil locations by finding the minimum error coil locations and then extrapolating the tip.

property tip_to_midpoint#

catheter_utils.geometry.estimate_geometry(distal, proximal)#: Given a set of catheter coordinates, find the catheter specifications that best fit the data.

catheter_utils.localization module#

Catheter localization algorithms. Take projection data and produce coordinate estimates.

class catheter_utils.localization.HadamardCoordinates#

Bases: object

Convert between Hadamard projection coordinates (“fh”) and world coordinates.

classmethod projection_to_world(x)#: Transform from projection coordinates to world coordinates.

classmethod world_to_projection(u)#: Transform from world coordinates to projection coordinates.

classmethod world_to_projection_mat()#

class catheter_utils.localization.JointIterativeWeightedCentroid(geometry=None, centroid_weighting=None, err_weighting=None, tol=1e-06, max_itr=10)#

Bases: object

Responsible for localizing a catheter using the iterative centroid method with errors weighted according to a function of the projections.

localize(distal_data, proximal_data)#

class catheter_utils.localization.ProjectionWeightedCatheterFit(world_to_projection, intercoil_distance, projection_weights_a, a, projection_weights_b, b)#

Bases: object

This object is responsible for fitting the distal and proximal coils to a sample of observed coordinates while weighting errors according to the given weights.

classmethod fit(p, c, wa, a, wb, b)#: Set up the root finding problem and find the root.

fun(x)#: The lagrangian function for the weighted minimum norm problem (mse estimate) with the inter-coil distance constraint.

property init#: The initial guess for the location of the root. Use the unconstrained estimate.

solve()#: Find a root of the lagrangian.

class catheter_utils.localization.XYZCoordinates#

Bases: object

Convert between XYZ projection (“sri”) projection and world coordinates.

static projection_to_world(x)#: Transform from projection coordinates to world coordinates.

static world_to_projection(u)#: Transform from world coordinates to projection coordinates.

static world_to_projection_mat()#

catheter_utils.localization.centroid(fs, xs)#: Localize the catheter in the projection direction by finding the centroid of the signal.

catheter_utils.localization.centroid_around_peak(fs, xs, window_radius=3.5)#: Localize the catheter in the projection direction by finding the centroid of the signal in a window centered around the peak.

catheter_utils.localization.iterative_weighted_centroid(fs, xs, weighting, tol=1e-06, max_iter=32)#: Localize the catheter in the projection direction by iteratively finding the centroid using a weighting function centered at the previous location.

catheter_utils.localization.joint_iterative_weighted_centroid(distal_data, proximal_data, geometry, weighting, tol=1e-06, max_iter=256)#

catheter_utils.localization.jpng(distal_data, proximal_data, geometry, width=3, sigma=0.5, tol=1e-06, max_iter=256)#

catheter_utils.localization.localize_catheter(distal_data, proximal_data, localizer, localizer_args=None, localizer_kwargs=None)#

A helper for combining single projection localizations into an estimate for two coil locations.

Returns the distal coordinates, proximal coordinates, and the highest number of iterations required (zero for non-iterative algorithms)

catheter_utils.localization.localize_coil(data, localizer, localizer_args=None, localizer_kwargs=None)#

A helper for combining single projection localizations into an estimate of a coil position.

Returns the 3d coordinates and number of iterations required for each projection. For non-iterative algorithms, the number of iterations will be 0.

catheter_utils.localization.peak(fs, xs)#: Localize the catheter in the projection direction by finding the max signal.

catheter_utils.localization.png(fs, xs, width=3, sigma=0.5, tol=1e-06, max_iter=32)#: ‘Peak Normed Gaussian’ localizes the catheter in the projection direction by iteratively computing the ‘png’ weighted centroid.

catheter_utils.localization.png_density(xs, width=3, sigma=0.5)#: ‘Peak Normed Gaussian’ is a function used for iterative catheter localization. It is 1 in the range [-width, width] before decaying as a gaussian.

catheter_utils.metrics module#

This module contains functions related to evaluating/comparing results.

catheter_utils.metrics.Bias(distal_file, proximal_file, gt_coords, Geometry)#

produces the bias between the ground truth and measurements.

distal_file: text file of distal coordinates proximal_file: text file of proximal coordinates gt_coords: ground truth tip coordinates Geometry: the geometry of the coils

catheter_utils.metrics.Chebyshev(distal_file, proximal_file, gt_coords, Geometry)#

produces the 95% chebyshev radius.

distal_file: text file of distal coordinates proximal_file: text file of proximal coordinates gt_coords: ground truth tip coordinates Geometry: the geometry of the coils

catheter_utils.metrics.barplot(dest, expname, x_axis)#: plot bar graph of Bias and Chebyshev tracking error. x-axis: algorithm (Default), y-axis: Bias + Chebyshev. Rest of data columns are filters

catheter_utils.metrics.get_coords(data_file)#

takes a path to a txt file and extracts coordinate data.

data_file is the path to a .txt file that contains the x,y,z coordinates

catheter_utils.metrics.trackerr(seq_path, src_path, groundtruth, algorithm, dest_path, distal_index, proximal_index, dither_index, expname)#: retrieve .txt files from localization algorithm folders, FOV from projection files, and groundtruth coordinates then calculate Bias and Chebyshev tracking error. Data exported as csv with expname (default is experiment name in GroundTruthCoords.csv)

catheter_utils.projections module#

This module contains things related to reading and manipulating projections.

class catheter_utils.projections.FindData(toc, recording, distal, proximal, dither)#

Bases: object

Extract coil projection data and synchronized rows of distal & proximal pairs

combine_snr()#

Compute dict of snrs for this projection: the keys are the coils, and each value is an arrays of snrs, one for each set of axes over the recording, ordered by time

This should not need to be called from outside the class: it is called internally when the projections are read and when the snr_combo_method is changed

SNRS are combined over axes: 3 axes (X, Y, and Z) for the basic “SRI” 3-projection sequence and 4 axes (4 diagonals of a cube) for the “FH” hadmard-multiplexed sequence The snr_combo_method defines how the SNRs are combined.

These snr combined values are stored in the snr property. They are computed when this method is called and saved until the snr_combo_method is changed

get_distal_data(i)#

get_proximal_data(i)#

get_timestamp(axis, readout)#

property resp#

property snr#: Return a dict of SNRs by coil - Each value is an arrays of snrs, one for each set of axes over the recording, ordered by time - Each SNR is a combination of the SNRs of each axis projection - see combine_snr & snr_combo_method for details

property snr_combo_method#

The SNR combination method defines how SNRs are combined across axes

Should be one of: ‘min’, ‘median’, ‘mean’
The default value on construction is ‘min’

WARNING: on setting, it may take some time to compute the combined SNRs

property snrs_per_readout#

Return SNRs from each readout Returns a dict whose keys are the coil & axis (both ints) and each value is an array of SNRs for this recording, ordered by time

Unlike the snr property, snrs_per_readout does not combine the SNR over axes

property timestamp#

property trig#

exception catheter_utils.projections.ProjectionFileCorrupted#

Bases: ValueError

Raised to indicate that the file is ‘corrupt’.

exception catheter_utils.projections.ProjectionFileVersionCheck#

Bases: ValueError

Raised to indicate that the file failed its version check.

class catheter_utils.projections.ReadRawResult(meta, raw, legacy_version, corrupt)#

Bases: tuple

corrupt#: Alias for field number 3

legacy_version#: Alias for field number 2

meta#: Alias for field number 0

raw#: Alias for field number 1

catheter_utils.projections.discover_raw(path, validate=False)#

Check for possible projections files in the given directory, and summarize their contents.

Returns (discoveries, unknown) where: discoveries is a pandas.DataFrame where rows describe individual

projections and columns are given by:
scheme: str # how projections are related, recording: int # the recording number, coil: int # the coil that the projection was acquired on, axis: int # the axis of the projection, dither: int # the dither index (0 for sri), filename: str # the file that the projection is in, index: int # the index of the projection in the file

If validate is set to True then there will be additional columns:
corrupt: bool # is the file corrupt expected: bool # projections in the file agree with expectation version: int # the inferred file version

unknown is a list of “.projections” filenames that do not follow our: file naming conventions. What do they contain? Ask somebody else.

catheter_utils.projections.fov_info(meta, raw)#: extract FOV info from pandas.Dataframe (meta), and raw numpy data (raw). Output from read_raw function

catheter_utils.projections.guess_contents_raw(filename)#

Guess the projection content of a raw projections file with the given filename. The guess is based on convention.

Returns a list of dicts providing info about what each projection is.

catheter_utils.projections.read_raw(filename, legacy_version=None, allow_corrupt=False)#

Read the raw projection data from the requested file.

If legacy_version is None then this will try to infer the correct version. Otherwise it will read the file using the requested version number.

If allow_corrupt is True then this won’t raise an exception when encountering an apparently corrupt file, and will instead log a warning and return as much data as could be read.

Returns ReadRawResult(meta, raw, version, corrupt) where:: ‘meta’ is a pandas.DataFrame containing information about each sample; ‘raw’ is a list of 2D complex valued numpy arrays with readouts in rows; ‘version’ is the inferred or requested legacy_version; and ‘corrupt’ indicates an apparently corrupt file.

catheter_utils.projections.reconstruct(raw)#: Reconstruct the raw signals into ‘projections’. These are 1D magnitude images.

catheter_utils.projections.reconstruct_complex(raw)#: Reconstruct the raw signals into ‘complex projections’. These are the (inverse) FT of the raw signals.

catheter_utils.projections.snr(fs)#: Estimate the given signal’s SNR.

catheter_utils.projections.variance(fs, xs)#

Estimate the given signal’s variance.

Treat fs as though it is proportional to a probability density, and calculate its variance.

Module contents#

Home to catheter utils.

catheter_utils package

Contents

catheter_utils package#

Submodules#

catheter_utils.cathcoords module#

catheter_utils.geometry module#

catheter_utils.localization module#

catheter_utils.metrics module#

catheter_utils.projections module#

Module contents#