Advanced Features

This section describes a number of advanced features that have been added to QiTissue. Most features rely on the Python interpreter that is embedded in QiTissue. These functions can be accessed via the Python menu.

Most of these are experimental and should be used with care. Some features are external functionality requiring advanced knowledge of the operating system of your computer and, in many cases, familiarity with running commands on the command line.

Advanced Registration using ASHLAR

In some instances the built-in registration capabilities in QiTissue cannot resolve registration issues. This can happen when images are very large, have large empty areas (e.g. TMAs), have stitching problems (e.g. CZI images stitched with ZEN), contain significantly damaged or degraded tissues, etc. Under such conditions the advanced registration tool, ASHLAR (https://github.com/labsyspharm/ashlar), originally developed by Jeremy Muhlich at Harvard Medical School, can provide a solution. Qi developed a set of customizations around ASHLAR to interpret OHSU-style cycif multiplex image series acquired on Zeiss Axioscan scanners and inject metadata into the resulting OME-TIFF output. More detail and the customized code can be found on: https://github.com/dsudar/ashlar/tree/rotcor_metadata

INSTALLATION INSTRUCTIONS
NOTE: tested on Linux, Mac x86 and arm64, and Windows

1. Ensure your system has the development and runtime tools needed
----> ONLY ON MAC: Open a terminal window and install Apple's XCode developer tools:

xcode-select --install

2. You can skip this step if you have a Conda installed already
----> ON LINUX and MAC: Install Mamba (the better/faster conda, see: <https://mamba.readthedocs.io/en/latest/mamba-installation.html> )
----> Open Terminal window and type:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh"
bash Mambaforge-$(uname)-$(uname -m).sh

----> ON WINDOWS: Install Anaconda (from: <https://www.anaconda.com/download> )
Follow the Anaconda installation instructions
Open Anaconda Navigator and select Environments from the left tabs
Click "Create" at the bottom to create a new environment called "ashlar" with Python package 3.10 (whichever the latest 3.10 version is)
Start the ashlar environment with the green arrow and select "Open Terminal"

3. Create a conda env and install custom ashlar, see: <https://github.com/dsudar/ashlar/tree/rotcor_metadata>
----> ON MAC or LINUX:
Make sure you have a Terminal window opened and type:

conda create -y -n ashlar python=3.10
conda activate ashlar

----> ONLY ON MAC: (needs to be done via pip upfront since there's no compatible package on condaforge)

pip install pyjnius

----> ON ALL PLATFORMS:

conda install -y -c conda-forge numpy scipy matplotlib networkx scikit-image=0.19 scikit-learn "tifffile>=2023.3.15" zarr pyjnius blessed openjdk

----> ON WINDOWS or LINUX:

pip install pylibCZIrw

----> ON MAC:

pip install https://pypi.scm.io/api/package/pylibczirw/pylibCZIrw-3.5.1-cp310-cp310-macosx109_universal2.whl#sha256=9eb427f96cf4ae855deda50164e723e4685ad69adaf04b2831e856bd2c2144d6

----> ON ALL PLATFORMS:

pip install git+https://github.com/dsudar/ashlar.git@rotcor_metadata

4. Running the czi2ashlar app
cd to the directory with the czi files
Open a Terminal window (per above) and type:

czi2ashlar -o outputfile.ome.tif file1 file2 file3 .... (you can use wildcards for the files)

NOTE 1: the OHSU naming scheme R<cyclenumber>_marker1.marker2.marker3.marker4_<otherstuff> is required
NOTE 2: if the counterstain (e.g. DAPI) is NOT the first channel, use -c chan# to indicate the channel to use for alignment, the value -1 indicates the last channel in each cycle
the resulting single outputfile.ome.tif file has all the channels and rich metadata that can be read by QiTissue and other software (e.g. QuPath)

5. Next time you want to run it
----> ON MAC AND ON LINUX:
Open a terminal window (per above) and type:

conda activate ashlar

Continue with step 4

----> ON WINDOWS:
Start Anaconda Navigator, start "ashlar" from the Environments list with "Open Terminal"
Continue with step 4

NOTE: the czi2ashlar package also contains 2 batch processing scripts which are only available on Linux (or on Mac for a)):
a) batch_czi2ashlar: a simply bash script to run czi2ashlar on multiple datasets in separate directories or combined in one directory
b) slurm_czi2ashlar: a script specifically written for the OHSU exacloud cluster which does the same as batch_czi2ashlar but runs the tasks in parallel

Controls-based Normalization

QiTissue supports a variety of internal normalization methods that normalize the measured feature values against the distribution of the dataset itself. A new set of routines based on the approach by researchers at Oregon Health & Science University and Sherbrooke University in Canada, allows normalization against the values distribution in a control dataset. These routines also incorporate auto-fluorescence background correction, correction for differences in exposure times, and the facility to execute a gating/classification workflow on a batch of datasets.

INSTALLATION

The Control Normalization package is provided as a small set of Python scripts which can be downloaded from ControlNorm Package, unzipped (on Windows right-click on the .zip file and select Extract All...; on Mac simply double-click on the .zip file), and the resulting ControlNorm folder can be dropped into Documents/QiScripts (a folder that should already exist).

INSTRUCTIONS

The ControlNorm package consists of 3 routines: 1) ExportSummaryStatistics which measures an extensive summary of statistical values from a control dataset that was acquired with the same biomarkers and processed the same as one or more experimental datasets, 2) NormalizeDataset, which processes the currently loaded dataset to yield normalized values for the measured features against the values from the control dataset from routine 1, and 3) NormProcDatasets, which allows for batch processing of a list of experimental datasets by performing the normalization step as in routine 2, optionally followed by running a saved gating/classification workflow.

