nyxus.Nyxus

class Nyxus(features, neighbor_distance=5, pixels_per_micron=1.0, coarse_gray_depth=256, n_feature_calc_threads=4, n_loader_threads=1, using_gpu=-1, ibsi=False, gabor_kersize=16, gabor_gamma=0.1, gabor_sig2lam=0.8, gabor_f0=0.1, gabor_theta=45, gabor_thold=0.025, gabor_freqs=[1, 2, 4, 8, 16, 32, 64])

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 (int (optional, default 5)) – 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.

  • gabor_kersize (int (optional, default 16)) – Size of filter kernel’s side

  • gabor_gamma (float (optional, default 0.1)) – Aspect ratio of the Gaussian factor

  • gabor_sig2lam (float (optional, deafult 0.8)) – Spatial frequency bandwidth.

  • gabor_f0 (float (optional, default 0.1)) – frequency of the baseline lowpass filter as denominator of pi.

  • gabor_theta (float (optional, default 45):) – Orientation of the Gaussian in degrees 0-180.

  • gabor_thold (float (optional, 0.025)) – lower threshold of the filtered image to baseline ratio.

  • gabor_freqs (list[int] (optional, default [1,2,4,8,16,32,64])) – comma-separated denominators of pi as frequencies of Gabor filter’s harmonic factor.

__init__(features, neighbor_distance=5, pixels_per_micron=1.0, coarse_gray_depth=256, n_feature_calc_threads=4, n_loader_threads=1, using_gpu=-1, ibsi=False, gabor_kersize=16, gabor_gamma=0.1, gabor_sig2lam=0.8, gabor_f0=0.1, gabor_theta=45, gabor_thold=0.025, gabor_freqs=[1, 2, 4, 8, 16, 32, 64])
Parameters

  • features (List[str]) –

  • neighbor_distance (int) –

  • pixels_per_micron (float) –

  • coarse_gray_depth (int) –

  • n_feature_calc_threads (int) –

  • n_loader_threads (int) –

  • using_gpu (int) –

  • ibsi (bool) –

  • gabor_kersize (int) –

  • gabor_gamma (float) –

  • gabor_sig2lam (float) –

  • gabor_f0 (float) –

  • gabor_theta (float) –

  • gabor_thold (float) –

  • gabor_freqs (List[int]) –

Methods

__init__(features[, neighbor_distance, ...])

arrow_is_enabled()

Returns true if arrow support is enabled.

blacklist_roi(blacklist)

Defines the application-wide ROI blacklist

clear_roi_blacklist()

Clears the ROI blacklist

create_arrow_file([path])

Creates an Arrow IPC file containing the features.

create_parquet_file([path])

Creates a Parquet file containing the features.

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

get_arrow_ipc_file()

Returns the path to the Arrow IPC file.

get_arrow_memory_mapping()

Returns a memory mapping to the Arrow IPC file.

get_arrow_table()

Returns an arrow table containing the feature calculations.

get_params(*args)

Returns the parameters of a Nyxus object.

get_parquet_file()

Returns the path to the Arrow IPC file.

roi_blacklist_get_summary()

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

set_environment_params(**params)

Sets parameters of the environment for Nyxus

set_gabor_feature_params(**kwargs)

Sets parameters of feature GABOR

set_params(**params)

Sets parameters of the Nyxus class

using_gpu(gpu_on)

arrow_is_enabled()

Returns true if arrow support is enabled.

Parameters

None –

Returns

bool

Return type

If arrow support is enabled

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

create_arrow_file(path='NyxusFeatures.arrow')

Creates an Arrow IPC file containing the features.

This method must be called after calling one of the featurize methods.

Parameters

path (Path to write the arrow file to. (Optional, default "NyxusFeatures.arrow")) –

Return type

None

create_parquet_file(path='NyxusFeatures.parquet')

Creates a Parquet file containing the features.

This method must be called after calling one of the featurize methods.

Parameters

path (Path to write the parquet file to. (Optional, default "NyxusFeatures.parquet")) –

Return type

None

featurize(intensity_images, label_images, intensity_names=[], label_names=[], output_type='pandas', output_path='')

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_images (np.ndarray) – 2D image or 3D collection of intensity images.

  • label_images (np.ndarray) – 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_names (list) –

  • label_names (list) –

  • output_type (Optional[str]) –

  • output_path (Optional[str]) –

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='.*', output_type='pandas', output_path='')

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

  • output_type (Optional[str]) –

  • output_path (Optional[str]) –

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, output_type='pandas', output_path='')

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) –

  • output_type (Optional[str]) –

  • output_path (Optional[str]) –

