Package: pathopatch
PathoPatch:Accelerating Artificial Intelligence Based Whole Slide Image Analysis with an Optimized Preprocessing PipelineInstallationClone the repository:Create a conda environment with Python 3.10.12 version and install conda requirements:conda env create -f environment.yaml -vv. You can change the environment name by editing thenametag in the environment.yaml file.
This step is necessary, as we need to installOpenslidewith binary files. This is easier with conda. Otherwise, installation fromsourceneeds to be performed and packages installed with piActivate environment:conda activate pathopatch_envOptional: cuCIMRunconda install -c rapidsai cuciminside your conda environment. This process is time consuming, so you should be patient. Also follow theirofficial guidelineif any problems occur.DevelopmentInstall pre-commit withpre-commit installUsageIn our Pre-Processing pipeline, we are able to extract quadratic patches from detected tissue areas, load annotation files (.json) and apply color normlizations. We make use of the popularOpenSlidelibrary, but extended it with theRAPIDS cuCIMframework for a speedup in patch-extraction.The CLI of the main script for patch extraction (main_extraction) is as follows:python3main_extraction.py[-h][--wsi_pathsWSI_PATHS][--wsi_filelistWSI_FILELIST][--output_pathOUTPUT_PATH][--wsi_extension{svs}][--configCONFIG][--patch_sizePATCH_SIZE][--patch_overlapPATCH_OVERLAP][--target_mppTARGET_MPP][--target_magTARGET_MAG][--downsampleDOWNSAMPLE][--levelLEVEL][--context_scales[CONTEXT_SCALES...]][--check_resolutionCHECK_RESOLUTION][--processesPROCESSES][--overwrite][--annotation_pathsANNOTATION_PATHS][--annotation_extension{json,xml}][--incomplete_annotations][--label_map_fileLABEL_MAP_FILE][--save_only_annotated_patches][--save_context_without_mask][--exclude_classesEXCLUDE_CLASSES][--store_masks][--overlapping_labels][--normalize_stains][--normalization_vector_jsonNORMALIZATION_VECTOR_JSON][--min_intersection_ratioMIN_INTERSECTION_RATIO][--tissue_annotationTISSUE_ANNOTATION][--tissue_annotation_intersection_ratioTISSUE_ANNOTATION_INTERSECTION_RATIO][--masked_otsu][--otsu_annotationOTSU_ANNOTATION][--filter_patchesFILTER_PATCHES][--apply_prefilterAPPLY_PREFILTER][--log_pathLOG_PATH][--log_level{critical,error,warning,info,debug}][--hardware_selection{cucim,openslide}][--wsi_propertiesDICT]optionalarguments:-h,--helpshowthishelpmessageandexit--wsi_pathsWSI_PATHSPathtothefolderwhereallWSIarestoredorpathtoasingleWSI-file.(default:None)--wsi_filelistWSI_FILELISTPathtoacsv-filelistwithWSIfiles(separator:`,`),ifprovidedjustthesefilesareused.MustincludefullpathstoWSIs,includingsuffixes.Canbeusedasanreplacementforthewsi_pathsoption.Ifbothareprovided,yieldsanerror.(default:None)--output_pathOUTPUT_PATHPathtothefolderwheretheresultingdatasetshouldbestored.(default:None)--wsi_extension{svs}TheextensiontypesusedfortheWSIfiles,theoptionsare:['svs'](default:None)--configCONFIGPathtoaconfigfile.TheconfigfilecanholdthesameparametersastheCLI.ParametersprovidedwiththeCLIarealwayshavingprecedenceovertheparametersintheconfigfile.(default:None)--patch_sizePATCH_SIZEThesizeofthepatchesinpixelthatwillberetrievedfromtheWSI,e.g.256for256px(default:None)--patch_overlapPATCH_OVERLAPThepercentageamountpixelsthatshouldoverlapbetweentwodifferentpatches.PleaseProvideasintegerbetween0and100,indicatingoverlapinpercentage.(default:None)--downsampleDOWNSAMPLEEachWSIlevelisdownsampledbyafactorof2,downsampleexpresseswhichkindofdownsamplingshouldbeusedwithrespecttothehighestpossibleresolution.Mediumpriority,getsoverwrittenbytarget_magifprovided,butoverwriteslevel.(default:None)--target_mppTARGET_MPPIfthisparameterisprovided,theoutputleveloftheWSIcorrespondstothelevelthatisatthetargetmicronsperpixeloftheWSI.Alternativetotarget_mag,downsapleandlevel.Highestpriority,overwritestarget_mag,downsampleandlevelifprovided.(default:None)--target_magTARGET_MAGIfthisparameterisprovided,theoutputleveloftheWSIcorrespondstothelevelthatisatthetargetmagnificationoftheWSI.Alternativetotarget_mpp,downsapleandlevel.Highpriority,justtarget_mpphasahigherpriority,overwritesdownsampleandlevelifprovided.(default:None)--levelLEVELThetilelevelforsampling,alternativetodownsample.Lowestpriority,getsoverwrittenbytarget_maganddownsampleiftheyareprovided.(default:None)--context_scales[CONTEXT_SCALES...]Definecontextscalesforcontextpatches.Contextpatchesarecenteredaroundacentralpatch.Thecontext-patchsizeisequaltothepatch-size,butdownsamplingisdifferent(default:None)--check_resolutionCHECK_RESOLUTIONIfafloatvalueissupplies,theprogramcheckswhethertheresolutionofallimagescorrespondstothegivenvalue(default:None)--processesPROCESSESThenumberofprocessestouse.(default:None)--overwriteOverwritethepatchesthathavealreadybeencreatedincasetheyalreadyexist.Removesdataset.Handlewithcare!(default:None)--annotation_pathsANNOTATION_PATHSPathtothesubfolderwheretheXML/JSONannotationsarestoredorpathtoafile(default:None)--annotation_extension{json,xml}Theextensiontypesusedfortheannotationfiles,theoptionsare:['json','xml'](default:None)--incomplete_annotationsSettoallowWSIwithoutannotationfile(default:None)--label_map_fileLABEL_MAP_FILEThepathtoajsonfilethatcontainsthemappingbetweentheannotationlabelsandsomeintegers;anexamplecanbefoundinexamples(default:None)--save_only_annotated_patchesIftrueonlypatchescontainingannotationswillbestored(default:None)--save_context_without_maskThisishelpfulforextractingpatches,thatarenotwithinamask,butneededfortheValuingVicinitySegmentationAlgorithms.Thisflagisspecificallyhelpfulifonlyfullyannotatedpatchesshouldbeextractedfromaregionofinterestandtheirmasksarestored,butalsosourroundingneighbourhoodpatchesareneeded(default:False)--exclude_classesEXCLUDE_CLASSESCanbeusedtoexcludeannotationclasses(default:None)--store_masksSettostoremasksperpatch.Defaultstofalse(default:None)--overlapping_labelsPerdefault,labels(annotations)aremutuallyexclusive.Iflabelsoverlap,theyareoverwrittenaccordingtothelabel_map.jsonordering(highestnumber=highestpriority(default:None)--normalize_stainsUsesMacenkonormalizationonaportionofthewholeslideimage(default:None)--normalization_vector_jsonNORMALIZATION_VECTOR_JSONThepathtoaJSONfilewherethenormalizationvectorsarestored(default:None)--adjust_brightnessNormalizebrightnessinabatchbyclippingto90percent.Notrecommended,butkeptforlegacyreasons(default:None)--min_intersection_ratioMIN_INTERSECTION_RATIOTheminimumintersectionbetweenthetissuemaskandthepatch.Mustbebetween0and1.0meansthatallpatchesareextracted.(default:None)--tissue_annotationTISSUE_ANNOTATIONCanbeusedtonameapolygonannotationtodeterminethetissuearea.Ifatissueannotationisprovided,noOtsu-thresholdingisperformed(default:None)--tissue_annotation_intersection_ratioTISSUE_ANNOTATION_INTERSECTION_RATIOIntersectionratiowithtissueannotation.Helpful,ifROIannotationispassed,whichshouldnotinterferewithbackgroundratio.Ifnotprovided,thedefaultmin_intersection_ratiowiththebackgroundisused.(default:None)--masked_otsuUseannotationtomaskthethumbnailbeforeotsu-thresholdingisused(default:None)--otsu_annotationOTSU_ANNOTATIONCanbeusedtonameapolygonannotationtodeterminetheareaformaskedotsuthresholding.Seperatemultiplelabelswith' '(whitespace)(default:None)--filter_patchesFILTER_PATCHESPost-extractionpatchfilteringtosortoutartefacts,markerandothernon-tissuepatcheswithaDLmodel.Timeconsuming.(default:False)--apply_prefilterAPPLY_PREFILTERPre-extractionmaskfilteringtoremovemarkerfrommaskbeforeapplyingotsu(default:False)--log_pathLOG_PATHPathwherelogfilesshouldbestored.Otherwise,logfilesarestoredintheoutputfolder(default:None)--log_level{critical,error,warning,info,debug}Setthelogginglevel.Optionsare['critical','error','warning','info','debug'](default:None)--hardware_selection{cucim,openslide}Selecthardwaredevice(justifavailable,otherwisealwayscucim).Defaultstocucim.)--wsi_propertiesWSI_PROPERTIESCanbeusedtopassthewsipropertiesmanually,butjustappliesifmetadatacannotbederivedfromOpenSlide(e.g.,for.tifffiles).Supportedkeysareslide_mppandmagnification(default:None)Label-Map:An exemplarylabel_map.jsonfile is shown below. It is important that the background label always has a 0 assigned as integer valueExample:{"Background":0,"Tissue-Annotation":1,"Tumor":2,"Stroma":3,"Necrosis":4}Precedence of Target-Magnification, Downsampling and LevelTarget_mpp has the highest priority. If all four are passed, always the target mpp is used for output. Level has the lowest priority.
Sorted by priority:Target microns per pixel: Overwrites all other selectionsTarget magnification: Overwrites downsampling and levelDownsampling: Overwrites levelLevel: Lowest priority, default used when neither target magnification nor downsampling is passedCLIA CLI is used to start the preprocessing. The entry-point is themain_extraction.pyfile. In addition to the CLI, also a configuration file can be passed viapython3pathopatcher/main_extraction.py--configpath/to/config.yamlExemplary configuration file:patch_extraction.yamlResulting Dataset StructureIn general, the folder structure for a preprocessed dataset looks like this:
The aim of pre-processing is to create one dataset per WSI in the following structure:WSI_Name
├──annotation_masks# thumbnails of extracted annotation masks│├──all_overlaid.png# all with same dimension as the thumbnail│├──tumor.png
│└──...├──context# context patches, if extracted│├──2# subfolder for each scale││├──WSI_Name_row1_col1_context_2.png
││├──WSI_Name_row2_col1_context_2.png
││└──...
│└──4││├──WSI_Name_row1_col1_context_2.png
││├──WSI_Name_row2_col1_context_2.png
││└──...
├──masks# Mask (numpy) files for each patch -> optional folder for segmentation│├──WSI_Name_row1_col1.npy
│├──WSI_Name_row2_col1.npy
│└──...
├──metadata# Metadata files for each patch│├──WSI_Name_row1_col1.yaml
│├──WSI_Name_row2_col1.yaml
│└──...
├──patches# Patches as .png files│├──WSI_Name_row1_col1.png
│├──WSI_Name_row2_col1.png
│└──...
├──thumbnails# Different kind of thumbnails│├──thumbnail_mpp_5.png
│├──thumbnail_downsample_32.png
│└──...
├──tissue_masks# Tissue mask images for checking│├──mask.png# all with same dimension as the thumbnail│├──mask_nogrid.png
│└──tissue_grid.png
├──mask.png# tissue mask with green grid├──metadata.yaml# WSI metdata for patch extraction├──patch_metadata.json# Patch metadata of WSI merged in one file└──thumbnail.png# WSI thumbnailLicensePathoPatcherbyFabian Hörst, University Hospital Essen,is licensed underCC BY-NC-SA 4.0