The datasets (both control and experimental) must have complete data and metadata including exposure times, cycle and fluorochrome info, and auto-fluorescence channels for all fluorochromes in the "0" cycle. Data acquired with Zeiss Axioscan instruments in CZI format (ideally pre-processed with ASHLAR per above for accurate registration) meets these requirements as practiced by researchers at OHSU and Sherbrooke University.

A typical procedure consists of 2 steps:

STEP 1

Load the control dataset (typically a TMA with a large variety of normal tissues), perform all usual steps to remove artifacts, unwanted debris, areas where the tissue has dissociated, areas with poor staining, etc. Then run the segmentation step and adjust the parameters until most cells and nuclei are properly segmented. Finally, execute the ExportSummaryStatistics script from the Python menu and, when prompted, select the name and destination of the exported summary statistics file. Make note of the file name and location.

STEP 2 (for normalizing a single dataset)

Load the experimental dataset and do the same initial steps as in STEP 1 to achieve a good segmentation. Next, run the NormalizeDataset script from the Python menu; in the dialog box select the saved summary statistics file from STEP 1 and the normalization method to use. E.g. Mean and Std Dev yields the regular Z-score calculation, while Median and Quantile Range yields the Robust Z-score. The feature table will be augmented with the auto-fluorescence corrected and normalized values for most of the intensity-based features. under the Generators section. Click "Start" to execute the script.

STEP 2 (for batch processing a list of datasets)

To enable efficient batch processing, NormProcDatasets can do the normalization and/or run a workflow on the normalized dataset. Run the NormProcDatasets script from the Python menu and select the (one or more) segmented experimental datasets to be normalized against the control values using the "Add Datasets" button. Check the "Normalize using Control" checkbox and select the summary statistics and desired normalization method as above.

Optionally, elect to execute a workflow script created in the Workflow Editor on each experimental dataset after the normalization step. To use this capability, first a workflow is typically created for a gating or classification strategy on one of the datasets under investigation. Using the normalized features as inputs, create and optimize a workflow and save it from the Workflow Editor using "Save workflow script without annotations" from the upper-right drop-down menu. Make note where this workflow script is saved.

Optionally, select "Close each dataset on completion" to avoid many datasets open at the same time. After clicking "Start" each experimental dataset from the list will first be normalized against the control and then processed following the workflow script.