diff --git a/Readme.md b/Readme.md index 6edd429..6f19e01 100644 --- a/Readme.md +++ b/Readme.md @@ -1,12 +1,11 @@ # HistoQC ---- + HistoQC is an open-source quality control tool for digital pathology slides ![screenshot](https://user-images.githubusercontent.com/9681868/40330248-a39603a2-5d4c-11e8-9d16-cc13fd9e21d4.png) # Requirements ---- Tested with Python 3.7 and 3.8 Note: the DockerFile installs Python 3.8, so if your goal is reproducibility you may want to take this into account @@ -36,12 +35,27 @@ Openslide binaries will have to be installed separately as per individual o/s in The most basic docker image can be created with the included (7-line) Dockerfile. + +# Installation + +You can install HistoQC into your system by using + +```bash +git clone https://github.com/choosehappy/HistoQC.git +cd HistoQC +python -m pip install --upgrade pip # (optional) upgrade pip to newest version +pip install -r requirements.txt # (required) install pinned versions of packages +pip install . # (recommended) install HistoQC as a package +``` +Note that `pip install .` will install HistoQC as a python package in your environment. If you do not want to install HistoQC as a package, you will only be able to run HistoQC from the `HistoQC` directory. + # Basic Usage ---- + +## histoqc CLI Running the pipeline is now done via a python module: -``` +``` C:\Research\code\HistoQC>python -m histoqc --help usage: __main__.py [-h] [-o OUTDIR] [-p BASEPATH] [-c CONFIG] [-f] [-b BATCH] [-n NPROCESSES] [--symlink TARGET_DIR] @@ -70,27 +84,18 @@ optional arguments: ``` -HistoQC now has a httpd server which allows for improved result viewing, it can be accessed like so: +Installed or simply git-cloned, a typical command line for running the tool thus looks like: +```bash +python -m histoqc -c v2.1 -n 3 "*.svs" ``` -C:\Research\code\HistoQC>python -m histoqc.ui --help -usage: __main__.py [-h] [--bind ADDRESS] [--port PORT] [--deploy OUT_DIR] - [data_directory] - -positional arguments: - data_directory Specify the data directory [default:current directory] -optional arguments: - -h, --help show this help message and exit - --bind ADDRESS, -b ADDRESS - Specify alternate bind address [default: all - interfaces] - --port PORT Specify alternate port [default: 8000] - --deploy OUT_DIR Write UI to OUT_DIR +which will use 3 process to operate on all svs files using the named configuration file config_v2.1.ini from the config directory. -``` +In case of errors, HistoQC can be run with the same output directory and will begin where it left off, identifying completed images by the presence of an existing directory. -Lastly, supplied configuration files can be viewed and modified like so: +## histoqc.config CLI +Supplied configuration files can be viewed and modified like so: ``` @@ -108,36 +113,46 @@ optional arguments: ``` -If you would like, you can install HistoQC into your system by using -``` -git clone https://github.com/choosehappy/HistoQC.git -cd HistoQC -python -m pip install --upgrade pip # (optional) upgrade pip to newest version -pip install -r requirements.txt # install pinned versions of packages -pip install . +Alternatively one can specify their own modified config file using an absolute or relative filename: + +```bash +python -m histoqc.config --show light > mylight.ini +python -m histoqc -c ./mylight.ini -n 3 "*.svs" ``` -Installed or simply git-cloned, a typical command line for running the tool thus looks like: +## histoqc.ui CLI + +HistoQC now has a httpd server which allows for improved result viewing, it can be accessed like so: ``` -python -m histoqc -c v2.1 -n 3 "*.svs" -``` +C:\Research\code\HistoQC>python -m histoqc.ui --help +usage: __main__.py [-h] [--bind ADDRESS] [--port PORT] [--deploy OUT_DIR] + [data_directory] -which will use 3 process to operate on all svs files using the named configuration file config_v2.1.ini from the config directory. +positional arguments: + data_directory Specify the data directory [default:current directory] -Alternatively one can specify their own modified config file using an absolute or relative filename: +optional arguments: + -h, --help show this help message and exit + --bind ADDRESS, -b ADDRESS + Specify alternate bind address [default: all + interfaces] + --port PORT Specify alternate port [default: 8000] + --deploy OUT_DIR Write UI to OUT_DIR ``` -python -m histoqc.config --show light > mylight.ini -python -m histoqc -c ./mylight.ini -n 3 "*.svs" -``` - -Afterward completion of slide processing you can view the results in your web-browser simply by following the directions after typing: +After completion of slide processing, view results in your web-browser simply by running the following command *from within the output directory* (saved in the **histoqc_output_YYMMDD-hhmmss** format by default. See histoqc CLI -o option) +```bash +cd histoqc_output_YYMMDD-hhmmss +python -m histoqc.ui ``` -python -m histoqc.ui + +... OR set data_directory to the output directory explicitly: +```bash +python -m histoqc.ui ./histoqc_output_YYMMDD-hhmmss ``` Which will likely say something like: @@ -147,32 +162,30 @@ Serving HistoQC UI on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... ``` Allowing you to browse to http://localhost:8000/ to select your results.tsv file. - -In case of errors, HistoQC can be run with the same output directory and will begin where it left off, identifying completed images by the presence of an existing directory. This can also be done remotely, but is a bit more complex, see advanced usage. # Configuration modifications ---- + HistoQC's performance is significantly improved if you select an appropriate configuration file as a starting point and modify it to suit your specific use case. If you would like to see a list of provided config files to start you off, you can type -``` +```bash python -m histoqc.config --list ``` and then you can select one and write it to file like so for your modification and tuning: -``` +```bash python -m histoqc.config --show ihc > myconfig_ihc.ini -```` +``` # Advanced Usage ---- + See [wiki](https://github.com/choosehappy/HistoQC/wiki) @@ -184,10 +197,12 @@ Information from HistoQC users appears below: 1. the new Pannoramic 1000 scanner, objective-magnification is given as 20, when a 20x objective lense and a 2x aperture boost is used, i.e. image magnification is actually 40x. While their own CaseViewer somehow determines that a boost exists and ends up with 40x when objective-magnification in Slidedat.ini is at 20, openslide and bioformats give 20x. -1.1. When converted to svs by CaseViewer, the MPP entry in ImageDescription meta-parameter give the average of the x and y mpp. Both values are slightly different for the new P1000 and can be found in meta-parameters of svs as tiff.XResolution and YResolution (inverse values, so have to be converted, also respecting ResolutionUnit as centimeter or inch +1.1. When converted to svs by CaseViewer, the MPP entry in ImageDescription meta-parameter give the average of the x and y mpp. Both values are slightly different for the new P1000 and can be found in meta-parameters of svs as tiff.XResolution and YResolution inverse values, so have to be converted, also respecting ResolutionUnit as centimeter or inch + + # Citation ---- + If you find this software useful, please drop me a line and/or consider citing it: "HistoQC: An Open-Source Quality Control Tool for Digital Pathology Slides", Janowczyk A., Zuo R., Gilmore H., Feldman M., Madabhushi A., JCO Clinical Cancer Informatics, 2019