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

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.

Currently, Nyxus can read image data from OME-TIFF, OME-Zarr and DICOM 2D Grayscale images. It also has a Python API to support in-memory image data via Numpy array.

The docs can be found at Read the Docs.

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

pip install nyxus

or

conda install nyxus -c conda-forge

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

from nyxus import Nyxus
nyx = Nyxus(["*ALL*"])
intensityDir = "/path/to/images/intensities/"
maskDir = "/path/to/images/labels/"
features = nyx.featurize_directory (intensityDir, maskDir)

Alternatively, Nyxus can process explicitly defined pairs of intensity-mask images thus specifying custom 1:N and M:N mapping between label and intensity image files. The following example extracts features from intensity images 'i1', 'i2', and 'i3' related with mask images 'm1' and 'm2' via a custom mapping:

from nyxus import Nyxus
nyx = Nyxus(["*ALL*"])
features = nyx.featurize_files(
    [
        "/path/to/images/intensities/i1.ome.tif", 
        "/path/to/images/intensities/i2.ome.tif",
        "/path/to/images/intensities/i3.ome.tif" 
    ], 
    [
        "/path/to/images/labels/m1.ome.tif", 
        "/path/to/images/labels/m2.ome.tif",
        "/path/to/images/labels/m2.ome.tif"
    ],
	False)

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

Nyxus can also process intensity-mask pairs that are loaded as Numpy arrays using the featurize method. This method takes in either a single pair of 2D intensity-mask pairs or a pair of 3D arrays containing 2D intensity and mask images. There is also two optional parameters to supply names to the resulting dataframe, .

from nyxus import Nyxus
import numpy as np

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

intens = np.array([
    [[1, 4, 4, 1, 1],
     [1, 4, 6, 1, 1],
     [4, 1, 6, 4, 1],
     [4, 4, 6, 4, 1]],
])

seg = np.array([
    [[1, 1, 1, 1, 1],
     [1, 1, 1, 1, 1],
     [0, 1, 1, 1, 1],
     [1, 1, 1, 1, 1]]
])

features = nyx.featurize(intens, seg)

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

Note that in this case, default names of virtual image files were provided for the mask_image and intensity_image columns. To override default names 'Intensity' and 'Segmentation' appearing in these columns, the optional arguments intensity_names and label_names are used by passing lists of names in. The length of the lists must be the same as the length of the mask and intensity arrays. The following example sets mask and intensity images in the output to desired values:

intens_names = ['int1', 'int2']
seg_names = ['seg1', 'seg2']
features = nyx.featurize(intens, seg, intens_name, seg_name)

The features variable will now use the custom names, as shown below

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.

All parameters to configure Nyxus are available to set within the constructor. These parameters can also be updated after the object is created using the set_params method. This method takes in keyword arguments where the key is a valid parameter in Nyxus and the value is the updated value for the parameter. For example, to update the coarse_gray_depth to 256 and the gabor_f0 parameter to 0.1, the following can be done:

from nyxus import Nyxus
nyx = Nyxus(["*ALL*"])
intensityDir = "/path/to/images/intensities/"
maskDir = "/path/to/images/labels/"
features = nyx.featurize_directory (intensityDir, maskDir)
nyx.set_params(coarse_gray_depth=256, gabor_f0=0.1)

A list of valid parameters is included in the documentation for this method.

To get the values of the parameters in Nyxus, the get_params method is used. If no arguments are passed to this function, then a dictionary mapping all of the variable names to the respective value is returned. For example,

from nyxus import Nyxus
nyx = Nyxus(["*ALL*"])
intensityDir = "/path/to/images/intensities/"
maskDir = "/path/to/images/labels/"
features = nyx.featurize_directory (intensityDir, maskDir)
print(nyx.get_params())

will print the dictionary

{'coarse_gray_depth': 256, 
'features': ['*ALL*'], 
'gabor_f0': 0.1, 
'gabor_freqs': [1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0], 
'gabor_gamma': 0.1, 
'gabor_kersize': 16, 
'gabor_sig2lam': 0.8, 
'gabor_theta': 45.0, 
'gabor_thold': 0.025, 
'ibsi': 0, 
'n_loader_threads': 1, 
'n_feature_calc_threads': 4, 
'neighbor_distance': 5, 
'pixels_per_micron': 1.0}

There is also the option to pass arguments to this function to only receive a subset of parameter values. The arguments should be valid parameter names as string, separated by commas. For example,

from nyxus import Nyxus
nyx = Nyxus(["*ALL*"])
intensityDir = "/path/to/images/intensities/"
maskDir = "/path/to/images/labels/"
features = nyx.featurize_directory (intensityDir, maskDir)
print(nyx.get_params('coarse_gray_depth', 'features', 'gabor_f0'))

will print the dictionary

