nyxus.Nyxus

class Nyxus(features, **kwargs)

Bases: object

Nyxus image feature extraction library

Scalably extracts features from images.

Example: nyx = Nyxus(

features = [[”ALL”]], 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_thold = 0.025, gabor_thetas = [0, 45, 90, 135], gabor_freqs = [4, 16, 32, 64]

)

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, default 0.8)) – Spatial frequency bandwidth.
gabor_f0 (float (optional, default 0.1)) – frequency of the baseline lowpass filter as denominator of pi.
gabor_thetas (list[float] (optional, default [0, 45, 90, 135]):) – 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[float] (optional, default [4, 16, 32, 64])) – comma-separated denominators of pi as frequencies of Gabor filter’s harmonic factor.
channel_signature ((optional)) – Channel signature to match files with the given channel name, such as channel_signature=’c’ for ‘_c’ like in ‘p0_y1_r1_c1.ome.tiff’
parent_channel ((optional)) – Channel number that should be used as a provider of parent segments
child_channel ((optional)) – Channel number that should be used as a provider of child segments
aggregate ((optional)) – Name of a method how to aggregate features of segments recognized as children of same parent segment. Options are ‘SUM’, ‘MEAN’, ‘MIN’, ‘MAX’, ‘WMA’, and ‘NONE’.
dynamic_range ((optional)) – Desired dynamic range of voxels of a floating point TIFF image.
min_intensity ((optional, default 0.0)) – Minimum intensity of voxels of a floating point TIFF image.
max_intensity ((optional, default 1.0)) – Maximum intensity of voxels of a floating point TIFF image.

__init__(features, **kwargs)

Parameters: features (List[str]) –

Methods

`__init__`(features, **kwargs)
`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
`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_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

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.
intensity_names (list (optional, default [])) – names for the images in for the DataFrame output.
label_names (list (optional, default [])) – names for the labels in for the DataFrame output.
output_type (str (optional, default "pandas")) – Output format for the features values. Valid options are “pandas”, “arrowipc”, and “parquet”.
output_path (str (optional, default "")) –
Output filepath for Arrow IPC and Parquet output formats. Default is “”, which is the current directory. The output_path can either be to a directory or filename. For example,
- If ‘output_path=/path/to/directory’ then a file with the default name NyxusFeatures.<extension> will be created. If the directory does not exist, it will be created.
- If ‘output_path=/path/to/directory/some_file_name.arrow’ then this file will be created. If the directory does not exist, it will also be created.
- If ‘output_path=some_file_name.arrow’ then this file will be created in the current working directory.

Returns

df – if output_type == pandas Pandas DataFrame containing the requested features with one row per label per image. Otherwise, arrow file path

Return type

pd.DataFrame or str

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 (str (optional, default "pandas")) – Output format for the features values. Valid options are “pandas”, “arrowipc”, and “parquet”.
output_path (str (optional, default "")) –
Output filepath for Arrow IPC and Parquet output formats. Default is “”, which is the current directory. The output_path can either be to a directory or filename. For example,
- If ‘output_path=/path/to/directory’ then a file with the default name NyxusFeatures.<extension> will be created. If the directory does not exist, it will be created.
- If ‘output_path=/path/to/directory/some_file_name.arrow’ then this file will be created. If the directory does not exist, it will also be created.
- If ‘output_path=some_file_name.arrow’ then this file will be created in the current working directory.

Returns

df – if output_type == pandas Pandas DataFrame containing the requested features with one row per label per image. Otherwise, arrow file path

Return type

pd.DataFrame or str

featurize_files(intensity_files, mask_files, single_roi, 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. Single-ROI feature extraction is enforced via passing ‘True’ as parameter ‘single_roi’

Parameters

intensity_files (list of intensity image file paths) –
mask_files (list of mask image file paths) –
single_roi ('True' to treat items of 'intensity_files' as single-ROI ('mask_files' will be ignored), 'False' to treat items of 'intensity_files' and 'mask_files' as intensity/segmentation image pairs) –
output_type (str (optional, default "pandas")) – Output format for the features values. Valid options are “pandas”, “arrowipc”, and “parquet”.
output_path (str (optional, default "")) –
Output filepath for Arrow IPC and Parquet output formats. Default is “”, which is the current directory. The output_path can either be to a directory or filename. For example,
- If ‘output_path=/path/to/directory’ then a file with the default name NyxusFeatures.<extension> will be created. If the directory does not exist, it will be created.
- If ‘output_path=/path/to/directory/some_file_name.arrow’ then this file will be created. If the directory does not exist, it will also be created.
- If ‘output_path=some_file_name.arrow’ then this file will be created in the current working directory.

Returns

df – if output_type == pandas Pandas DataFrame containing the requested features with one row per label per image. Otherwise, arrow file path

Return type

pd.DataFrame or str

get_arrow_ipc_file()

Returns the path to the Arrow IPC file.

Parameters: None –
Return type: Path to the Arrow IPC file (string)

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
dynamic_range (float): Desired dynamic range of voxels of a floating point TIFF image.
min_intensity (float): Minimum intensity of voxels of a floating point TIFF image.
max_intensity (float): Maximum intensity of voxels of a floating point TIFF image.
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_thetas (str): comma-separated orientations of the Gaussian in degrees 0-180. Example: set_params(gabor_thetas=”45,60,70”)
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.
verbose: int (optional, non-negative, default 0)
Level of diagnostic output shown in the console. Set ‘0’ to disable any diagnostic output.

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) * thold (float): lower threshold of the filtered image to baseline ratio. Example: customize_gabor_feature(thold=0.025) * thetas (list[int]): list of orientations of the Gaussian in degrees 0-180 matching ‘freqs’. Example: customize_gabor_feature(theta=1.5708) * 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
dynamic_range (float): Desired dynamic range of voxels of a floating point TIFF image.
min_intensity (float): Minimum intensity of voxels of a floating point TIFF image.
max_intensity (float): Maximum intensity of voxels of a floating point TIFF image.
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_thetas (str): comma-separated orientations of the Gaussian in degrees 0-180. Example: set_params(gabor_thetas=”0,45,60”)
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”)