mibidata package¶

Submodules¶

mibidata.color module¶

Color transformation and composites.

mibidata.color.rgb2hsl(rgb)¶

Converts an RGB array to HSL.

The hue is scaled to [0, 2*pi]; the saturation and lightness to [0, 1].

Parameters:: rgb – An NxMx3 array of floats in the unit interval.
Returns:: An array the same shape as rgb converted to HSL coordinates.
Raises:: ValueError – Raised if the input array has values outside of the unit interval.

References

HSL_and_HSV. Wikipedia: The Free Encyclopedia. Accessed 09/11/2016.: http://en.wikipedia.org/wiki/HSL_and_HSV.

mibidata.color.hsl2rgb(hsl)¶

Converts an HSL array to RGB.

Parameters:: hsl – An NxMx3 array of floats representing an HSL image. The H layer must have values in the range [0, 2*pi]; the S and L layers must have values in the unit interval.
Returns:: An array the same shape as hsl converted to RGB coordinates.
Raises:: ValueError – Raised if the input array has values outside of the expected intervals.

References

HSL_and_HSV. Wikipedia: The Free Encyclopedia. Accessed 09/11/2016.: http://en.wikipedia.org/wiki/HSL_and_HSV.

mibidata.color.rgb2cym(rgb)¶

Converts an RGB array to CYM.

Parameters:: rgb – An NxMx3 array of floats in the unit interval.
Returns:: An array the same shape as rgb converted to CYM colors.

mibidata.color.invert_luminosity(rgb)¶

Inverts the luminosity of an RGB image.

Parameters:: rgb – An NxMx3 array of floats in the unit interval.
Returns:: An array the same shape as rgb that has had its luminosity inverted.

mibidata.color.composite(image, color_map, gamma=0.3333333333333333, min_scaling=10)¶

Combines multiple image channels by color into a 3-D array.

Parameters:

image – A MibiImage.
color_map – A dictionary keyed by color with values of channel names corresponding to a subset of those in the MibiImage. The allowed colors are ‘Cyan’, ‘Yellow’, ‘Magenta’, ‘Green’, ‘Orange’, ‘Violet’, ‘Red’, ‘Blue’ and ‘Gray’.
gamma – The value with which to scale the image data. Defaults to 1/3. If no gamma correction is desired, set to 1.
min_scaling – The minimum number of counts used as the divisor for each channel before applying gamma. This intended to prevent images with only a few counts from being scaled incorrectly to [0, 1].

Returns:

An NxMx3 uint8 array of an RGB image.

mibidata.color.compose_overlay(image, overlay_settings)¶

Overlays multiple image channels using overlay_settings from MIBItracker.

The overlay_settings are intended to have the form of a channels.json file as downloaded from MIBItracker but they can have any of the of the following forms:

{'image_id': {'channels': {'channel_1': {'color': color, ...}, ...}},
{'channels': {'channel_1': {'color': color, ...}, ...},
{'channel_1': {'color': color, ...}, ...}.

Each channel is expected to have the following fields:

‘color’ (required):
One of the following: ‘Cyan’, ‘Yellow’, ‘Magenta’, ‘Green’, ‘Orange’, ‘Violet’, ‘Red’, ‘Blue’, or ‘Gray’.
‘brightness’ (optional):
float between -1 and 1; defaults to 0.
‘intensity_higher’ (optional):
Upper limit of the channel intensity; defaults to maximum counts in the channel.
‘intensity_lower’ (optional):
Lower limit of the channel intensity; defaults to 0.
‘blur’ (optional):
integer between 0 and 10. Defines the gaussian blur of the channel according to pre-defined convolution kernels.

Parameters:

image – A MibiImage.
overlay_settings – Dictionary of MIBItracker visual settings.

Returns:

An NxMx3 uint8 array of an RGB image.

mibidata.combine_tiffs module¶

Combines a folder of single-channel TIFFs into a multiplexed MIBItiff.

mibidata.combine_tiffs.merge_mibitiffs(input_folder, out=None)¶

Merges a folder of single-channel MIBItiff files into a single MIBItiff.

Parameters:

input_folder – Path to a folder containing MIBItiff files. While these files may be single-channel, they are assumed to have accurate and consistent MIBI metadata.
out – Optionally, a path to a location for saving the combined TIFF. If not specified, defaults to ‘combined.tiff’ inside the input folder.

mibidata.combine_tiffs.create_mibitiffs(input_folder, run_path, point, panel_path, slide, size, run_label=None, instrument=None, tissue=None, aperture=None, out=None)¶

Combines single-channel TIFFs into a MIBItiff.

The input TIFFs are not assumed to have any MIBI metadata. If they do, it is suggested to use the simpler merge_mibitiffs() instead.

Parameters:

input_folder – Path to a folder containing single-channel TIFFs.
run_path – Path to a run xml.
point – Point name of the image, e.g. Point1 or Point2. This should match the name of folder generated for the raw data as it is listed in the run xml file.
panel_path – Path to a panel CSV.
slide – The slide ID.
size – The size of the FOV in microns, i.e. 500.
run_label – Optional custom run label for the combined TIFF. If uploading the output to MIBItracker, the run label set here must match the label of the MIBItracker run. Defaults to the name of the run xml.
instrument – Optionally, the instrument ID.
tissue – Optionally, the name of tissue.
aperture – Optionally, the name of the aperture or imaging preset.
out – Optionally, a path to a location for saving the combined TIFF. If not specified, defaults to ‘combined.tiff’ inside the input folder.
run_label – Optionally, a custom run label for the run property of the image.

mibidata.constants module¶

Constants used in mibidata module.

mibidata.mibi_image module¶

Base module for working with MIBI images.

class mibidata.mibi_image.MibiImage(data, channels, **kwargs)¶

Bases: object

A multiplexed image with labeled channels and metadata.

Parameters:

data – An MxMxD numpy array of multiplexed image data, where D is the channel index and the frame size of the image is MxM.
channels – A tuple of channel names of length D. The names may either be strings, or tuples of strings of the format (mass, target).
kwargs –
A mapping of arguments that used to define the image metadata. A list of required keys follows; however, the user can define other metadata key-value pairs that will be added as attributes to the class instance in use.
- run: A string name of the run during which this image was
  acquired.
- date: The run date. It can either be a datetime object,
  or a string. If a string, it will be parsed according to the datetime_format.
- coordinates: A tuple of (x, y) stage coordinates at which the
  image was acquired; stage coordinates should be in microns.
- size: A float size of the image width/height in \(\mu m\).
- slide: A string or integer slide ID.
- fov_id: A string identifying the FOV within the run,
  i.e. ‘FOV1’ in MIBIcontrol or ‘Point1’ in earlier versions.
- fov_name: A user-defined string name for the FOV as assigned
  before the run. In prior versions this was called ‘point_name’.
- folder: The folder name for this image as determined by the
  acquisition software. For data generated from MIBIcontrol software, this will the same as the fov_id.
- dwell: A float pixel dwell time in \(ms\).
- scans: A comma-separated list of image scan numbers.
- aperture: Aperture code (e.g. ‘A’ or ‘B’) matching aperture width
  used during image acquisition.
- instrument: A string identifier for the instrument used.
- tissue: A string name of the tissue type.
- panel: A string name of the panel used to stain the tissue.
- version: A string identifier for the software version used.
- datetime_format: The optional format of the date, if given as a
  string. Defaults to '%Y-%m-%dT%H:%M:%S'.
- mass_offset: Mass offset parameter used for mass calibration.
- mass_gain: Mass gain used for mass calibration.
- time_resolution: Parameter used for mass calibration.
- miscalibrated: Whether or not there was significant difference
  between peak locations after mass recalibration.
- check_reg: Whether or not the maximum shift between depths is
  higher than a threshold.
- filename: The name of the instrument file containing the run
  metadata.
- description: String describing any additional information about
  the image.

Raises:

ValueError – Raised if * the shape of data does not match length of channels. * the channel names are not unique. * the masses (if included in channel tuples) are not unique. * the targets (if included in channel tuples) are not unique. * the fov_id doesn’t match the point in folder, unless the call is using the old point name format, in which case, only a warning is shown.

data¶: An MxMxD numpy array of multiplexed image data, where D is the channel index and the frame size of the image is MxM.

channels¶: A tuple of channel names of length D. The names may either be strings, or tuples of strings of the format (mass, target).

kwargs¶

A mapping of arguments that used to define the image metadata. A list of required keys follows; however, the user can define other metadata key-value pairs that will be added as attributes to the class instance in use.

run: A string name of the run during which this image was
acquired.
date: The run date. It can either be a datetime object,
or a string. If a string, it will be parsed according to the datetime_format.
coordinates: A tuple of (x, y) stage coordinates at which the
image was acquired; stage coordinates should be in microns.
size: A float size of the image width/height in \(\mu m\).
slide: A string or integer slide ID.
fov_id: A string identifying the FOV within the run,
i.e. ‘FOV1’ in MIBIcontrol or ‘Point1’ in earlier versions.
fov_name: A user-defined string name for the FOV as assigned
before the run. In prior versions this was called ‘point_name’.
folder: The folder name for this image as determined by the
acquisition software. For data generated from MIBIcontrol software, this will the same as the fov_id.
dwell: A float pixel dwell time in \(ms\).
scans: A comma-separated list of image scan numbers.
aperture: Aperture code (e.g. ‘A’ or ‘B’) matching aperture width
used during image acquisition.
instrument: A string identifier for the instrument used.
tissue: A string name of the tissue type.
panel: A string name of the panel used to stain the tissue.
version: A string identifier for the software version used.
datetime_format: The optional format of the date, if given as a
string. Defaults to '%Y-%m-%dT%H:%M:%S'.
mass_offset: Mass offset parameter used for mass calibration.
mass_gain: Mass gain used for mass calibration.
time_resolution: Parameter used for mass calibration.
miscalibrated: Whether or not there was significant difference
between peak locations after mass recalibration.
check_reg: Whether or not the maximum shift between depths is
higher than a threshold.
filename: The name of the instrument file containing the run
metadata.
description: String describing any additional information about
the image.

add_attr(**kwargs)¶

Adds user-defined metadata key-value pairs as attributes to: the class instance in use. If attribute already exists for the current instance, raises an error.

Parameters:

kwargs – A mapping of arguments for a user to add multiple attributes with their respecitve values.

Raises:

ValueError – Raised if attempts to set an attribute that is already
defined for this instance. –

remove_attr(attributes)¶

Removes user-defined attributes from the class instance in use.

Parameters:: attributes – A single string or a list of user-defined attributes for deletion.
Raises:: ValueError – Raised if * attempts to remove a required attribute. * an attribute is not defined for this instance.

property pixel_size¶: Returns the diameter of a pixel in microns.

property point_name¶: Returns fov_name instead of deprecated point_name.

property folder¶

property fov_id¶

set_fov_id(fov_id, folder=None)¶

Sets the fov_id and optionally updates the folder to match.

Parameters:

fov_id – The fov id within the run such as FOV1, or if from a beta system Point1.
folder – For compatibility with beta systems, the folder containing the fov data, such as Point1/RowNumber0/Depth_Profile0. If omitted, this will default to match the fov id.

property aperture¶

property channels¶

A tuple of channel names.

The names may either be strings, or tuples of strings of the format (mass, target).

__eq__(other)¶

Checks for equality between MibiImage instances.

Parameters:: other – A MibiImage.

Returns: True if both the values of the data array and the metadata of: the other MibiImage are equal to this instance’s; otherwise False.

__getitem__(channels)¶: Equivalent to slice_data().

static parse_aperture(value)¶

Parameters:

value – A string representing an aperture code.

Returns:

An aperture code (e.g. ‘A’ or ‘B’) matching aperture width used during image acquisition.

Raises:

ValueError – Raised if the value parameter cannot be mapped to an
aperture code. –

metadata()¶: Returns a dictionary of the image’s metadata.

channel_inds(channels)¶

Returns the indices of the specified channels on the data’s 2nd axis.

Parameters:: channels – A single channel, mass or target label; or, a sequence of channels, masses, or targets.
Returns:: A scalar or numpy array of the indices of the specified channels.
Raises:: KeyError – Raised if channels are not all found in image.

slice_data(channels)¶

Selects a subset of data from the MibiImage given selected channels.

If a single channel is given, the third dimension will be stripped and an actual slice of the array will be returned, not a copy.

If a sequence of channels is given, even if it is a sequence of length 1, a copy will be returned.

This method can also be called by indexing with [] (i.e. __getitem__(). See also slice_image().

Parameters:: channels – A single channel, mass or target label; or, a sequence of channels, masses, or targets.
Returns:: A numpy array containing the data sliced from the image.

slice_image(channels)¶

Returns a MibiImage from slicing channels of another MibiImage.

mibidata.panels module¶

Utility for working with panels saved as CSV files.

mibidata.panels.read_csv(path)¶

Reads a panel CSV file into a dataframe.

Parameters:: path – The path to the CSV file.
Returns:: A dataframe containing columns ‘Mass’ and ‘Target’.

mibidata.panels.merge_masses(df)¶

Merges ‘Target’ cells of a DataFrame with the same ‘Mass’ value.

This function merges multiple targets that are conjugated to the same mass tag such that the returned DataFrame contains only unique masses. Target names are combined using the conventions of :func:’util.natural_sort()’.

Parameters:: df – A DataFrame of the panel containing columns ‘Mass’ and ‘Target’.
Returns:: A DataFrame containing columns ‘Mass’ and ‘Target’ with merged targets of the same mass.

mibidata.pseudodepths module¶

Splits single-depth MIBI scans into pseudo Depth Profiles.

mibidata.pseudodepths.divide(msdf_file, num_scans, path=None)¶

Creates a pseudo depth profile from a single Image.msdf file.

Parameters:

msdf_file – The string path to a local msdf file.
num_scans – The integer number of pseudo-depths into which to divide this msdf file. This must be a divisor of the number of ToF cycles per pixel.
path – The string path to the folder into which to write the output msdf files, which will follow the convention Depth0/Image.msdf, Depth1/Image.msdf, etc. If Depth<n>/Image.msdf files already exist in this location, they will be overwritten. If no path is specified, this will default to creating a folder named PseudoDepths in the same directory as the input msdf file.

Returns:

The integer number of ToF cycles per pixel in the: original data.

cycles_per_scan: The integer number of ToF cycles per each output
pseudo-depth.

Return type:

cycles_per_pixel

Raises:

ValueError – Raised if the msdf file is not >=6.3.4.0 with ToF cycle number encoded, or if the number of scans given is not a divisor of the number of cycles per scan.

mibidata.runs module¶

Utilities for working with MIBI run metadata.

mibidata.runs.parse_xml(path)¶

Read a run XML and return a list of image metadata dicts, plus a dict of the mass calibration and other msdf metadata.

Parameters:: path – A path to a run XML file.
Returns:: A list of image metadata dicts for each FOV. calibration: A dict containing mass calibration parameters.
Return type:: fovs

mibidata.segmentation module¶

Utilities for working with segmentation data.

mibidata.segmentation.extract_cell_dataframe(label_image, image=None, mode='total', num_sectors=8)¶

Creates a dataframe of single-cell statistics from a labeled image.

Parameters:

label_image – An NxM array where each pixel’s nonnegative integer value corresponds to the label of an image region, such as a cell or other segment.
image – Optionally, a MibiImage of an NxM field of view. Defaults to None; if not None, the sum or score (depending on the mode) of each channel within each labeled region is returned as column of the dataframe. Otherwise, only the regions’ size and area are returned.
mode – One of``’total’, ``'quadrant' or 'circular_sectors', defaulting to 'total'. If 'total'`, the ion counts within each labeled region are summed. If ``'quadrant', the geometric mean of each regions’s four quadrants is calculated, which favors regions with even spatial distribution. If 'circular_sectors', the geometric mean of each regions’s num_sectors circular sectors is calculated. This is a generalization of the quadrant mode. The mode is ignored if an image is not specified.
num_sectors – number of circular sectors to use in the circular_sectors mode. Optional, default is 8.

Returns:

A dataframe indexed by image region’s label, and whose columns include the area, centroid, and if included the total or scored counts of the image’s channels within each region.

mibidata.segmentation.replace_labeled_pixels(label_image, df, columns=None)¶

Replaces the pixels within each label with a value from a dataframe.

Parameters:

label_image – An NxM array where each pixel’s nonnegative integer value corresponds to the label of an image region, such as a cell or other segment.
df – A dataframe whose index corresponds to the integers in the label_array, and whose column values will replace the labels in the returned image. It is expected that the index will have name ‘label’ as is returned from :function:`extract_cell_dataframe`.
columns – An optional sequence of which columns from the dataframe to include in the returned image. Defaults to None, which uses all columns in the dataframe.

Returns:

A mibidata.mibi_image.MibiImage instance where each channel corresponds to a dataframe column, and the data is a copy of the label image where each pixel has been replaced with the corresponding value from that label’s row in the dataframe.

Raises:

IndexError – if the index values of the DataFrame do not match the labels in the image.

mibidata.segmentation.expand_objects(label_image, distance)¶

Expands labeled objects in an image by a given number of pixels.

Parameters:

label_image – An NxM array where each pixel’s nonnegative integer value corresponds to the label of an image region, such as a cell or other segment.
distance – The distance (in pixels) to expand each object.

Returns:

A new label array of the expanded objects.

mibidata.segmentation.filter_by_size(label_image, min_size, max_size)¶

Removes segments outside of a specified size range.

Parameters:

label_image – An NxM array where each pixel’s nonnegative integer value corresponds to the label of an image region, such as a cell or other segment.
min_size – The minimum area in pixels of a segment.
max_size – The maximum area in pixels of a segment.

Returns:

A new label image, where segments outside of the size range have been set to zero, and a dataframe of its labels, centroids and area.

mibidata.segmentation.get_adjacency_matrix(label_image)¶

Calculates adjacency matrix.

Parameters:

label_image – An NxM array where each pixel’s nonnegative integer value corresponds to the label of an image region, such as a cell or other segment.

Returns:

NxN array of floats (N is the number of labels): Each i, j element of the adjacency_matrix corresponds to the fraction of the i region boundary length that is shared with j region.

Return type:

adjacency_matrix

mibidata.tiff module¶

Read and write to and from IONpath MIBItiff files.

mibidata.tiff.write(filename, image, sed=None, optical=None, ranges=None, multichannel=True, dtype=None, write_float=None)¶

Writes MIBI data to a multipage TIFF.

Parameters:

filename – The path to the target file if multi-channel, or the path to a folder if single-channel.
image – A mibidata.mibi_image.MibiImage instance.
sed – Optional, an array of the SED image data. This is assumed to be grayscale even if 3-dimensional, in which case only one channel will be used.
optical – Optional, an RGB array of the optical image data.
ranges – A list of (min, max) tuples the same length as the number of channels. If None, the min will default to zero and the max to the max pixel value in that channel. This is used by some external software to calibrate the display.
multichannel – Boolean for whether to create a single multi-channel TIFF, or a folder of single-channel TIFFs. Defaults to True; if False, the sed and optical options are ignored.
dtype – dtype: One of (np.float32, np.uint16) to force the dtype of the saved image data. Defaults to None, which chooses the format based on the data’s input type, and will convert to np.float32 or np.uint16 from other float or int types, respectively, if it can do so without a loss of data.
write_float – Deprecated, will raise ValueError if specified. To specify the dtype of the saved image, please use the dtype argument instead.

Raises:

ValueError – Raised if * The image is not a mibidata.mibi_image.MibiImage instance. * The mibidata.mibi_image.MibiImage coordinates, size, fov_id, fov_name, run, folder, dwell, scans, mass_gain, mass_offset, time_resolution, masses or targets are None. * dtype is not one of np.float32 or np.uint16. * write_float has been specified. * Converting the native mibidata.mibi_image.MibiImage dtype to the specified or inferred dtype results in a loss of data.

mibidata.tiff.read(file, sims=True, sed=False, optical=False, label=False, masses=None, targets=None)¶

Reads MIBI data from an IonpathMIBI TIFF file.

Parameters:

file – The string path or an open file object to a MIBItiff file.
sims – Boolean for whether to return the SIMS (MIBI) data. Defaults to True.
sed – Boolean for whether to return the SED data. Defaults to False.
optical – Boolean for whether to return the optical image. Defaults to False.
label – Boolean for whether to return the slide label image. Defaults to False.
masses – A list of integer masses. If specified, only channels corresponding to these masses will be included in the returned MibiImage. Either masses or targets can be specified, not both.
targets – A list of string targets. If specified, only channels corresponding to these targets will be included in the returned MibiImage. Either masses or targets can be specified, not both.

Returns: A tuple of the image types set to True in the parameters, in the: order SIMS, SED, Optical, Label (but including only those types specified). The SIMS data will be returned as a mibidata.mibi_image.MibiImage instance; the other image types will be returned as numpy arrays. If an image type is selected to be returned but is not present in the image, it will be returned as None. If returning SIMS data and the masses or targets parameters are set, only those channels will be included in the MibiImage instance, otherwise all channels present in the file will be returned.

Raises:: ValueError – Raised if * The input file is not of the IONpath MIBItiff format * No image type is selected to be returned. * Both masses and targets are specified.

mibidata.tiff.info(filename)¶

Gets the metadata from a MIBItiff file.

Parameters:: filename – The path to the TIFF.
Returns:: A dictionary of metadata as could be supplied as kwargs to mibidata.mibi_image.MibiImage, except with a channels key whose value is a list of (mass, target) tuples.

mibidata.util module¶

Common convenience functions used in mibidata module.

mibidata.util.encode_strings(string_list, encoding='utf-8')¶

Encodes each string in a list into a bytes object and returns a list of bytes objects. Useful function when writing and reading string lists which are not supported in pytables.

Parameters:

string_list – A list of strings to encode.
encoding – Encoding to use, defaults to UTF-8.

Returns:

A list of bytes objects that have been encoded with the given encoding.

mibidata.util.decode_strings(bytes_objects_list, encoding='utf-8')¶

Decodes each bytes object in a list into a string and returns a list of strings. Useful function when writing and reading string lists which are not supported in pytables.

Parameters:

bytes_objects_list – A list of strings to encode.
encoding – Encoding to use, defaults to UTF-8.

Returns:

A list of strings that have been decoded with the given encoding.

mibidata.util.natural_sort(l)¶

Sorts a list of strings in the way that humans expect, in place.

For example, this would order ‘Depth2’ before ‘Depth11’, whereas sort would place those in the opposite order.

Parameters:: l – A list of strings.

mibidata.util.sort_channel_names(l)¶

Sorts a list of string in place such that number only string are after all text strings and text strings with numbers are sorted alphabetically.

ex: [‘beta-tubulin’, ‘CD20’, ‘CD4’, ‘CD45’, ‘CD8’, ‘dsDNA’, ‘Keratin’,: ‘23’, ‘97’, ‘144’, ‘150’]

Parameters:: l – A list of strings.

mibidata.util.format_for_filename(label)¶: Replaces delimiters and utf-8 encodes targets for use as filenames.

mibidata.util.car2pol(x, y, x_c=0, y_c=0, degrees=False)¶

Convert cartesian to polar coordinates w.r.t. a central point. Angle phi is returned in the range [0, 2 pi) rad. A flag can be activated to return phi angles in degrees.

Parameters:

x – arrays of coordinates to transform.
y – arrays of coordinates to transform.
x_c – numbers representing the coordinates of the center (origin of polar coordinates). Optional; default is (0, 0).
y_c – numbers representing the coordinates of the center (origin of polar coordinates). Optional; default is (0, 0).
degrees – flag to return phi angles in degrees instead of radians. Optional; default is False (i.e. radians).

Returns:

arrays of transformed coordinates.

Return type:

r, phi

mibidata package¶

Submodules¶

mibidata.color module¶

mibidata.combine_tiffs module¶

mibidata.constants module¶

mibidata.mibi_image module¶

mibidata.panels module¶

mibidata.pseudodepths module¶

mibidata.runs module¶

mibidata.segmentation module¶

mibidata.tiff module¶

mibidata.util module¶

Module contents¶

Ionpath MIBIlib

Navigation

Related Topics