Skip to main content

Scalable library for calculating features from intensity-label image data

Project description

Nyxus

A scalable library for calculating features from intensity-label image data

Overview

Nyxus is a feature-rich, highly optimized, Python/C++ application capable of analyzing images of arbitrary size and assembling complex regions of interest (ROIs) split across multiple image tiles and files. This accomplished through multi-threaded tile prefetching and a three phase analysis pipeline shown below.

Nyxus can be used via Python or command line and is available in containerized form for reproducible execution. Nyxus computes over 450 combined intensity, texture, and morphological features at the ROI or whole image level with more in development. Key features that make Nyxus unique among other image feature extraction applications is its ability to operate at any scale, its highly validated algorithms, and its modular nature that makes the addition of new features straightforward.

Getting started

For use in python, the latest version of Nyxus can be installed via the Pip package manager:

pip install nyxus

Usage is very straightforward. Given intensities and labels folders, Nyxus pairs up intensity-label pairs and extracts features from them. A summary of the avaialble feature are listed below.

from nyxus import Nyxus

intensity_path = "/path/to/images/intensities/"
labels_path = "/path/to/images/labels/"

nyx = Nyxus(["*ALL*"])

features = nyx.featurize(intensity_path, labels_path)

The features variable is a Pandas dataframe similar to what is shown below.

mask_image intensity_image label MEAN MEDIAN ... GABOR_6
0 p1_y2_r51_c0.ome.tif p1_y2_r51_c0.ome.tif 1 45366.9 46887 ... 0.873016
1 p1_y2_r51_c0.ome.tif p1_y2_r51_c0.ome.tif 2 27122.8 27124.5 ... 1.000000
2 p1_y2_r51_c0.ome.tif p1_y2_r51_c0.ome.tif 3 34777.4 33659 ... 0.942857
3 p1_y2_r51_c0.ome.tif p1_y2_r51_c0.ome.tif 4 35808.2 36924 ... 0.824074
4 p1_y2_r51_c0.ome.tif p1_y2_r51_c0.ome.tif 5 36739.7 37798 ... 0.854067
... ... ... ... ... ... ... ...
734 p5_y0_r51_c0.ome.tif p5_y0_r51_c0.ome.tif 223 54573.3 54573.3 ... 0.980769

For more information on all of the available options and features, check out the documentation.

Nyxus can also be built from source and used from the command line, or via a pre-built Docker container.

Available features

The feature extraction plugin extracts morphology and intensity based features from pairs of intensity/binary mask images and produces a csv file output. The input image should be in tiled OME TIFF format. The plugin extracts the following features:

Nyxus provides a set of pixel intensity, morphology, texture, intensity distribution features, digital filter based features and image moments


Nyxus feature code Description
INTEGRATED_INTENSITY Integrated intensity of the region of interest (ROI)
MEAN, MAX, MEDIAN, STANDARD_DEVIATION, MODE Mean/max/median/stddev/mode intensity value of the ROI
SKEWNESS, KURTOSIS, HYPERSKEWNESS, HYPERFLATNESS higher standardized moments
MEAN_ABSOLUTE_DEVIATION Mean absolute devation
ENERGY ROI energy
ROOT_MEAN_SQUARED Root of mean squared deviation
ENTROPY ROI entropy - a measure of the amount of information in the ROI
UNIFORMITY Uniformity - measures how uniform the distribution of ROI intensities is
UNIFORMITY_PIU Percent image uniformity, another measure of intensity distribution uniformity
P01, P10, P25, P75, P90, P99 1%, 10%, 25%, 75%, 90%, and 99% percentiles of intensity distribution
INTERQUARTILE_RANGE Distribution's interquartile range
ROBUST_MEAN_ABSOLUTE_DEVIATION Robust mean absolute deviation
MASS_DISPLACEMENT ROI mass displacement
AREA_PIXELS_COUNT ROI area in the number of pixels
COMPACTNESS Mean squared distance of the object’s pixels from the centroid divided by the area
BBOX_YMIN Y-position and size of the smallest axis-aligned box containing the ROI
BBOX_XMIN X-position and size of the smallest axis-aligned box containing the ROI
BBOX_HEIGHT Height of the smallest axis-aligned box containing the ROI
BBOX_WIDTH Width of the smallest axis-aligned box containing the ROI
MAJOR/MINOR_AXIS_LENGTH, ECCENTRICITY, ORIENTATION, ROUNDNESS Inertia ellipse features
NUM_NEIGHBORS, PERCENT_TOUCHING The number of neighbors bordering the ROI's perimeter and related neighbor methods
EXTENT Proportion of the pixels in the bounding box that are also in the region
CONVEX_HULL_AREA Area of ROI's convex hull
SOLIDITY Ratio of pixels in the ROI common with its convex hull image
PERIMETER Number of pixels in ROI's contour
EQUIVALENT_DIAMETER Diameter of a circle with the same area as the ROI
EDGE_MEAN/MAX/MIN/STDDEV_INTENSITY Intensity statistics of ROI's contour pixels
CIRCULARITY Represents how similar a shape is to circle. Clculated based on ROI's area and its convex perimeter
EROSIONS_2_VANISH Number of erosion operations for a ROI to vanish in its axis aligned bounding box
EROSIONS_2_VANISH_COMPLEMENT Number of erosion operations for a ROI to vanish in its convex hull
FRACT_DIM_BOXCOUNT, FRACT_DIM_PERIMETER Fractal dimension features
GLCM Gray level co-occurrence Matrix features
GLRLM Gray level run-length matrix based features
GLSZM Gray level size zone matrix based features
GLDM Gray level dependency matrix based features
NGTDM Neighbouring gray tone difference matrix features
ZERNIKE2D, FRAC_AT_D, RADIAL_CV, MEAN_FRAC Radial distribution features
GABOR A set of Gabor filters of varying frequencies and orientations