{ 
  'coarse_gray_depth': 256, 
  'features': ['*ALL*'], 
  'gabor_f0': 0.1 
}

Nyxus provides the ability to get the results of the feature calculations in Arrow IPC and Parquet formats.

To create an Arrow IPC or Parquet file, use output_type="arrowipc" or output_type="parquet" in Nyxus.featurize* calls. Optionally, an output_path argument can be passed to specify the location of the output file. For example,

    from nyxus import Nyxus
    import numpy as np

    intens = np.array([
        [[1, 4, 4, 1, 1],
            [1, 4, 6, 1, 1],
            [4, 1, 6, 4, 1],
            [4, 4, 6, 4, 1]],
                    
        [[1, 4, 4, 1, 1],
            [1, 1, 6, 1, 1],
            [1, 1, 3, 1, 1],
            [4, 4, 6, 1, 1]],
        
        [[1, 4, 4, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 6, 1, 1],
            [1, 1, 6, 1, 1]],
        
        [[1, 4, 4, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 6, 1, 1]],
    ])

    seg = np.array([
        [[1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1]],
                    
        [[1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1],
            [0, 1, 1, 1, 1],
            [1, 1, 1, 1, 1]],
        
        [[1, 1, 1, 0, 0],
            [1, 1, 1, 1, 1],
            [1, 1, 0, 1, 1],
            [1, 1, 1, 1, 1]],
                    
        [[1, 1, 1, 0, 0],
            [1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1],
            [1, 1, 1, 1, 1]]
        
    ])

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

    arrow_file = nyx.featurize(intens, seg, output_type="arrowipc", output_path="some_path")

    print(arrow_file)

The output is:

    NyxusFeatures.arrow

This functionality is also available in the through the command line using the flag --outputType. If this flag is set to --outputType=arrowipc then the results will be written to an Arrow IPC file in the output directory and --outputType=parquet will write to a Parquet file.

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

For the complete list of features see Nyxus provided features

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:

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

Example 1: 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=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output --filePattern=.*_c1\.ome\.tif --outputType=singlecsv 

Example 2: 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=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output --filePattern=p1_y2_r68_c1\.ome\.tif --outputType=singlecsv 

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

./nyxus --features=*all_intensity*,*basic_morphology* --intDir=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output --filePattern=.* --outputType=singlecsv 

Example 4: Skipping specified ROIs while extracting features

Suppose we need to blacklist ROI labels 2 and 3 from the kurtosis feature extraction globally, in each image. The command line way to do that is using option --skiproi :

./nyxus --skiproi=2,3 --features=KURTOSIS --intDir=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output --filePattern=.* --outputType=singlecsv 

As a result, the default feature extraction result produced without option --skiproi looking like

          mask_image  intensity_image  label    KURTOSIS
0    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      1   -0.134216
1    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      2   -0.130024
2    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      3   -1.259801
3    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      4   -0.934786
4    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      5   -1.072111
..          ...             ...           ...      ...

will start looking like

          mask_image  intensity_image  label    KURTOSIS
0    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      1   -0.134216
1    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      4   -0.934786
2    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      5   -1.072111
3    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      6   -0.347741
4    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      7   -1.283468
..          ...             ...           ...      ...

Note the comma character separator   ,   in the blacklisted ROI label list.

If we need to blacklist ROI labels 15 and 16 only in image image421.tif ROI label 17 in image image422.tif, we can do it via a per-file blacklist :

./nyxus --skiproi=image421.tif:15,16;image421.tif:17 --features=KURTOSIS --intDir=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output --filePattern=.* --outputType=singlecsv 

Note the colon character   :   between the file name and backlisted labels within this file and semicolon character separator   ;   of file blacklists.

Example 5: Skipping specified ROIs while extracting features (via Python API)

The Nyxus Python API equivalent of global ROI blacklisting is implemented by method blacklist_roi(string) called before a call of method featurize...(), for example, labels 15, 16, and 17 can be globally blacklisted as follows:

from nyxus import Nyxus
nyx = Nyxus(features=["KURTOSIS"])
nyx.blacklist_roi('15,16,17')
features = nyx.featurize_directory (intensity_dir="/path/to/intensity/images", label_dir="/path/to/mask/images", file_pattern=".*")

Similarly, per-file ROI blacklists are defined in a way similar to the command line interface:

from nyxus import Nyxus
nyx = Nyxus(features=["KURTOSIS"])
nyx.blacklist_roi('p0_y1_r1_c0.ome.tif:15,16;p0_y1_r2_c0.ome.tif:17')
features = nyx.featurize_directory (intensity_dir="/path/to/intensity/images", label_dir="/path/to/mask/images", file_pattern=".*")

See also methods clear_roi_blacklist() and roi_blacklist_get_summary() .

