nyxus.Nyxus

class Nyxus(features, neighbor_distance=5.0, pixels_per_micron=1.0, coarse_gray_depth=256, n_feature_calc_threads=4, n_loader_threads=1, using_gpu=-1, ibsi=False)

Bases: object

Nyxus image feature extraction library

Scalably extracts features from images.

Parameters

features (list[str]) –
List of features to be calculated. Individual features can be provided or pre-specified feature groups. Valid groups include:

ALL ALL_INTENSITY ALL_MORPHOLOGY BASIC_MORPHOLOGY ALL_GLCM ALL_GLRM ALL_GLSZM ALL_GLDM ALL_NGTDM ALL_BUT_GABOR ALL_BUT_GLCM

Both individual features and feature groups are case sensitive.
neighbor_distance (float (optional, default 5.0)) – Any two objects separated by a Euclidean distance (pixel units) greater than this value will not be be considered neighbors. This cutoff is used by all features which rely on neighbor identification.
pixels_per_micron (float (optional, default 1.0)) – Specify the image resolution in terms of pixels per micron for unit conversion of non-unitless features.
coarse_gray_depth (int (optional, default 256)) – Custom number of levels in grayscale denoising used in texture features.
n_feature_calc_threads (int (optional, default 4)) – Number of threads to use for feature calculation parallelization purposes.
n_loader_threads (int (optional, default 1)) – Number of threads to use for loading image tiles from disk. Note: image loading multithreading is very memory intensive. You should consider optimizing n_feature_calc_threads before increasing n_loader_threads.
using_gpu (int (optional, default -1)) – Id of the gpu to use. To find available gpus along with ids, using nyxus.get_gpu_properties(). The default value of -1 uses cpu calculations. Note that the gpu features only support a single thread for feature calculation.
ibsi (bool (optional, default false)) – IBSI available features will be IBSI compliant when true.

__init__(features, neighbor_distance=5.0, pixels_per_micron=1.0, coarse_gray_depth=256, n_feature_calc_threads=4, n_loader_threads=1, using_gpu=-1, ibsi=False)

Parameters

features (List[str]) –
neighbor_distance (float) –
pixels_per_micron (float) –
coarse_gray_depth (int) –
n_feature_calc_threads (int) –
n_loader_threads (int) –
using_gpu (int) –
ibsi (bool) –

Methods

`__init__`(features[, neighbor_distance, ...])
`blacklist_roi`(blacklist)	Defines the application-wide ROI blacklist
`clear_roi_blacklist`()	Clears the ROI blacklist
`featurize`(intensity_images, label_images[, ...])	Extract features from a single image pair in a 2D np.array or for all the images in a 3D np.array.
`featurize_directory`(intensity_dir[, ...])	Extract features from all the images satisfying the file pattern of provided image directories.
`featurize_files`(intensity_files, mask_files)	Extract features from image file pairs passed as lists
`roi_blacklist_get_summary`()	Returns a human-friendly text of the summary of the application-wide ROI blacklist
`using_gpu`(gpu_on)

blacklist_roi(blacklist)

Defines the application-wide ROI blacklist

Defines a set of ROI labels that need to be skipped during feature extraction and in the output. Examples: ‘27,28,30’ - defines a global blacklist of ROI labels 27, 28, and 30 ‘file1.ome.tif:5,6,7;file2.ome.tif:11,12,13,14’ - defines 2 file-specific blacklists

Parameters: blacklist (blacklist definition (string)) –
Return type: None

clear_roi_blacklist()

Clears the ROI blacklist

Parameters: None –
Return type: None

featurize(intensity_images, label_images, intensity_names=[], label_names=[])

Extract features from a single image pair in a 2D np.array or for all the images in a 3D np.array.

Extracts all the requested features _at the image level_ from the images in intensity_images. Features will be extracted for each unique label present in the label images. The name of resulting features in df will be autogenerated if no intensity and label names are provided. Note that if names are provided, the number of names must be the same as the number of images.

Parameters

intensity_dir (np.array) – 2D image or 3D collection of intensity images.
label_images (np.array) – 2D image or 3D collection of label images.
(optional) (label_names) – names for the images in for the DataFrame output.
(optional) – names for the labels in for the DataFrame output.
intensity_images (array) –
intensity_names (list) –
label_names (list) –

Returns

df – Pandas DataFrame containing the requested features with one row per label per image.

Return type

pd.DataFrame

featurize_directory(intensity_dir, label_dir=None, file_pattern='.*')

Extract features from all the images satisfying the file pattern of provided image directories.

Extracts all the requested features _at the image level_ from the images present in intensity_dir. If label_dir is specified, features will be extracted for each unique label present in the label images. The file names of the label images are expected to match those of the intensity images.

Parameters

intensity_dir (str) – Path to directory containing intensity images.
label_dir (str (optional, default None)) – Path to directory containing label images.
file_pattern (str (optional, default ".*")) – Regular expression used to filter the images present in both intensity_dir and label_dir

Returns

df – Pandas DataFrame containing the requested features with one row per label per image.

Return type

pd.DataFrame

featurize_files(intensity_files, mask_files)

Extract features from image file pairs passed as lists

Extracts all the requested features _at the image level_ from the intensity images present in list intensity_files with respect to region of interest masks presented in list mask_files. Multiple

Parameters

intensity_files (list of intensity image file paths) –
mask_files (list of mask image file paths) –

Returns

df – Pandas DataFrame containing the requested features with one row per label per image.

Return type

pd.DataFrame

roi_blacklist_get_summary()

Returns a human-friendly text of the summary of the application-wide ROI blacklist

Parameters: None –
Return type: text of blacklist summary (string)