| Overview | Installation | Quick Start | Parameter Details | Run ImSpiRE in Python interface |
ImSpiRE is an image feature-aided spatial resolution enhancement method for the ISC spatial transcriptome. Without any additional data except a parallel histology image, ImSpiRE constructs the subspot resolution transcriptional profiles while imputing gene expression of the unmeasured tissue regions. The basic idea of ImSpiRE is that the parallel histology images (usually H&E-stained images) provide valuable information (such as cell morphology, staining intensity and texture), and ImSpiRE leverages these image-derived features to enhance resolution. For spatial transcriptomes with high-pixel-density parallel histology images, ImSpiRE-enhanced profiles can achieve single-cell resolution.
ImSpiRE is a command line tool written in Python 3.8. It is available as a docker image, which eliminates the cumbersome installation and allows for portability across different computing systems. We also provide a Python library to meet the needs of other users.
For convenience, we strongly recommend that users install ImSpiRE via the Docker platform. Docker is available on a variety of Linux platforms, macOS and Windows 10 through Docker Desktop, and as a static binary installation. You can find your preferred operating system here.
After installing Docker, you can use the command below to pull the Docker image of ImSpiRE. It will take a few minutes to download the Docker image.
$ docker pull tongjizhanglab/imspire:1.2.0You can then start a container based on this image and run ImSpiRE within it.
$ docker run -it --name `whoami`_imspire -v ~:/home tongjizhanglab/imspire:1.2.0 /bin/bashYou can type the following command within the Docker container to obtain the help information of ImSpiRE.
$ ImSpiRE -hImSpiRE has been packaged and made available on PyPI. Before you begin, make sure you have pip3 on hand. Python's package installer is pip3. If you don't have pip3, you can get it here.
Make sure your environment is ready for ImSpiRE.
$ conda create -n imspire python=3.8
$ conda activate imspire ImSpiRE and other related packages can then be installed with a single command.
$ pip3 install imspire Wait a minute and type the following command to check if ImSpiRE has been successfully installed.
$ ImSpiRE -hImSpiRE employs Python package backgroundremoverfor extracting the foreground. When you run backgroundremover for the first time, it will check to see if you have the u2net model; if not, it will download it from u2net's google drive and place the pre-trained model u2net.pth in the directory ~/.u2net, as stated here. You can also download the model from GoogleDrive by yourself and place u2net.pth in the directory ~/.u2net/.
ImSpiRE includes an image feature extraction function. However, if users want to extract image features using CellProfiler, it must be installed separately. CellProfiler 4 should be pip installable in Python 3.8+ when a number of prerequisite packages are installed. More details can be found here.
$ pip3 install cellprofiler==4.2.1CellProfiler 4.2.1 can also be installed from source code.
$ wget -O core-4.2.1.tar.gz https://github.com/CellProfiler/core/archive/refs/tags/v4.2.1.tar.gz
$ wget -O CellProfiler-4.2.1.tar.gz https://github.com/CellProfiler/CellProfiler/archive/refs/tags/v4.2.1.tar.gz
$ tar -xzvf CellProfiler-4.2.1.tar.gz
$ tar -xzvf core-4.2.1.tar.gzDue to problems with package dependencies, we recommend modifying the setup.py files of cellprofiler and cellprofiler-core to change the pyzmq==18.0.1 to pyzmq==18.1.1, as they say too here. You can now install cellprofiler-core and cellprofiler in order.
$ cd core-4.2.1
$ pip3 install .
$ cd CellProfiler-4.2.1
$ pip3 install .You may need to use the command below to add the default installation path of pip3 to your system path.
$ export PATH=~/.local/bin:$PATHThen, type the command below to check whether CellProfiler has been installed successfully.
$ cellprofiler -hWe note that you may encounter a failure to install wxPython 4.1.0 when installing CellProfiler. You can download the corresponding WHL file and then install it. As an example, for Ubuntu 18.0.4, you can install wxPython 4.1.0 with the following code.
$ wget https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-18.04/wxPython-4.1.0-cp38-cp38-linux_x86_64.whl
$ pip3 install wxPython-4.1.0-cp38-cp38-linux_x86_64.whlThe CellProfiler piplines used in ImSpiRE can be available by the following commands.
$ wget https://github.com/TongjiZhanglab/ImSpiRE/raw/master/CellProfiler_pipelines/cellprofiler_pipelines.zip
$ unzip cellprofiler_piplines.zipImSpiRE utilizes the count file in tab-delimited format or hierarchical-data format (HDF5 or H5) and the image file in TIFF format, as well as a file containing spot coordinates as input.
We provided a small test dataset containing the raw count matrix, image and spot coordinates. A CellProfiler pipeline is also included in the test dataset for users if required. You can also type the command below to download.
$ wget https://github.com/TongjiZhanglab/ImSpiRE/raw/master/test/test_data.zip
$ unzip -d test_data test_data.zipIf you install ImSpiRE via the Docker platform, you need to start a container and run ImSpiRE within it.
$ docker run -it --name `whoami`_imspire -v ~:/home tongjizhanglab/imspire:1.2.0 /bin/bash
$ cd /homeType the command below to run ImSpiRE.
$ ImSpiRE -i test_data/ -c test_data/count_matrix.tsv -s test_data/image.tif -p ST -n test_output -OIf you want to extract image features with CellProfiler, use the following command.
$ ImSpiRE -i test_data/ -c test_data/count_matrix.tsv -s test_data/image.tif -p ST -n test_output -m 2 --CellProfilerParam_Pipeline test_data/Cellprofiler_Pipeline_HE.cppipe -OThe contents of the output directory in tree format will be displayed as described below, including the ImSpiRE-enhanced resolution profile stored in Anndata h5ad file format, the text file containing patch coordinates, the spot subimages and patch subimages if CellProfiler is used to extract image features, the image features, the matrices involved in OT and other supplementary results.
PATH/ProjectName
├── ProjectName_ResolutionEnhancementResult.h5ad ## the ImSpiRE-enhanced resolution profile
├── ProjectName_PatchLocations.txt ## the text file containing patch coordinates
├── ImageResults ## the spot and patch subimages if CellProfiler is used to extract image features
│ ├── SpotImage
│ └── PatchImage
├── FeatureResults ## the image features
│ ├── SpotFeature
│ └── PatchFeature
└── SupplementaryResults ## the matrices involved in OT and other supplementary results
├── ot_C1_alpha_beta_epsilon.npy
├── ot_C2_alpha_beta_epsilon.npy
├── ot_M_alpha_beta_epsilon.npy
├── ot_T_alpha_beta_epsilon.npy
└── ...The parameter details of ImSpiRE are as follows:
usage: ImSpiRE [-h] <-i InputDir> <-c filtered_feature_bc_matrix.h5> <-s image.tif> [-n ProjectName] [-o OutputDir] [options]
ImSpiRE is an Image feature-aided Spatial Resolution Enhancenment method for in situ capturing (ISC) spatial transcriptome.
optional arguments:
-h, --help show this help message and exit
-v, --version show version number of ImSpiRE and exit
-i INPUT_DIR, --Input_Dir INPUT_DIR
This indicates the path to the directory for input datafiles. For a Visium
dataset, it is similar to the standard output format of Space Ranger,
which should contain a count file in the {Input_Dir} and a text file named
"tissue_positions_list.csv" that describes the spot locations in the
{Input_Dir}/spatial/. For a spatial transcriptomics (ST) dataset, it
should contain a count file and a text file named "pxl_pos.txt" that
describes the spot locations in the {Input_Dir}. Note that the file
"tissue_positions_list.csv" does not contain a header column, while the
file "pxl_pos.txt" includes a header column and contains two columns,
which represent the pixel coordinates of rows and columns of spots,
respectively.
-c INPUT_COUNT_FILE, --Input_Count_File INPUT_COUNT_FILE
The input count file. It would typically be
"filtered_feature_bc_matrix.h5" and "count_matrix.tsv" for 10X Visium and
ST, respectively. Note that the count file of ST platform should be tab-
delimited.
-s INPUT_SECTION_IMAGE_FILE, --Input_Section_Image_File INPUT_SECTION_IMAGE_FILE
The high-resolution tissue image, which should be a Tagged Image File
Format (TIF or TIFF) file.
-t {H&E,IF}, --Input_Image_Type {H&E,IF}
The types of staining, including Haematoxylin & Eosin (H&E) staining and
Immunofluorescence (IF) staining. DEFAULT: "H&E".
-o OUTPUT_DIR, --Output_Dir OUTPUT_DIR
The project directory, which is used to save all output files. DEFAULT:
".".
-n OUTPUT_NAME, --Output_Name OUTPUT_NAME
The project name, which is used to generate output file names as a prefix.
DEFAULT: "ImSpiRE".
-p {Visium,ST}, --Platform {Visium,ST}
The platform that generates the dataset, Visium or ST. DEFAULT: "Visium".
-m {1,2}, --Mode {1,2}
Two types of extracted image features. When this parameter is set to 1,
ImSpiRE will extract intensity and texture features of the image, which
are the objective features of the image itself. When this parameter is set
to 2, ImSpiRE will use CellProfiler to extract image features, which may
be more biologically significant. DEFAULT: 1.
-O, --Overwriting The switch of overwriting. If add the parameter "-O", ImSpiRE will
overwrite the exiting folders.
--Verbose The verbose flag. If add the parameter "--Verbose", ImSpiRE will verbose
the output.
--Random_State RANDOM_STATE
Fix the seed for reproducibility. DEFAULT: 0.
--Switch_Preprocess {ON,OFF}
The switch of basic filtering of spots and genes, ON or OFF. DEFAULT:
"ON".
--Threshold_MinCounts THRESHOLD_MINCOUNTS
The minimum number of counts required for a spot to pass filtering, which
is enabled only if "--Switch_SpotFilter" is "ON". DEFAULT: 100.
--Threshold_MaxCounts THRESHOLD_MAXCOUNTS
The maximum number of counts required for a spot to pass filtering, which
is enabled only if "--Switch_SpotFilter" is "ON". DEFAULT: 10000.
--Threshold_MitoPercent THRESHOLD_MITOPERCENT
The maximum count percent of mitochondrial genes required for a spot to
pass filtering, which is enabled only if "--Switch_SpotFilter" is "ON".
DEFAULT: 20.
--Threshold_MinSpot THRESHOLD_MINSPOT
The minimum number of spots expressed required for a gene to pass
filtering, which is enabled only if "--Switch_SpotFilter" is "ON".
DEFAULT: 10.
--ImageParam_CropSize IMAGEPARAM_CROPSIZE
The pixel size of each patch subimage. For example, "--ImageParam_CropSize
100" means each patch subimage is 100*100 pixels. DEFAULT: 100.
--ImageParam_PatchDist IMAGEPARAM_PATCHDIST
The pixel distance between adjacent patches. DEFAULT: 100.
--ImageParam_TotalChannelNumber {3,4}
The total number of channels, which is needed only if "--Input_Image_Type"
is "IF". For example, "--ImageParam_TotalChannelNumber 3" means the TIFF
file contain three channels.
--ImageParam_DAPIChannel {1,2,3,4}
The channel of the DAPI, which is needed only if "--Input_Image_Type" is
"IF". For example: "--ImageParam_DAPIChannel 1".
--ImageParam_FiducialFrameChannel {1,2,3,4}
The channel of the fiducial frame, which is needed only if "--
Input_Image_Type" is "IF". For example: "--ImageParam_FiducialFrameChannel
3".
--FeatureParam_ProcessNumber FEATUREPARAM_PROCESSNUMBER
The number of worker processes to create when extracting texture and
intensity features, which is used when "-m" is 1. DEFAULT: 8.
--FeatureParam_FeatureType {0,1,2}
This determines which type of image features to use when "-m" is 1. 0 for
both texture and intensity features, 1 for texture features only and 2 for
intensity features only. DEFAULT: 0.
--FeatureParam_ClipLimit FEATUREPARAM_CLIPLIMIT
The clipping limit, which is used when "-m" is 1. It is normalized between
0 and 1, with higher values representing more contrast. DEFAULT: 0.01.
--FeatureParam_IterCount FEATUREPARAM_ITERCOUNT
Number of iterations Grabcut image segmentation algorithm should make
before returning the result. DEFAULT: 50.
--CellProfilerParam_Pipeline CELLPROFILERPARAM_PIPELINE
The path to the CellProfiler pipline. It would be better to use different
piplines for H&E and IF samples. For H&E samples,
"Cellprofiler_Pipeline_HE.cppipe" is recommended. For IF samples,
"Cellprofiler_Pipeline_IF_C3/4.cppipe" is recommended based on the total
number of channels. In the docker image, the pipelines are stored in
"/root". You can also download them from
https://github.com/TongjiZhanglab/ImSpiRE to your own working directory.
DEFAULT: "Cellprofiler_Pipeline_HE.cppipe".
--CellProfilerParam_KernelNumber CELLPROFILERPARAM_KERNELNUMBER
This option specifies the number of kernel to use to run CellProfiler.
DEFAULT: 8.
--OptimalTransportParam_Alpha OPTIMALTRANSPORTPARAM_ALPHA
The weighting parameter between physical distance network and image
feature distance network, ranging from 0 to 1. For example, "--
OptimalTransportParam_Alpha 0.5" means ImSpiRE will equally consider the
weight of physical distance network and image feature distance network.
DEFAULT: 0.5.
--OptimalTransportParam_Beta OPTIMALTRANSPORTPARAM_BETA
The constant interpolating parameter of Fused-gromov-Wasserstein transport
ranging from 0 to 1. DEFAULT: 0.5.
--OptimalTransportParam_NumNeighbors OPTIMALTRANSPORTPARAM_NUMNEIGHBORS
The number of neighbors for nearest neighbors graph. DEFAULT: 5.
--OptimalTransportParam_Epsilon OPTIMALTRANSPORTPARAM_EPSILON
The entropic regularization term with value greater than 0. DEFAULT:
0.001.
ImSpiRE can also be used step by step in the Python interface and easily integrated into custom scripts. Here is a tutorial written using Jupyter Notebook.