Hierarchical ROI analysis in a form of finding ROIs nested geometrically as nested AABBs and aggregating features of child ROIs within corresponding parent is available as an optional extra step after the feature extraction of the whole image set is finished. To enable this step, all the command line options '--hsig', '--hpar', '--hchi', and '--hag' need to have non-blank valid values.

Valid aggregation options are SUM, MEAN, MIN, MAX, WMA (weighted mean average), or NONE (no aggregation).

Example 6: Processing an image set with nested ROI postprocessing

nyxus --features=*ALL_intensity* --intDir=/path/to/intensity/images --segDir=/path/to/mask/images --outDir=/path/to/output/directory --filePattern=.* --outputType=separatecsv --reduceThreads=4 --hsig=_c --hpar=1 --hchi=0 --hag=WMA 

As a result, 2 additional CSV files will be produced for each mask image whose channel number matches the value of option '--hpar': file

<imagename>_nested_features.csv

where features of the detected child ROIs are laid next to their parent ROIs on same lines and auxiliary file

<imagename>_nested_relations.csv

serving as a relational table of parent and child ROI labels within parent ROI channel image <imagename>.

The nested features functionality can also be utilized in Python using the Nested class in nyxus. The Nested class contains two methods, find_relations and featurize.

The find_relations method takes in a path to the label files, along with a child filepattern to identify the files in the child channel and a parent filepattern to match the files in the parent channel. The find_relation method returns a Pandas DataFrame containing a mapping between parent ROIs and the respective child ROIs.

The featurize method takes in the parent-child mapping along with the features of the ROIs in the child channel. If a list of aggregate functions is provided to the constructor, this method will return a pivoted DataFrame where the rows are the ROI labels and the columns are grouped by the features.

Example 7: Using aggregate functions

from nyxus import Nyxus, Nested
import numpy as np

int_path = 'path/to/intensity'
seg_path = 'path/to/segmentation'

nyx = Nyxus(['GABOR'])

child_features = nyx.featurize(int_path, seg_path, file_pattern='p[0-9]_y[0-9]_r[0-9]_c0\.ome\.tif')

nest = Nested(['sum', 'mean', 'min', ('nanmean', lambda x: np.nanmean(x))])

df = nest.find_relations(seg_path, 'p{r}_y{c}_r{z}_c1.ome.tif', 'p{r}_y{c}_r{z}_c0.ome.tif')

df2 = nest.featurize(df, features)

The parent-child map is

    Image              Parent_Label  Child_Label
    0  /path/to/image          72             65
    1  /path/to/image          71             66
    2  /path/to/image          70             64
    3  /path/to/image          68             61
    4  /path/to/image          67             65

and the aggregated DataFrame is

            GABOR_0                                  GABOR_1                                  GABOR_2              ... 
            sum        mean      min       nanmean    sum      mean       min       nanmean   sum      mean        ...
    label                                                                                                          ...                                                                                                      
     1      24.010227  0.666951  0.000000  0.666951  19.096262  0.530452  0.001645  0.530452  17.037345  0.473260  ... 
     2      13.374170  0.445806  0.087339  0.445806   7.279187  0.242640  0.075000  0.242640   6.390529  0.213018  ...  
     3       5.941783  0.198059  0.000000  0.198059   3.364149  0.112138  0.000000  0.112138   2.426409  0.080880  ...  
     4      13.428773  0.559532  0.000000  0.559532  12.021938  0.500914  0.008772  0.500914   9.938915  0.414121  ...  
     5       6.535722  0.181548  0.000000  0.181548   1.833463  0.050930  0.000000  0.050930   2.083023  0.057862  ...

Example 8: Without aggregate functions

from nyxus import Nyxus, Nested
import numpy as np

int_path = 'path/to/intensity'
seg_path = 'path/to/segmentation'

nyx = Nyxus(['GABOR'])

child_features = nyx.featurize(int_path, seg_path, file_pattern='p[0-9]_y[0-9]_r[0-9]_c0\.ome\.tif')

nest = Nested()

df = nest.find_relations(seg_path, 'p{r}_y{c}_r{z}_c1.ome.tif', 'p{r}_y{c}_r{z}_c0.ome.tif')

df2 = nest.featurize(df, features)

the parent-child map remains the same but the featurize result becomes

                     GABOR_0                                                                ...    
    Child_Label       1          2         3         4         5    6    7    8    9    10  ...    
    label                                                                                   ...
    1            0.666951       NaN       NaN       NaN       NaN  NaN  NaN  NaN  NaN  NaN  ...     
    2                 NaN  0.445806       NaN       NaN       NaN  NaN  NaN  NaN  NaN  NaN  ...     
    3                 NaN       NaN  0.198059       NaN       NaN  NaN  NaN  NaN  NaN  NaN  ...     
    4                 NaN       NaN       NaN  0.559532       NaN  NaN  NaN  NaN  NaN  NaN  ...     
    5                 NaN       NaN       NaN       NaN  0.181548  NaN  NaN  NaN  NaN  NaN  ...