Returns

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

Return type

pd.DataFrame

get_arrow_ipc_file()

Returns the path to the Arrow IPC file.

Parameters

None –

Return type

Path to the Arrow IPC file (string)

get_arrow_memory_mapping()

Returns a memory mapping to the Arrow IPC file.

This method creates a memory mapping between the Arrow IPC file on disk to allow for random access. This method does not consume addition RAM.

Parameters

None –

Return type

MemoryMappedFile

get_arrow_table()

Returns an arrow table containing the feature calculations.

Parameters

None –

Return type

pyarrow.Table

get_params(*args)

Returns the parameters of a Nyxus object. If no args are supplied, all parameters will be returned.

Valid parameters are:

  • features: List[str],

  • neighbor_distance

  • pixels_per_micron

  • coarse_gray_depth

  • n_feature_calc_threads

  • n_loader_threads

  • using_gpu

  • ibsi: bool

  • gabor_kersize (int): size of filter kernel’s side. Example: set_params(gabor_kersize=16)

  • gabor_gamma (float): aspect ratio of the Gaussian factor. Example: set_params(gabor_gamma=0.1)

  • gabor_sig2lam (float): spatial frequency bandwidth. Example: set_params(gabor_sig2lam=0.8)

  • gabor_f0 (float): frequency of the baseline lowpass filter as denominator of pi. Example: set_params(gabor_f0=0.1)

  • gabor_theta (float): orientation of the Gaussian in degrees 0-180. Example: set_params(gabor_theta=1.5708)

  • gabor_thold (float): lower threshold of the filtered image to baseline ratio. Example: set_params(gabor_thold=0.025)

  • gabor_freqs (str): comma-separated denominators of pi as frequencies of Gabor filter’s harmonic factor. Example: set_params(gabor_freqs=”1,2,4,8,16,32,64”)

Parameters

args (Strings containing parameter names to get the value of. (Optional)) –

Returns

A dictionary mapping the parameter name to the value

Return type

dict

get_parquet_file()

Returns the path to the Arrow IPC file.

Parameters

None –

Return type

Path to the Parquet file (string)

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)

set_environment_params(**params)

Sets parameters of the environment for Nyxus

Keyword args: *neighbor_distance: int

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

    Specify the image resolution in terms of pixels per micron for unit conversion of non-unitless features.

  • coarse_gray_depth: int

    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 )

    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

    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.

set_gabor_feature_params(**kwargs)

Sets parameters of feature GABOR

Keyword args: * kersize (int): size of filter kernel’s side. Example: customize_gabor_feature(kersize=16) * gamma (float): aspect ratio of the Gaussian factor. Example: customize_gabor_feature(gamma=0.1) * sig2lam (float): spatial frequency bandwidth. Example: customize_gabor_feature(sig2lam=0.8) * f0 (float): frequency of the baseline lowpass filter as denominator of pi. Example: customize_gabor_feature(f0=0.1) * theta (float): orientation of the Gaussian in degrees 0-180. Example: customize_gabor_feature(theta=1.5708) * thold (float): lower threshold of the filtered image to baseline ratio. Example: customize_gabor_feature(thold=0.025) * freqs (list[int]): list of denominators of pi as frequencies of Gabor filter’s harmonic factor. Example: customize_gabor_feature(freqs=”1,2,4,8,16,32,64”)

set_params(**params)

Sets parameters of the Nyxus class

Keyword args:

  • features: List[str],

  • neighbor_distance

  • pixels_per_micron

  • coarse_gray_depth

  • n_feature_calc_threads

  • n_loader_threads

  • using_gpu

  • ibsi: bool

  • gabor_kersize (int): size of filter kernel’s side. Example: set_params(gabor_kersize=16)

  • gabor_gamma (float): aspect ratio of the Gaussian factor. Example: set_params(gabor_gamma=0.1)

  • gabor_sig2lam (float): spatial frequency bandwidth. Example: set_params(gabor_sig2lam=0.8)

  • gabor_f0 (float): frequency of the baseline lowpass filter as denominator of pi. Example: set_params(gabor_f0=0.1)

  • gabor_theta (float): orientation of the Gaussian in degrees 0-180. Example: set_params(gabor_theta=1.5708)

  • gabor_thold (float): lower threshold of the filtered image to baseline ratio. Example: set_params(gabor_thold=0.025)

  • gabor_freqs (str): comma-separated denominators of pi as frequencies of Gabor filter’s harmonic factor. Example: set_params(gabor_freqs=”1,2,4,8,16,32,64”)