diff --git a/README.md b/README.md index 94f0ac79..30b29e89 100644 --- a/README.md +++ b/README.md @@ -184,12 +184,13 @@ Nyxus provides a set of pixel intensity, morphology, texture, intensity distribu | 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 +| GLCM | Grey level co-occurrence Matrix features | +| GLRLM | Grey level run-length matrix based features | +| GLDZM | Grey level distance zone matrix based features | +| GLSZM | Grey level size zone matrix based features | +| GLDM | Grey level dependency matrix based features | +| NGTDM | Neighbouring grey 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](docs/featurelist.md) @@ -224,7 +225,7 @@ Assuming you [built the Nyxus binary](#building-from-source) as outlined below, --intDir | Directory of intensity image collection | path --outDir | Output directory | path --segDir | Directory of labeled image collection | path ---coarseGrayDepth | (optional) Custom number of grayscale level bins used in texture features. Default: '--coarseGrayDepth=256' | integer +--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 diff --git a/docs/source/Math.rst b/docs/source/Math.rst index 485bfc5a..6aa6ebf9 100644 --- a/docs/source/Math.rst +++ b/docs/source/Math.rst @@ -15,6 +15,7 @@ Math formulas Math/f_glcm Math/f_gldm Math/f_glrlm + Math/f_gldzm Math/f_glszm Math/f_ngtdm Math/f_morphology diff --git a/docs/source/Math/f_gldzm.rst b/docs/source/Math/f_gldzm.rst new file mode 100644 index 00000000..65578c31 --- /dev/null +++ b/docs/source/Math/f_gldzm.rst @@ -0,0 +1,186 @@ + +Texture features / GLDZM +======================== + +The Grey Level Distance Zone Matrix (GLDZM) indicates the number of times each grey level's zones occur within a distance from the zone to the ROI border. + +A zone is a continuous set of pixels of same intensity (or "grey level"). + +The continuity is meant as a 4-connected neighbourhood. For example, the following intensity image matrix :math:`I` of 2 non-zero intensities 1 and 3 contains 4 zones of intensity 3 -- 1 single-pixel, 1 2-pixel, 1 3-pixel, and 2 4-pixel zones. + +.. math:: + + I = \begin{bmatrix} + 0 & 0 & 0 & 1 & 1 & 1 & 0\\ + 0 & 0 & \fbox{3} & 1 & \fbox{3} & 1 & 0\\ + 1 & \fbox{3} & 1 & 1 & \fbox{3} & 1 & 0\\ + 1 & \fbox{3} & 1 & 1 & \fbox{3} & \fbox{3} & 1\\ + \fbox{3} & 1 & \fbox{3} & \fbox{3} & 1 & 1 & 1\\ + \fbox{3} & 1 & \fbox{3} & \fbox{3} & 1 & 1 & 0\\ + \fbox{3} & 1 & 0 & 0 & 0 & 1 & 0 + \end{bmatrix} + +The zone's distance is the minimum of its each pixel's distance to the ROI or image border measured as the number of pixel boudaries to the first off-ROI or off-image pixel. + +Considering the following ROI image + +.. math:: + R = \begin{bmatrix} + 0 & 0 & 0 & 1 & 1 & 1 & 0\\ + 0 & 0 & 1 & 1 & 1 & 1 & 0\\ + 1 & 1 & 1 & 1 & 1 & 1 & 0\\ + 1 & 1 & 1 & 1 & 1 & 1 & 1\\ + 1 & 1 & 1 & 1 & 1 & 1 & 1\\ + 1 & 1 & 1 & 1 & 1 & 1 & 0\\ + 1 & 1 & 0 & 0 & 0 & 1 & 0 + \end{bmatrix} + +the distances of zons of intensity 3, ignoring pixels of other non-zero intensities (shown as :math:`*`), in the masked image (whose off-ROI pixels are shown as :math:`\times`) are + +.. math:: + D = \begin{bmatrix} + \times & \times & \times & * & * & * & \times \\ + \times & \times & \fbox{2} & * & \fbox{2} & * & \times \\ + * & \fbox{2} & * & * & \fbox{2} & * & \times \\ + * & \fbox{2} & * & * & \fbox{2} & \fbox{2} & * \\ + \fbox{1} & * & \fbox{2} & \fbox{2} & * & * & * \\ + \fbox{1} & * & \fbox{2} & \fbox{2} & * & * & \times \\ + \fbox{1} & * & \times & \times & \times & * & \times + \end{bmatrix} + + +The following example is an image having 5 discrete grey values masked with the above ROI mask :math:`R` : + +.. math:: + + I_2 = \begin{bmatrix} + \times & \times & \times & 4 & 4 & 4 & \times \\ + \times & \times & 3 & 1 & 3 & 4 & \times \\ + 2 & 1 & 1 & 1 & 3 & 2 & \times \\ + 4 & 4 & 2 & 2 & 3 & 3 & 1 \\ + 3 & 5 & 3 & 3 & 2 & 1 & 1 \\ + 3 & 5 & 3 & 3 & 2 & 4 & \times \\ + 3 & 1 & \times & \times & \times & 4 & \times + \end{bmatrix} + + +Its distance map :math:`D_2` is: + +.. math:: + + D_2 = \begin{bmatrix} + \times & \times & \times & 1 & 1 & 1 & \times \\ + \times & \times & 1 & 2 & 2 & 1 & \times \\ + 1 & 1 & 2 & 3 & 2 & 1 & \times \\ + 1 & 2 & 3 & 3 & 3 & 2 & 1 \\ + 1 & 2 & 2 & 2 & 2 & 2 & 1 \\ + 1 & 2 & 1 & 1 & 1 & 1 & \times \\ + 1 & 1 & \times & \times & \times & 1 & \times + \end{bmatrix} + +In a grey level distance zone matrix (GLDZM) :math:`M`, the element :math:`(x,d)` describes the number of zones in an image +with grey level :math:`x` located at distance :math:`d` from the edge of the ROI or image border. + +Applied to the example, the GLDZM :math:`M(I_2)` of image :math:`I_2` having distance matrix :math:`D_2`, is: + +.. math:: + + M(I_2)=\begin{bmatrix} + 3 & 0 & 0\\ + 3 & 0 & 1\\ + 3 & 1 & 0\\ + 2 & 0 & 0\\ + 1 & 1 & 0\end{bmatrix} + +Let +:math:`m(x,d)` be an element ofthe distance zone matrix corresponding to grey level :math:`x` and zone distance :math:`d` , + +:math:`N_g` -- the number of grey levels , + +:math:`N_d` -- the maximum zone distance, and + +:math:`N_s` -- the number of zones of any non-zero intensity. + +:math:`p(x,d)` be an element of the normalized distance zone matrix expressing the relative probability of element :math:`(x,d)`, defined as + +.. math:: + p_{x,d} = \frac{m_{x,d}}{N_s} . + +:math:`N_v` is the number of ROI image pixels. + +In addition, the marginal totals + +.. math:: + m_{x,\cdot} = m_x = \sum_d m_{x,d} + +represent the total of all zones with a given intensity :math:`x`, and + +.. math:: + m_{\cdot, d} = m_d = \sum_x m_{x,d} + +represent the total of all zones with a given distance :math:`d`. + +The following features are then defined: + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_SDE}} {\textup{Small Distance Emphasis}} = \frac{1}{N_s} \sum_d \frac{m_d}{d^2} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_LDE}} {\textup{Large Distance Emphasis}} = \frac{1}{N_s} \sum_d d^2 m_d + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_LGLE}} {\textup{Low Grey Level Emphasis}} = \frac{1}{N_s} \sum_x \frac{m_x}{x^2} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_HGLE}} {\textup{High Grey Level Emphasis}} = \frac{1}{N_s} \sum_x x^2 m_x + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_SDLGLE}} {\textup{Small Distance Low Grey Level Emphasis}} = \frac{1}{N_s} \sum_x \sum_d \frac{ m_{x,d}}{x^2 d^2} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_SDHGLE}} {\textup{Small Distance High Grey Level Emphasis}} = \frac{1}{N_s} \sum_x \sum_d \frac{x^2 m_{x,d}}{d^2} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_LDLGLE}} {\textup{Large Distance Low Grey Level Emphasis}} = \frac{1}{N_s} \sum_x \sum_d \frac{d^2 m_{x,d}}{x^2} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_LDHGLE}} {\textup{Large Distance High Grey Level Emphasis}} = \frac{1}{N_s} \sum_x \sum_d \x^2 d^2 m_{x,d} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_GLNU}} {\textup{Grey Level Non-Uniformity}} = \frac{1}{N_s} \sum_x m_x^2 + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_GLNUN}} {\textup{Grey Level Non-Uniformity Normalized}} = \frac{1}{N_s^2} \sum_x m_x^2 + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZDNU}} {\textup{Zone Distance Non-Uniformity}} = \frac{1}{N_s} \sum_d m_d^2 + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZDNUN}} {\textup{Zone Distance Non-Uniformity Normalized}} = \frac{1}{N_s^2} \sum_d m_d^2 + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZP}} {\textup{Zone Percentage}} = \frac{N_s}{N_v} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_GLM}} {\textup{Grey Level Mean}} = \mu_x = \sum_x \sum_d x p_{x,d} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_GLV}} {\textup{Grey Level Variance}} = \sum_x \sum_d \left(x - \mu_x \right)^2 p_{x,d} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZDM}} {\textup{Zone Distance Mean}} = \mu_d = \sum_x \sum_d d p_{x,d} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZDV}} {\textup{Zone Distance Variance}} = \sum_x \sum_d \left(d - \mu_d \right)^2 p_{x,d} + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_ZDE}} {\textup{Zone Distance Entropy}} = - \sum_x \sum_d p_{x,d} \textup{log}_2 ( p_{x,d} ) + +.. math:: + \underset{\mathrm{Nyxus \, code: \, GLDZM\_GLE}} {\textup{Grey Level Entropy}} = - \sum_x \sum_d p_{x,d} \textup{log}_2 ( p_{x,d} ) + + +References +---------- + +Thibault, G., Angulo, J., and Meyer, F. (2014); Advanced statistical matrices for texture characterization: application to cell classification; IEEE transactions on bio-medical engineering, 61(3):630-7. diff --git a/docs/source/featurelist.rst b/docs/source/featurelist.rst index 583927e2..f819adda 100644 --- a/docs/source/featurelist.rst +++ b/docs/source/featurelist.rst @@ -274,7 +274,7 @@ Nyxus provided features * - Nyxus feature code - Description * - GLCM_ANGULAR2NDMOMENT - - Gray Level Co-occurrence Matrix (GLCM) Features, 2nd angular moment + - Grey Level Co-occurrence Matrix (GLCM) Features, 2nd angular moment * - GLCM_CONTRAST - GLCM, Contrast * - GLCM_CORRELATION @@ -300,13 +300,13 @@ Nyxus provided features * - GLCM_INFOMEAS2 - GLCM, Informational Measure of Correlation (IMC) 2 * - GLRLM_SRE - - Gray level run-length matrix (GLRLM) based feature, Short Run Emphasis + - Grey level run-length matrix (GLRLM) based feature, Short Run Emphasis * - GLRLM_LRE - GLRLM, Long Run Emphasis * - GLRLM_GLN - - GLRLM, Gray Level Non-Uniformity + - GLRLM, Grey Level Non-Uniformity * - GLRLM_GLNN - - GLRLM, Gray Level Non-Uniformity Normalized + - GLRLM, Grey Level Non-Uniformity Normalized * - GLRLM_RLN - GLRLM, Run Length Non-Uniformity * - GLRLM_RLNN @@ -314,31 +314,67 @@ Nyxus provided features * - GLRLM_RP - GLRLM, Run Percentage * - GLRLM_GLV - - GLRLM, Gray Level Variance + - GLRLM, Grey Level Variance * - GLRLM_RV - GLRLM, Run Variance * - GLRLM_RE - GLRLM, Run Entropy * - GLRLM_LGLRE - - GLRLM, Low Gray Level Run Emphasis + - GLRLM, Low Grey Level Run Emphasis * - GLRLM_HGLRE - - GLRLM, High Gray Level Run Emphasis + - GLRLM, High Grey Level Run Emphasis * - GLRLM_SRLGLE - - GLRLM, Short Run Low Gray Level Emphasis + - GLRLM, Short Run Low Grey Level Emphasis * - GLRLM_SRHGLE - - GLRLM, Short Run High Gray Level Emphasis + - GLRLM, Short Run High Grey Level Emphasis * - GLRLM_LRLGLE - - GLRLM, Long Run Low Gray Level Emphasis + - GLRLM, Long Run Low Grey Level Emphasis * - GLRLM_LRHGLE - - GLRLM, Long Run High Gray Level Emphasis + - GLRLM, Long Run High Grey Level Emphasis + * - GLDZM_SDE + - GLDZM, Small Distance Emphasis + * - GLDZM_LDE + - GLDZM, Large Distance Emphasis + * - GLDZM_LGLE + - GLDZM, Low Grey Level Emphasis + * - GLDZM_HGLE + - GLDZM, High GreyLevel Emphasis + * - GLDZM_SDLGLE + - GLDZM, Small Distance Low Grey Level Emphasis + * - GLDZM_SDHGLE + - GLDZM, Small Distance High GreyLevel Emphasis + * - GLDZM_LDLGLE + - GLDZM, Large Distance Low Grey Level Emphasis + * - GLDZM_LDHGLE + - GLDZM, Large Distance High Grey Level Emphasis + * - GLDZM_GLNU + - GLDZM, Grey Level Non Uniformity + * - GLDZM_GLNUN + - GLDZM, Grey Level Non Uniformity Normalized + * - GLDZM_ZDNU + - GLDZM, Zone Distance Non Uniformity + * - GLDZM_ZDNUN + - GLDZM, Zone Distance Non Uniformity Normalized + * - GLDZM_ZP + - GLDZM, Zone Percentage + * - GLDZM_GLM + - GLDZM, Grey Level Mean + * - GLDZM_GLV + - GLDZM, Grey Level Variance + * - GLDZM_ZDM + - GLDZM, Zone Distance Mean + * - GLDZM_ZDV + - GLDZM, Zone Distance Variance + * - GLDZM_ZDE + - GLDZM, Zone Distance Entropy * - GLSZM_SAE - - Gray level size zone matrix (GLSZM) based feature, Small Area Emphasis + - GLDZM, Grey level size zone matrix (GLSZM) based feature, Small Area Emphasis * - GLSZM_LAE - Large Area Emphasis * - GLSZM_GLN - - Gray Level Non - Uniformity + - Grey Level Non - Uniformity * - GLSZM_GLNN - - Gray Level Non - Uniformity Normalized + - Grey Level Non - Uniformity Normalized * - GLSZM_SZN - Size - Zone Non - Uniformity * - GLSZM_SZNN @@ -346,53 +382,53 @@ Nyxus provided features * - GLSZM_ZP - Zone Percentage * - GLSZM_GLV - - Gray Level Variance + - Grey Level Variance * - GLSZM_ZV - Zone Variance * - GLSZM_ZE - Zone Entropy * - GLSZM_LGLZE - - Low Gray Level Zone Emphasis + - Low Grey Level Zone Emphasis * - GLSZM_HGLZE - - High Gray Level Zone Emphasis + - High Grey Level Zone Emphasis * - GLSZM_SALGLE - - Small Area Low Gray Level Emphasis + - Small Area Low Grey Level Emphasis * - GLSZM_SAHGLE - - Small Area High Gray Level Emphasis + - Small Area High Grey Level Emphasis * - GLSZM_LALGLE - - Large Area Low Gray Level Emphasis + - Large Area Low Grey Level Emphasis * - GLSZM_LAHGLE - - Large Area High Gray Level Emphasis + - Large Area High Grey Level Emphasis * - GLDM_SDE - - Gray level dependency matrix (GLDM) based feature, Small Dependence Emphasis(SDE) + - Grey level dependency matrix (GLDM) based feature, Small Dependence Emphasis(SDE) * - GLDM_LDE - Large Dependence Emphasis (LDE) * - GLDM_GLN - - Gray Level Non-Uniformity (GLN) + - Grey Level Non-Uniformity (GLN) * - GLDM_DN - Dependence Non-Uniformity (DN) * - GLDM_DNN - Dependence Non-Uniformity Normalized (DNN) * - GLDM_GLV - - Gray Level Variance (GLV) + - Grey Level Variance (GLV) * - GLDM_DV - Dependence Variance (DV) * - GLDM_DE - Dependence Entropy (DE) * - GLDM_LGLE - - Low Gray Level Emphasis (LGLE) + - Low Grey Level Emphasis (LGLE) * - GLDM_HGLE - - High Gray Level Emphasis (HGLE) + - High Grey Level Emphasis (HGLE) * - GLDM_SDLGLE - - Small Dependence Low Gray Level Emphasis (SDLGLE) + - Small Dependence Low Grey Level Emphasis (SDLGLE) * - GLDM_SDHGLE - - Small Dependence High Gray Level Emphasis (SDHGLE) + - Small Dependence High Grey Level Emphasis (SDHGLE) * - GLDM_LDLGLE - - Large Dependence Low Gray Level Emphasis (LDLGLE) + - Large Dependence Low Grey Level Emphasis (LDLGLE) * - GLDM_LDHGLE - - Large Dependence High Gray Level Emphasis (LDHGLE) + - Large Dependence High Grey Level Emphasis (LDHGLE) * - NGTDM_COARSENESS - - Neighbouring Gray Tone Difference Matrix (NGTDM) Features, Coarseness + - Neighbouring Grey Tone Difference Matrix (NGTDM) Features, Coarseness * - NGTDM_CONTRAST - NGTDM, Contrast * - NGTDM_BUSYNESS @@ -580,7 +616,7 @@ Nyxus provided features * - Nyxus feature code - Description * - NUM_NEIGHBORS - - The number of neighbors bordering the ROI's perimeter within proximity radius specified by command line argument --pixelDistance. (Default value of --pixelDistance is 5.) Algorithmically calculating this feature invilves solving the nearest neighbors search problem that in turn involves the proximity measure and the proximity threshold. Particularly, this plugin uses the $L\ *2$ norm measure over Cartesian space of pixel coordinates and parameter *\ --pixelDistance_ + - The number of neighbors bordering the ROI's perimeter within proximity radius specified by command line argument --pixelDistance. (Default value of --pixelDistance is 5.) Algorithmically calculating this feature invilves solving the nearest neighbors search problem that in turn involves the proximity measure and the proximity threshold. Particularly, this plugin uses the :math:`L_2` norm measure over Cartesian space of pixel coordinates and parameter --pixelDistance * - PERCENT_TOUCHING - Percent of ROI's contour pixels located at distance 0 from neighboring other ROIs's contour * - CLOSEST_NEIGHBOR1_DIST