Nyxus uses CMake as the build system and needs a C++17 supported compiler to build from the source.

To build Nyxus from source, several build dependencies are needed to be satisfied. These dependencies arise from Nyxus's need to read and write various data format. The dependencies are listed below.

• Tiff Support: libtiff, libdeflate, zlib
• Zarr Support: z5, xtensor, nlohman_json, blosc, zlib
• Dicom Support: dcmtk, fmjpeg, zlib
• Apache Arrow Support: arrow-cpp, pyarrow
• Python Interface: pybind11

These packages also have underlying dependencies and at times, these dependency resolution may appear challenging. We prefer conda to help with resolving these dependencies. However, for users without access to a conda enviornment, we have also provided installation script to build and install all the dependencies except Apache Arrow.

By default, Nyxus can be built with a minimal set of dependecies (Tiff support and Python interface). To build Nyxus with all the supported IO options mentioned above, pass -DALLEXTRAS=ON in the cmake command.

Nyxus also can be build with NVIDIA GPU support. To do so, a CUDA Development toolkit compatible with the host C++ compiler need to be present in the system. For building with GPU support, pass -DUSEGPU=ON flag in the cmake command.

To build the command line interface, pass -DBUILD_CLI=ON in the cmake command.

Below is an example of how to build Nyxus inside a conda environment on Linux.

conda create -n nyxus_build python=3.10
conda activate nyxus_build
git clone https://github.com/PolusAI/nyxus.git
cd nyxus
conda install mamba -c conda-forge
mamba install -y -c conda-forge --file ci-utils/envs/conda_cpp.txt 
export NYXUS_DEP_DIR=$CONDA_PREFIX
mkdir build
cd build
cmake -DBUILD_CLI=ON -DALLEXTRAS=ON  -DUSEGPU=ON ..
make -j4

To install the python package in the conda environment on Linux, use the following direction.

conda create -n nyxus_build python=3.10
conda activate nyxus_build
git clone https://github.com/PolusAI/nyxus.git
cd nyxus
conda install mamba -c conda-forge
mamba install -y -c conda-forge --file ci-utils/envs/conda_cpp.txt --file ci-utils/envs/conda_py.txt
export NYXUS_DEP_DIR=$CONDA_PREFIX
CMAKE_ARGS="-DUSEGPU=ON -DALLEXTRAS=ON -DPython_ROOT_DIR=$CONDA_PREFIX -DPython_FIND_VIRTUALENV=ONLY" python -m pip install . -vv

To build Nyxus outside of a conda environment, we will first need to build and install all the required and optional dependecies. ci-utils/install_prereq_windwos.bat and ci-utils/install_prereq_linux.sh performs the task for Windows and Linux (and Mac) respectively. These script take a --min_build yes option to only build the minimal dependencies. Below, we provide an example for Windows OS.

git clone https://github.com/PolusAI/nyxus.git
cd nyxus
mkdir build
cd build
..\ci-utils\install_prereq_windows.bat
cmake -DBUILD_CLI=ON -DUSEGPU=ON -DALLEXTRAS=ON -DCMAKE_PREFIX_PATH=.\local_install -DCMAKE_INSTALL_PREFIX=.\local_install ..
cmake --build . --config Release
set PATH=%PATH%;%cd%\local_install\bin

To install the python package in the environment on Linux, use the following direction.

python -m virtualenv venv
venv\Scripts\activate.bat
git clone https://github.com/PolusAI/nyxus.git
cd nyxus
mkdir build_dep
cd build_dep
..\ci-utils\install_prereq_windows.bat
cd ..
set NYXUS_DEP_DIR=%cd%\build_dep\local_install
set CMAKE_ARGS=-DUSEGPU=ON -DALLEXTRAS=ON
python -m pip install . -vv
xcopy /E /I /y %NYXUS_DEP_DIR%\bin\*.dll %VIRTUAL_ENV%\lib\site-packages\nyxus

Note that, in both cases, the dlls of the dependencies need to be in the PATH (for CLI) or in the site-packages location (for Python package).

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 [--gpus all] --mount type=bind,source=/images/collections,target=/data 87f3b560bbf2 --intDir=/data/c1/int --segDir=/data/c1/seg --outDir=/data/output --filePattern=.* --outputType=separatecsv --features=entropy,kurtosis,skewness,max_intensity,mean_intensity,min_intensity,median,mode,standard_deviation

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.

Outputtype: There are 4 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. Arrow - to save all the features extracted from all the images in Apache Arrow format. Parquet - to save all the features extracted from all the images in Apache Parquet format

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.