Skip to content

Installation Guide

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

1. Dependencies

Before installing CartLoader, make sure the tools below are present on your system.

1.1 Required System Utilities

Confirm that these command-line programs are installed:

  • gzip
  • sort
  • bgzip
  • tabix

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
conda create -n ENV_NAME python=3.13.1   # choose the environment name and Python version that suits your workflow
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 ./requirements.txt

# Install R packages:
Rscript ./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 that the package loads correctly:

1
python -c "import cartloader; print('cartloader installed successfully!')"