You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
"As an example, you can open the sample slide and annotations available here https://viewer.imaging.datacommons.cancer.gov/slim/studies/2.25.150973379448125660359643882019624926008/series/1.3.6.1.4.1.5962.99.1.1062471168.429178244.1637445043712.2.0. Note that not all of the slides in a given study contain annotations. Make sure you select the slide that has the suffix \"DX1\", as shown in the screenshot below. To enable visualization of the annotations, open \"Annotation Groups\" section in the right panel, and toggle \"Nuclei\" switch.\n",
71
+
"As an example, you can open the sample slide and annotations available here https://viewer.imaging.datacommons.cancer.gov/slim/studies/2.25.150973379448125660359643882019624926008/series/1.3.6.1.4.1.5962.99.1.1062471168.429178244.1637445043712.2.0. Note that not all of the slides in a given study contain annotations. Make sure you select the slide that has the suffix \"DX1\", as shown in the screenshot below. To enable visualization of the annotations, open \"Annotation Groups\" section in the right panel, and toggle the \"Nuclei\" switch.\n",
72
72
"\n",
73
73
"<img src=\"https://raw.githubusercontent.com/ImagingDataCommons/IDC-Tutorials/master/notebooks/pathomics/pan_cancer_annotation_slim_example.png\" alt=\"Example visualization of annotations\" width=\"1000\"/>"
"WARNING:pydicom:get_frame_offsets is deprecated and will be removed in v4.0\n"
128
+
]
129
+
}
130
+
],
119
131
"source": [
120
132
"import os\n",
121
133
"import json\n",
@@ -140,62 +152,66 @@
140
152
},
141
153
"source": [
142
154
"## Accessing DICOM ANNs from the IDC\n",
143
-
"To access and download the ANNs files, we utilize the Python package [idc-index](https://github.com/ImagingDataCommons/idc-index) that facilitates querying metadata and downloading DICOM files from the IDC. Since all available ANN documents in the IDC have a combined size of 1.82 TB - for the demonstration in this tutorial we will use only a single ANN from the TCGA-BRCA collection as an example."
155
+
"To access and download the ANNs files, we utilize the Python package [idc-index](https://github.com/ImagingDataCommons/idc-index) that facilitates querying metadata and downloading DICOM files from the IDC. Since all available ANN objects in the IDC have a combined size of 1.82 TB - for the demonstration in this tutorial we will use only a single ANN from the TCGA-BRCA collection as an example."
"idc_client.fetch_index('sm_instance_index') # fetch additional sm_instance_index containing all slide microscopy (SM) instances available in the IDC\n",
168
+
"idc_client.fetch_index('ann_index') # fetch additional ann_index containing all ANN series available in the IDC"
156
169
]
157
170
},
158
171
{
159
172
"cell_type": "code",
160
-
"execution_count": null,
173
+
"execution_count": 4,
161
174
"metadata": {
162
175
"id": "cBxXm8bQ_Hcq"
163
176
},
164
177
"outputs": [],
165
178
"source": [
166
-
"query_sr = '''\n",
179
+
"query_ann = '''\n",
167
180
"SELECT\n",
168
-
" SeriesInstanceUID,\n",
181
+
" index.SeriesInstanceUID,\n",
169
182
" StudyInstanceUID,\n",
170
183
" PatientID,\n",
171
184
" collection_id\n",
172
185
"FROM\n",
173
186
" index\n",
187
+
"JOIN\n",
188
+
" ann_index ON ann_index.SeriesInstanceUID = index.SeriesInstanceUID\n",
174
189
"WHERE\n",
175
-
" analysis_result_id = 'Pan-Cancer-Nuclei-Seg-DICOM' AND Modality = 'ANN' AND collection_id = 'tcga_luad'\n",
"DICOM ANNs extend the capabilities of [DICOM Structured Report (SR)](https://highdicom.readthedocs.io/en/latest/generalsr.html) documents as they were developed specifically for the storage of a **large number of similar annotations** and corresponding measurements (hence the full name Microscopy Simple **Bulk** Annotations). A popular example are annotations of small structures like cells or cell nuclei.\n",
241
285
"\n",
242
-
"Each ANN object contains one or more \"Annotation Groups\" consisting of many similar graphical annotations, optionally accompanied by one or several numerical measurements belonging to those graphical annotations as well as some required and some optional metadata that describe the contents of the group (see [here](https://highdicom.readthedocs.io/en/latest/package.html#highdicom.ann.AnnotationGroup) for more information).\n",
243
-
"\n",
244
-
"The following code uses the Python library [highdicom](https://github.com/ImagingDataCommons/highdicom) to extract annotation groups and corresponding measurements from a single DICOM ANN.\n",
286
+
"Each ANN object contains one or more \"Annotation Groups\" consisting of many similar graphical annotations, optionally accompanied by one or several numerical measurements belonging to those graphical annotations as well as some required and some optional metadata that describe the contents of the group. These include an annotation group identifier, a human-readable label but also coded values that describe the category and the type of the annotated structure (see [here](https://highdicom.readthedocs.io/en/latest/package.html#highdicom.ann.AnnotationGroup) for a complete documentation).\n",
245
287
"\n",
246
-
"In highdicom, the annotation data are encoded as a list of numpy arrays, each of the shape (N x D). N is the number of coordinates which depends on the graphic type, e.g. a `POINT` will have one coordinate, while a `POLYGON` has >= 3 coordinates. Coordinates are either defined in the 2D image coordinate system (D=2), or in the frame-of-reference coordinate system (D=3).\n",
247
-
"\n",
248
-
"More explanations and guidance through implementation details for ANN objects in highdicom can be found [here](https://highdicom.readthedocs.io/en/latest/ann.html#microscopy-bulk-simple-annotation-ann-objects)."
288
+
"The following code uses [highdicom](https://github.com/ImagingDataCommons/highdicom) to extract annotation groups and metadata from a single DICOM ANN. More helpful explanations and guidance through implementation details for ANN objects in highdicom can be found [here](https://highdicom.readthedocs.io/en/latest/ann.html#microscopy-bulk-simple-annotation-ann-objects)."
"Graphic type of annotations: GraphicTypeValues.POLYGON\n",
294
-
"Number of annotations: 865921\n"
343
+
"Number of annotations: 865921\n",
344
+
"Algorithm type used to generate the annotations: AnnotationGroupGenerationTypeValues.AUTOMATIC\n"
295
345
]
296
346
}
297
347
],
298
348
"source": [
349
+
"# Most essential metadata of the annotation group can be accessed as follows:\n",
299
350
"ann_group = ann_groups[0]\n",
300
-
"print(f'Label of the annotation group: {ann_group.label}')\n",
351
+
"print(f'Unique identifier of the annotation group: {ann_group.uid}')\n",
352
+
"print(f'Human-readable label of the annotation group: {ann_group.label}')\n",
353
+
"print(f'Coded label of the annotated property category: \\n{ann_group.annotated_property_category}')\n",
354
+
"print(f'Coded label of the annotated property type: \\n{ann_group.annotated_property_type}')\n",
301
355
"print(f'Graphic type of annotations: {ann_group.graphic_type}')\n",
302
-
"print(f'Number of annotations: {ann_group.number_of_annotations}')"
356
+
"print(f'Number of annotations: {ann_group.number_of_annotations}')\n",
357
+
"print(f'Algorithm type used to generate the annotations: {ann_group.algorithm_type}')"
358
+
]
359
+
},
360
+
{
361
+
"cell_type": "markdown",
362
+
"metadata": {
363
+
"id": "g-z2XnaMyIpH"
364
+
},
365
+
"source": [
366
+
"In highdicom, the graphic annotation data are encoded as a list of numpy arrays, each of the shape (N x D). N is the number of coordinates which depends on the graphic type, e.g. a `POINT` will have one coordinate, while a `POLYGON` has >= 3 coordinates. Coordinates are either defined in the 2D image coordinate system (D=2), or in the frame-of-reference coordinate system (D=3)."
"print(f'Coordinates of first annotation: {first_ann}')"
328
393
]
329
394
},
330
395
{
@@ -333,23 +398,23 @@
333
398
"id": "AfxGQ-WXNGkj"
334
399
},
335
400
"source": [
336
-
"As previously mentioned, annotations can be accompanied by one or multiple measurements. For the Pan-Cancer-Nuclei-Seg-DICOM collection these are each nuclei's area given in µm²."
401
+
"As previously mentioned, annotations can be accompanied by one or multiple measurements. In highdicom, they are returned as tuple of `(names, values, units)` each of them being a list of coded values. For the Pan-Cancer-Nuclei-Seg-DICOM collection these are each nuclei's area given in µm²."
"The resulting GeoJSON file can then be imported into other tools for viewing and analysis, such as for example [QuPath](https://qupath.github.io/). Here QuPath v.0.5.1 was used. After opening the slide, you can load annotations as GeoJSON under `File` > `Import objects from file` and adapt the visualization (e.g. changing color) in the `Annotations` pane.\n",
819
+
"The resulting GeoJSON file can then be imported into other tools for viewing and analysis, such as for example [QuPath](https://qupath.github.io/). Here QuPath v.0.5.1 was used. After opening the slide, you can load annotations as GeoJSON under `File` > `Import objects from file` and adapt the visualization (e.g. changing color) in the `Annotations` pane.\n",
755
820
"\n",
756
821
"<img src=\"https://github.com/ImagingDataCommons/IDC-Tutorials/releases/download/0.22.0/pan_cancer_annotation_qupath_example.png\" alt=\"Example visualization of annotations\" width=\"1000\"/>"
0 commit comments