For the complete list of features see Nyxus provided features

Feature groups

Apart from defining your feature set by explicitly specifying comma-separated feature code, Nyxus lets a user specify popular feature groups. Supported feature groups are:


Group code Belonging features
*all_intensity* integrated_intensity, mean, median, min, max, range, standard_deviation, standard_error, uniformity, skewness, kurtosis, hyperskewness, hyperflatness, mean_absolute_deviation, energy, root_mean_squared, entropy, mode, uniformity, p01, p10, p25, p75, p90, p99, interquartile_range, robust_mean_absolute_deviation, mass_displacement
*all_morphology* area_pixels_count, area_um2, centroid_x, centroid_y, weighted_centroid_y, weighted_centroid_x, compactness, bbox_ymin, bbox_xmin, bbox_height, bbox_width, major_axis_length, minor_axis_length, eccentricity, orientation, num_neighbors, extent, aspect_ratio, equivalent_diameter, convex_hull_area, solidity, perimeter, edge_mean_intensity, edge_stddev_intensity, edge_max_intensity, edge_min_intensity, circularity
*basic_morphology* area_pixels_count, area_um2, centroid_x, centroid_y, bbox_ymin, bbox_xmin, bbox_height, bbox_width
*all_glcm* glcm_angular2ndmoment, glcm_contrast, glcm_correlation, glcm_variance, glcm_inversedifferencemoment, glcm_sumaverage, glcm_sumvariance, glcm_sumentropy, glcm_entropy, glcm_differencevariance, glcm_differenceentropy, glcm_infomeas1, glcm_infomeas2
*all_glrlm* glrlm_sre, glrlm_lre, glrlm_gln, glrlm_glnn, glrlm_rln, glrlm_rlnn, glrlm_rp, glrlm_glv, glrlm_rv, glrlm_re, glrlm_lglre, glrlm_hglre, glrlm_srlgle, glrlm_srhgle, glrlm_lrlgle, glrlm_lrhgle
*all_glszm* glszm_sae, glszm_lae, glszm_gln, glszm_glnn, glszm_szn, glszm_sznn, glszm_zp, glszm_glv, glszm_zv, glszm_ze, glszm_lglze, glszm_hglze, glszm_salgle, glszm_sahgle, glszm_lalgle, glszm_lahgle
*all_gldm* gldm_sde, gldm_lde, gldm_gln, gldm_dn, gldm_dnn, gldm_glv, gldm_dv, gldm_de, gldm_lgle, gldm_hgle, gldm_sdlgle, gldm_sdhgle, gldm_ldlgle, gldm_ldhgle
*all_ngtdm* ngtdm_coarseness, ngtdm_contrast, ngtdm_busyness, ngtdm_complexity, ngtdm_strength
*all_easy* All the features except the most time-consuming GABOR, GLCM, and the group of 2D moment features
*all* All the features

