Skip to content

residual_artifacts_and_coverage

Creates a binary mask of residual artifacts.

Parameters:

Name Type Description Default
img RGBImage

Image of a tissue.

 required
conversion ColorConversion

Conversion that describes the used staining protocol.

 required
nucleus_area int

Approximate area of a single cell nucleus in pixels.

 required
res_index int

Index of the residual channel in the used staining conversion.

 required
threshold float

Threshold that determines if a given pixel is an artifact. Currently recommended threshold value for H&E stained slides is 0.005. This value was declared emprirically and should provide a strict detection of artifacts. Depending on the match between the tissue and the expected staining protocol, slightly higher values could also provide reasonable results.

 required

Returns:

Type Description
ResidualArtifacts

Dictionary with a number of examined pixels, number of flagged pixels, and a binary mask of artifacts.
Note

The returned dictionary contains the following values:

Key Description
artifacts_per_pixel Binary mask of the detected residual artifacts.
number_of_examined_pixels Number of pixels that were evaluated by the function.
number_of_flagged_pixels Number of pixels labeled as artifacts.

Examples: 

from skimage.data import immunohistochemistry

from rationai.qc import residual_artifacts_and_coverage
from rationai.staining import StandardConversions


img = immunohistochemistry()

result = residual_artifacts_and_coverage(
    img, StandardConversions.RGB2HDR, nucleus_area=150, res_index=2, threshold=0.013
)

mask = result["artifacts_per_pixel"]  # Contains values 0 and 1
print(result["number_of_flagged_pixels"], result["number_of_examined_pixels"])

Source code in rationai/qc/residual_artifacts/residual_artifacts_and_coverage.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def residual_artifacts_and_coverage(
    img: RGBImage,
    conversion: ColorConversion,
    nucleus_area: int,
    res_index: int,
    threshold: float,
) -> ResidualArtifacts:
    """Creates a binary mask of residual artifacts.

    Args:
        img: Image of a tissue.
        conversion: Conversion that describes the used staining protocol.
        nucleus_area: Approximate area of a single cell nucleus in pixels.
        res_index: Index of the residual channel in the used staining conversion.
        threshold: Threshold that determines if a given pixel is an artifact.
            Currently recommended threshold value for H&E stained slides is `0.005`.
            This value was declared emprirically and should provide a strict
            detection of artifacts.
            Depending on the match between the tissue and the expected staining protocol,
            slightly higher values could also provide reasonable results.

    Returns:
        Dictionary with a number of examined pixels, number of flagged pixels,
            and a binary mask of artifacts.

    Note:
        The returned dictionary contains the following values:

        | Key                         | Description                                           |
        |-----------------------------|-------------------------------------------------------|
        | `artifacts_per_pixel`       | Binary mask of the detected residual artifacts.       |
        | `number_of_examined_pixels` | Number of pixels that were evaluated by the function. |
        | `number_of_flagged_pixels`  | Number of pixels labeled as artifacts.                |

    Examples:
    ```python
    from skimage.data import immunohistochemistry

    from rationai.qc import residual_artifacts_and_coverage
    from rationai.staining import StandardConversions


    img = immunohistochemistry()

    result = residual_artifacts_and_coverage(
        img, StandardConversions.RGB2HDR, nucleus_area=150, res_index=2, threshold=0.013
    )

    mask = result["artifacts_per_pixel"]  # Contains values 0 and 1
    print(result["number_of_flagged_pixels"], result["number_of_examined_pixels"])
    ```
    """
    num_examined, num_flagged, cov_heatmap = _get_debris_coverage(
        img=img,
        conv=conversion,
        nucleus_area=nucleus_area,
        res_index=res_index,
        threshold=threshold,
    )

    result: ResidualArtifacts = {
        "artifacts_per_pixel": cov_heatmap,
        "number_of_examined_pixels": num_examined,
        "number_of_flagged_pixels": num_flagged,
    }

    return result