Package: nyxus-cuda12x
NyxusA scalable library for calculating features from intensity-label image dataOverviewNyxus 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 atRead the Docs.Getting startedFor use in python, the latest version of Nyxus can be installed via thePip package managerorConda package manager:pip install nyxusorconda install nyxus -c conda-forgeUsage is very straightforward. Givenintensitiesandlabelsfolders, Nyxus pairs up intensity-label images and extracts features from all of them. A summary of the available feature arelisted below.fromnyxusimportNyxusnyx=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:fromnyxusimportNyxusnyx=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)Thefeaturesvariable is a Pandas dataframe similar to what is shown below.mask_imageintensity_imagelabelMEANMEDIAN...GABOR_60p1_y2_r51_c0.ome.tifp1_y2_r51_c0.ome.tif145366.946887...0.8730161p1_y2_r51_c0.ome.tifp1_y2_r51_c0.ome.tif227122.827124.5...1.0000002p1_y2_r51_c0.ome.tifp1_y2_r51_c0.ome.tif334777.433659...0.9428573p1_y2_r51_c0.ome.tifp1_y2_r51_c0.ome.tif435808.236924...0.8240744p1_y2_r51_c0.ome.tifp1_y2_r51_c0.ome.tif536739.737798...0.854067........................734p5_y0_r51_c0.ome.tifp5_y0_r51_c0.ome.tif22354573.354573.3...0.980769Nyxus can also process intensity-mask pairs that are loaded as Numpy arrays using thefeaturizemethod. 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, .fromnyxusimportNyxusimportnumpyasnpnyx=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)Thefeaturesvariable is a Pandas dataframe similar to what is shown below.mask_imageintensity_imagelabelMEANMEDIAN...GABOR_60Segmentation1Intensity1145366.946887...0.8730161Segmentation1Intensity1227122.827124.5...1.0000002Segmentation1Intensity1334777.433659...0.9428573Segmentation1Intensity1435808.236924...0.824074........................14Segmentation2Intensity2654573.354573.3...0.980769Note that in this case, default names of virtual image files were provided for themask_imageandintensity_imagecolumns. To override default names 'Intensity' and 'Segmentation' appearing in these columns, the optional argumentsintensity_namesandlabel_namesare 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)Thefeaturesvariable will now use the custom names, as shown belowmask_imageintensity_imagelabelMEANMEDIAN...GABOR_60seg1int1145366.946887...0.8730161seg1int1227122.827124.5...1.0000002seg1int1334777.433659...0.9428573seg1int1435808.236924...0.824074........................14seg2int2654573.354573.3...0.980769For more information on all of the available options and features, check outthe documentation.Nyxus can also bebuilt from sourceand used from the command line, or via a pre-built Docker container.Getting and setting parameters of NyxusAll parameters to configure Nyxus are available to set within the constructor. These parameters can also be updated after the object is created using theset_paramsmethod. 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 thecoarse_gray_depthto 256 and thegabor_f0parameter to 0.1, the following can be done:fromnyxusimportNyxusnyx=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, theget_paramsmethod 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,fromnyxusimportNyxusnyx=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,fromnyxusimportNyxusnyx=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}Using Arrow for feature resultsNyxus 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, useoutput_type="arrowipc"oroutput_type="parquet"inNyxus.featurize*calls.
Optionally, anoutput_pathargument can be passed to specify the location of the output file. For example,fromnyxusimportNyxusimportnumpyasnpintens=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.arrowThis functionality is also available in the through the command line using the flag--outputType. If this flag is set to--outputType=arrowipcthen the results will be written to an Arrow IPC file in the output directory and--outputType=parquetwill write to a Parquet file.Available featuresThe 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 tiledOME 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 momentsNyxus feature codeDescriptionINTEGRATED_INTENSITYIntegrated intensity of the region of interest (ROI)MEAN, MAX, MEDIAN, STANDARD_DEVIATION, MODEMean/max/median/stddev/mode intensity value of the ROISKEWNESS, KURTOSIS, HYPERSKEWNESS, HYPERFLATNESShigher standardized momentsMEAN_ABSOLUTE_DEVIATIONMean absolute deviationENERGYROI energyROOT_MEAN_SQUAREDRoot of mean squared deviationENTROPYROI entropy - a measure of the amount of information in the ROIUNIFORMITYUniformity - measures how uniform the distribution of ROI intensities isUNIFORMITY_PIUPercent image uniformity, another measure of intensity distribution uniformityP01, P10, P25, P75, P90, P991%, 10%, 25%, 75%, 90%, and 99% percentiles of intensity distributionINTERQUARTILE_RANGEDistribution's interquartile rangeROBUST_MEAN_ABSOLUTE_DEVIATIONRobust mean absolute deviationMASS_DISPLACEMENTROI mass displacementAREA_PIXELS_COUNTROI area in the number of pixelsCOMPACTNESSMean squared distance of the object’s pixels from the centroid divided by the areaBBOX_YMINY-position and size of the smallest axis-aligned box containing the ROIBBOX_XMINX-position and size of the smallest axis-aligned box containing the ROIBBOX_HEIGHTHeight of the smallest axis-aligned box containing the ROIBBOX_WIDTHWidth of the smallest axis-aligned box containing the ROIMAJOR/MINOR_AXIS_LENGTH, ECCENTRICITY, ORIENTATION, ROUNDNESSInertia ellipse featuresNUM_NEIGHBORS, PERCENT_TOUCHINGThe number of neighbors bordering the ROI's perimeter and related neighbor methodsEXTENTProportion of the pixels in the bounding box that are also in the regionCONVEX_HULL_AREAArea of ROI's convex hullSOLIDITYRatio of pixels in the ROI common with its convex hull imagePERIMETERNumber of pixels in ROI's contourEQUIVALENT_DIAMETERDiameter of the circle having circumference equal to the ROI's perimeterEDGE_MEAN/MAX/MIN/STDDEV_INTENSITYIntensity statistics of ROI's contour pixelsCIRCULARITYRepresents how similar a shape is to circle. Clculated based on ROI's area and its convex perimeterEROSIONS_2_VANISHNumber of erosion operations for a ROI to vanish in its axis aligned bounding boxEROSIONS_2_VANISH_COMPLEMENTNumber of erosion operations for a ROI to vanish in its convex hullFRACT_DIM_BOXCOUNT, FRACT_DIM_PERIMETERFractal dimension featuresGLCMGrey level co-occurrence Matrix featuresGLRLMGrey level run-length matrix based featuresGLDZMGrey level distance zone matrix based featuresGLSZMGrey level size zone matrix based featuresGLDMGrey level dependency matrix based featuresNGTDMNeighbouring grey tone difference matrix featuresZERNIKE2D, FRAC_AT_D, RADIAL_CV, MEAN_FRACRadial distribution featuresGABORA set of Gabor filters of varying frequencies and orientationsFor the complete list of features seeNyxus provided featuresFeature groupsApart 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 codeBelonging 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_asm, glcm_acor, glcm_cluprom, glcm_clushade, glcm_clutend, glcm_contrast, glcm_correlation, glcm_difave, glcm_difentro, glcm_difvar, glcm_dis, glcm_energy, glcm_entropy, glcm_hom1, glcm_hom2, glcm_id, glcm_idn, glcm_idm, glcm_idmn, glcm_infomeas1, glcm_infomeas2, glcm_iv, glcm_jave, glcm_je, glcm_jmax, glcm_jvar, glcm_sumaverage, glcm_sumentropy, glcm_sumvariance, glcm_variance*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 featuresCommand line usageAssuming youbuilt the Nyxus binaryas outlined below, the following parameters are available for the command line interface:ParameterDescriptionType--outputTypeOutput type for feature values (speratecsv, singlecsv, arrow, parquet). Default value: '--outputType=separatecsv'string constant--featuresString constant or comma-seperated list of constants requesting a group of features or particular feature. Default value: '--features=*ALL*'string--filePatternRegular expression to match image files in directories specified by parameters '--intDir' and '--segDir'. To match all the files, use '--filePattern=.*'string--intDirDirectory of intensity image collectionpath--outDirOutput directorypath--segDirDirectory of labeled image collectionpath--coarseGrayDepth(optional) Custom number of greyscale level bins used in texture features. Default: '--coarseGrayDepth=256'integer--glcmAngles(optional) Enabled direction angles of the GLCM feature. Superset of values: 0, 45, 90, and 135. Default: '--glcmAngles=0,45,90,135'list of integer constants--intSegMapDir(optional) Data collection of the ad-hoc intensity-to-mask file mapping. Must be used in combination with parameter '--intSegMapFile'path--intSegMapFile(optional) 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. Must be used in combination with parameter '--intSegMapDir'string--pixelDistance(optional) Number of pixels to treat ROIs within specified distance as neighbors. Default value: '--pixelDistance=5'integer--pixelsPerCentimeter(optional) Number of pixels in centimeter used by unit length-related features. Default value: 0real--ramLimit(optional) Amount of memory not to exceed by Nyxus, in megabytes. Default value: 50% of available memory. Example: '--ramLimit=2000' to use 2,000 megabytesinteger--reduceThreads(optional) Number of CPU threads used on the feature calculation step. Default: '--reduceThreads=1'integer--skiproi(optional) Skip ROIs having specified labels. Example: '--skiproi=image1.tif:2,3,4;image2.tif:45,56'string--tempDir(optional) Directory used by temporary out-of-RAM objects. Default value: system temporary directorypath--hsig(optional) Channel signature Example: "--hsig=_c" to match images whose file names have channel info starting substring '_c' like in 'p0_y1_r1_c1.ome.tiff'string--hpar(optional) Channel number that should be used as a provider of parent segments. Example: '--hpar=1'integer--hchi(optional) Channel number that should be used as a provider of child segments. Example: '--hchi=0'integer--hag(optional) Name of a method how to aggregate features of segments recognized as children of same parent segment. Valid options are 'SUM', 'MEAN', 'MIN', 'MAX', 'WMA' (weighted mean average), and 'NONE' (no aggregation, instead, same parent child segments will be laid out horizontally)string--fpimgdr(optional) Desired dynamic range of voxels of a floating point TIFF image. Example: --fpimgdr=240 makes intensities be read in range 0-240. Default value: 10e4unsigned integer--fpimgmin(optional) Minimum intensity of voxels of a floating point TIFF image. Default value: 0.0real--fpimgdr(optional) Maximum intensity of voxels of a floating point TIFF image. Default value: 1.0realExamplesExample 1:Running Nyxus to process images of specific image channelSuppose 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=singlecsvExample 2:Running Nyxus to process specific imageSuppose 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=singlecsvExample 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=singlecsvExample 4:Skipping specified ROIs while extracting featuresSuppose 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=singlecsvAs a result, the default feature extraction result produced without option --skiproi looking likemask_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.1300242    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.9347864    p0_y1_r1_c0.tif  p0_y1_r1_c0.tif      5   -1.072111
..          ...             ...           ...      ...will start looking likemask_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=singlecsvNote 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 methodblacklist_roi(string)called before a call of methodfeaturize...(), for example, labels 15, 16, and 17 can be globally blacklisted as follows:fromnyxusimportNyxusnyx=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:fromnyxusimportNyxusnyx=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 methodsclear_roi_blacklist()androi_blacklist_get_summary().Nested ROIsHierarchical 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 postprocessingnyxus --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=WMAAs 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.csvwhere features of the detected child ROIs are laid next to their parent ROIs on same lines and auxiliary file<imagename>_nested_relations.csvserving as a relational table of  parent and child ROI labels within parent ROI channel image<imagename>.Nested features Python APIThe nested features functionality can also be utilized in Python using theNestedclass innyxus. TheNestedclass
contains two methods,find_relationsandfeaturize.Thefind_relationsmethod 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. Thefind_relationmethod
returns a Pandas DataFrame containing a mapping between parent ROIs and the respective child ROIs.Thefeaturizemethod 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 functionsfromnyxusimportNyxus,Nestedimportnumpyasnpint_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',lambdax: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 isImageParent_LabelChild_Label0/path/to/image72651/path/to/image71662/path/to/image70643/path/to/image68614/path/to/image6765and the aggregated DataFrame isGABOR_0GABOR_1GABOR_2...summeanminnanmeansummeanminnanmeansummean...label...124.0102270.6669510.0000000.66695119.0962620.5304520.0016450.53045217.0373450.473260...213.3741700.4458060.0873390.4458067.2791870.2426400.0750000.2426406.3905290.213018...35.9417830.1980590.0000000.1980593.3641490.1121380.0000000.1121382.4264090.080880...413.4287730.5595320.0000000.55953212.0219380.5009140.0087720.5009149.9389150.414121...56.5357220.1815480.0000000.1815481.8334630.0509300.0000000.0509302.0830230.057862...Example 8:Without aggregate functionsfromnyxusimportNyxus,Nestedimportnumpyasnpint_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 thefeaturizeresult becomesGABOR_0...Child_Label12345678910...label...10.666951NaNNaNNaNNaNNaNNaNNaNNaNNaN...2NaN0.445806NaNNaNNaNNaNNaNNaNNaNNaN...3NaNNaN0.198059NaNNaNNaNNaNNaNNaNNaN...4NaNNaNNaN0.559532NaNNaNNaNNaNNaNNaN...5NaNNaNNaNNaN0.181548NaNNaNNaNNaNNaN...Building from sourceNyxus usesCMakeas the build system and needs aC++17supported compiler to build from the source.DependenciesTo 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, zlibZarr Support: z5, xtensor, nlohman_json, blosc, zlibDicom Support: dcmtk, fmjpeg, zlibApache Arrow Support: arrow-cpp, pyarrowPython Interface: pybind11These packages also have underlying dependencies and at times, these dependency resolution may appear challenging. We prefercondato help with resolving these dependencies. However, for users without access to acondaenviornment, we have also provided installation script to build and install all the dependencies exceptApache 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=ONin thecmakecommand.GPU SupportNyxus also can be build with NVIDIA GPU support. To do so, aCUDADevelopment toolkit compatible with the hostC++compiler need to be present in the system. For building with GPU support, pass-DUSEGPU=ONflag in thecmakecommand.Inside CondaTo build the command line interface, pass-DBUILD_CLI=ONin thecmakecommand.Below is an example of how to build Nyxus inside acondaenvironment on Linux.condacreate-nnyxus_buildpython=3.10
condaactivatenyxus_build
gitclonehttps://github.com/PolusAI/nyxus.gitcdnyxus
condainstallmamba-cconda-forge
mambainstall-y-cconda-forge--fileci-utils/envs/conda_cpp.txtexportNYXUS_DEP_DIR=$CONDA_PREFIXmkdirbuildcdbuild
cmake-DBUILD_CLI=ON-DALLEXTRAS=ON-DUSEGPU=ON..
make-j4To install the python package in thecondaenvironment on Linux, use the following direction.condacreate-nnyxus_buildpython=3.10
condaactivatenyxus_build
gitclonehttps://github.com/PolusAI/nyxus.gitcdnyxus
condainstallmamba-cconda-forge
mambainstall-y-cconda-forge--fileci-utils/envs/conda_cpp.txt--fileci-utils/envs/conda_py.txtexportNYXUS_DEP_DIR=$CONDA_PREFIXCMAKE_ARGS="-DUSEGPU=ON -DALLEXTRAS=ON -DPython_ROOT_DIR=$CONDA_PREFIX-DPython_FIND_VIRTUALENV=ONLY"python-mpipinstall.-vvWithout Using CondaTo build Nyxus outside of acondaenvironment, we will first need to build and install all the required and optional dependecies.ci-utils/install_prereq_windwos.batandci-utils/install_prereq_linux.shperforms the task for Windows and Linux (and Mac) respectively. These script take a--min_build yesoption to only build the minimal dependencies. Below, we provide an example for Windows OS.gitclonehttps://github.com/PolusAI/nyxus.gitcdnyxus
mkdirbuildcdbuild
..\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.--configReleasesetPATH=%PATH%;%cd%\local_install\binTo install the python package in the environment on Linux, use the following direction.python-mvirtualenvvenv
venv\Scripts\activate.bat
gitclonehttps://github.com/PolusAI/nyxus.gitcdnyxus
mkdirbuild_depcdbuild_dep
..\ci-utils\install_prereq_windows.batcd..setNYXUS_DEP_DIR=%cd%\build_dep\local_installsetCMAKE_ARGS=-DUSEGPU=ON-DALLEXTRAS=ON
python-mpipinstall.-vv
xcopy/E/I/y%NYXUS_DEP_DIR%\bin\*.dll%VIRTUAL_ENV%\lib\site-packages\nyxusNote that, in both cases, thedlls of the dependencies need to be in thePATH(for CLI) or in thesite-packageslocation (for Python package).Running via DockerRunning 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 commanddocker search nyxusand you'll be shown that it's available at least via organization 'polusai'. To pull it, rundocker pull polusai/nyxusThe 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_deviationWIPP UsageNyxus is available as plugin forWIPP.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 optionall.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 formatEmbedded 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 theofficial WIPP page.