Command line usage

Assuming you built the Nyxus binary as outlined below, the following parameters are available for the CLI:

Parameter Description I/O Type
--intDir Intensity image collection Input collection
--segDir Labeled image collection Input collection
--intSegMapDir Data collection of the ad-hoc intensity-to-mask file mapping Input Collection
--intSegMapFile Name of the text file containing an ad-hoc intensity-to-mask file mapping. The files are assumed to reside in corresponding intensity and label collections Input string
--features Select intensity and shape features required Input array
--filePattern To match intensity and labeled/segmented images Input string
--csvfile Save csv file as one csv file for all images or separate csv file for each image Input enum
--pixelDistance Pixel distance to calculate the neighbors touching cells Input integer
--embeddedpixelsize Consider the unit embedded in metadata, if present Input boolean
--unitLength Enter the metric for unit conversion Input string
--pixelsPerunit Enter the number of pixels per unit of the metric Input number
--outDir Output collection Output csvCollection

Example: Running Nyxus to process images of specific image channel

Suppose we need to process intensity/mask images of channel 1 :

./nyxus --features=*all_intensity*,*basic_morphology* --intDir=/home/ec2-user/data-ratbrain/int --segDir=/home/ec2-user/data-ratbrain/seg --outDir=/home/ec2-user/work/output-ratbrain --filePattern=.*_c1\.ome\.tif --csvFile=singlecsv 

Example: Running Nyxus to process specific image

Suppose we need to process intensity/mask file p1_y2_r68_c1.ome.tif :

./nyxus --features=*all_intensity*,*basic_morphology* --intDir=/home/ec2-user/data-ratbrain/int --segDir=/home/ec2-user/data-ratbrain/seg --outDir=/home/ec2-user/work/output-ratbrain --filePattern=p1_y2_r68_c1\.ome\.tif --csvFile=singlecsv 

Example: Running Nyxus to extract only intensity and basic morphology features

./nyxus --features=*all_intensity*,*basic_morphology* --intDir=/home/ec2-user/data-ratbrain/int --segDir=/home/ec2-user/data-ratbrain/seg --outDir=/home/ec2-user/work/output-ratbrain --filePattern=.* --csvFile=singlecsv 

Building from source

To build Nyxus from source, make sure you clone the Github repository with the --recurse-submodules option to clone all the necessary dependencies.

git clone --recurse-submodules https://github.com/PolusAI/nyxus.git

Nyxus relies on libTIFF as an external dependency which is readily available on most Unix-based OSs via the system package manager.

For Debian-based distros, such as Ubuntu, this can be installed via:

sudo apt install libtiff-dev

For CentOS:

sudo yum install libtiff-devel

For Mac OSX (via Homebrew):

brew install libtiff

Nyxus uses a CMake build system.

cd nyxus
mkdir build
cd build
cmake -DBUILD_CLI=ON ..
make -j4

Note that -DBUILD_CLI=ON tells Nyxus to build the command line interface as well.

Running via Docker

Running Nyxus from a local directory freshly made Docker container is a good idea. It allows one to test-run conteinerized Nyxus before it reaches Docker cloud deployment.

To search available Nyxus images run command

docker search nyxus

and you'll be shown that it's available at least via organization 'polusai'. To pull it, run

docker pull polusai/nyxus

The following command line is an example of running the dockerized feature extractor (image hash 87f3b560bbf2) with only intensity features selected:

docker run -it --mount type=bind,source=/images/collections,target=/data 87f3b560bbf2 --intDir=/data/c1/int --segDir=/data/c1/seg --outDir=/data/output --filePattern=.* --csvfile=separatecsv --features=entropy,kurtosis,skewness,max_intensity,mean_intensity,min_intensity,median,mode,standard_deviation

Install from sources and package into a Docker image

If you want to build your own Nyxus Docker container we provide a convenient shell script:

./build-docker.sh

Dependencies

Nyxus is tested with Python 3.6+. Nyxus relies on the the following packages, which are all included as submodules except for LibTIFF:

NIST Hedgehog >= 1.0.16
NIST Fastloader >= 2.1.4
pybind11 >= 2.8.1
libTIFF >= 3.6.1

WIPP Usage

Nyxus is available as plugin for WIPP.

