Skip to content

Installation Guide

This document walks through the environment setup and installation steps required for CartLoader.

1. Dependencies

Below listed all required tools and packages for CartLoader. Instruction of how to install those tools and packages are provided in the section 2 and 4.

1.1 Required System Utilities

Confirm that these command-line programs are installed:

  • gzip
  • sort
  • bgzip
  • tabix
  • bc
  • perl

1.2 External Tools and Utilities

These packages support spatial data handling and file conversion. Several are bundled as git submodules.

Python & Related Tooling

R & related Packages:

External Tools (included as submodules)

Geospatial Utilities

Cloud & CLI Utilities

2. Setting Up the Environment using conda

We recommend isolating the project in a conda environment to avoid dependency conflicts.

2.1 Installing conda

If conda is not already available, download and install Miniconda or Anaconda.

Example installation of Miniconda3 on Linux:

1
2
3
4
5
env_dir=/path/to/your/directory/hosting/tools/      ## replace `/path/to/your/directory/hosting/tools/` with your preferred tools directory
cd $env_dir

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

2.2 Creating an Environment

Set up a fresh environment for CartLoader:

1
2
3
4
5
ENV_NAME="cart_env"   # define your environment name
PY_VERSION="3.13.1"   # define your python version

conda create -n ${ENV_NAME} python=${PY_VERSION}
conda activate ${ENV_NAME}

2.3 Install Core Dependencies

Install the core dependencies once the environment is active:

1
conda install -c conda-forge gdal aws-cli imagemagick parquet-tools r-base

3. Installing CartLoader

Clone the repository and install required Python and R packages:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cd $env_dir
git clone git@github.com:seqscope/cartloader.git
cd cartloader

# Install python requirements:
pip install -r ./installation/requirements.txt

# Install R packages:
Rscript ./installation/install_r_packages.R

pip install -e ./

4. Initializing Submodules

1
2
cd $env_dir/cartloader
git submodule update --init --recursive

4.1 Installing spatula

Install spatula with its dependencies from the submodules directory:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cd ${env_dir}/cartloader/submodules/spatula

cd submodules
bash -x build.sh
cd ..

## build spatula
mkdir build
cd build
cmake ..
make

4.2 Installing punkst

Install the punkst toolkit to use FICTURE (Si et al., Nature Methods 2024).

Please follow the punkst installation guide.

What are FICTURE and punkst?

FICTURE is a segmentation-free method that infers latent spatial factors—coherent spatial patterns of gene activity—that correspond to underlying transcriptional programs or tissue structures. These factors can then be projected back to the pixel level. Although FICTURE is built on a Latent Dirichlet Allocation (LDA) framework by default, it is also compatible with clustering outputs from external tools like Seurat for pixel-level projection.

The punkst toolkit is a streamlined implementation of FICTURE, designed for improved computational efficiency and scalability while producing results equivalent to the original.

4.3 Installing tippecanoe

1
2
3
4
5
6
7
8
9
cd ${env_dir}/cartloader/submodules/tippecanoe
make -j

## Choose one of the following installation options:
# (1) System-wide installation (requires root access):
make install

# (2) Local installation (no root access): specify a custom PREFIX
make install PREFIX=${env_dir}/cartloader/submodules/tippecanoe/  # Replace with your desired installation path

4.4 Installing go-pmtiles

An easy way to install go-pmtiles is to download a release from the official website and decompress it. This provides a pmtiles binary ready for use.

Here is an example of its installation:

1
2
3
cd ${env_dir}
wget https://github.com/protomaps/go-pmtiles/releases/download/v1.28.0/go-pmtiles_1.28.0_Linux_x86_64.tar.gz
tar -zxvf go-pmtiles_1.28.0_Linux_x86_64.tar.gz

4.5 Installing ImageMagick

Skip this step if ImageMagick was already installed via conda in Section 2.3.

1
2
3
4
cd ${env_dir}/cartloader/submodules/ImageMagick
./configure     # Alternatively, run `./configure --prefix=${env_dir}/cartloader/submodules/ImageMagick`.
make 
make install

5. Verifying the Installation

Run the following command to verify cartloader and all dependecies

1
2
3
4
5
6
7
8
9
# activate your environment if you did not
# replace the $ENV_NAME with your environment name if you did not define it before
conda activate ${ENV_NAME} 

# verify the installation of cartloader
python -c "import cartloader; print('cartloader installed successfully!')"

# verify all dependencies
python ./installation/check_dependencies.py