Label image collection: The input should be a labeled image in tiled OME TIFF format (.ome.tif). Extracting morphology features, Feret diameter statistics, neighbors, hexagonality and polygonality scores requires the segmentation labels image. If extracting morphological features is not required, the label image collection can be not specified.

Intensity image collection: Extracting intensity-based features requires intensity image in tiled OME TIFF format. This is an optional parameter - the input for this parameter is required only when intensity-based features needs to be extracted.

File pattern: Enter file pattern to match the intensity and labeled/segmented images to extract features (https://pypi.org/project/filepattern/) Filepattern will sort and process files in the labeled and intensity image folders alphabetically if universal selector(.*.ome.tif) is used. If a more specific file pattern is mentioned as input, it will get matches from labeled image folder and intensity image folder based on the pattern implementation.

Pixel distance: Enter value for this parameter if neighbors touching cells needs to be calculated. The default value is 5. This parameter is optional.

Features: Comma separated list of features to be extracted. If all the features are required, then choose option all.

Csvfile: There are 2 options available under this category. Separatecsv - to save all the features extracted for each image in separate csv file. Singlecsv - to save all the features extracted from all the images in the same csv file.

Embedded pixel size: This is an optional parameter. Use this parameter only if units are present in the metadata and want to use those embedded units for the features extraction. If this option is selected, value for the length of unit and pixels per unit parameters are not required.

Length of unit: Unit name for conversion. This is also an optional parameter. This parameter will be displayed in plugin's WIPP user interface only when embedded pixel size parameter is not selected (ckrresponding check box checked).

Pixels per unit: If there is a metric mentioned in Length of unit, then Pixels per unit cannot be left blank and hence the scale per unit value must be mentioned in this parameter. This parameter will be displayed in plugin's user interface only when embedded pixel size parameter is not selected.

Note: If Embedded pixel size is not selected and values are entered in Length of unit and Pixels per unit, then the metric unit mentioned in length of unit will be considered. If Embedded pixel size, Length of unit and Pixels per unit is not selected and the unit and pixels per unit fields are left blank, the unit will be assumed to be pixels.

Output: The output is a csv file containing the value of features required.

For more information on WIPP, visit the official WIPP page.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

nyxus-0.2.3-cp39-cp39-win_amd64.whl (718.8 kB view hashes)

Uploaded CPython 3.9 Windows x86-64

nyxus-0.2.3-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (1.1 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ x86-64

nyxus-0.2.3-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl (1.2 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ i686

nyxus-0.2.3-cp39-cp39-macosx_10_15_x86_64.whl (949.2 kB view hashes)

Uploaded CPython 3.9 macOS 10.15+ x86-64

nyxus-0.2.3-cp38-cp38-win_amd64.whl (718.6 kB view hashes)

Uploaded CPython 3.8 Windows x86-64

nyxus-0.2.3-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (1.1 MB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ x86-64

nyxus-0.2.3-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl (1.2 MB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ i686

nyxus-0.2.3-cp38-cp38-macosx_10_15_x86_64.whl (949.1 kB view hashes)

Uploaded CPython 3.8 macOS 10.15+ x86-64

nyxus-0.2.3-cp37-cp37m-win_amd64.whl (739.0 kB view hashes)

Uploaded CPython 3.7m Windows x86-64

nyxus-0.2.3-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (1.1 MB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.12+ x86-64

nyxus-0.2.3-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl (1.2 MB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.12+ i686

nyxus-0.2.3-cp37-cp37m-macosx_10_15_x86_64.whl (948.7 kB view hashes)

Uploaded CPython 3.7m macOS 10.15+ x86-64

nyxus-0.2.3-cp36-cp36m-win_amd64.whl (738.9 kB view hashes)

Uploaded CPython 3.6m Windows x86-64

nyxus-0.2.3-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (1.1 MB view hashes)

Uploaded CPython 3.6m manylinux: glibc 2.12+ x86-64

nyxus-0.2.3-cp36-cp36m-manylinux_2_12_i686.manylinux2010_i686.whl (1.2 MB view hashes)

Uploaded CPython 3.6m manylinux: glibc 2.12+ i686

nyxus-0.2.3-cp36-cp36m-macosx_10_15_x86_64.whl (948.5 kB view hashes)

Uploaded CPython 3.6m macOS 10.15+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page