Skip to content

Installation Guide

This is an instruction to set up the required environment, install necessary dependencies, and install cartloader.

1. Dependencies

To ensure full functionality of cartloader, the following dependencies must be installed:

1.1 System Dependencies

Ensure the following command-line tools are available on your system:

  • gzip
  • sort
  • bgzip
  • tabix

1.2 External Tools & Utilities

The following external tools and utilities are required for handling spatial data and file processing. Some of these are included as submodules within the repository.

Python & Related Packages:

External Tools (Included in submodules)

Geospatial Data Handling:

Cloud & CLI Tools:

2. Setting Up the Environment using conda

We recommended to use conda to manage dependencies efficiently and avoid conflicts.

2.1 Installing conda

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

Here is an example to install Miniconda3 on Linux.

1
2
3
4
5
env_dir=/path/to/your/directory/hosting/tools/      ## replace `/path/to/your/directory/hosting/tools/` by the path to your tool 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

Create a dedicated Conda environment for cartloader:

1
2
3
4
5
conda_env=cartenv               # replace cartenv with the name of your conda environment
python_version=3.13.1           # replace 3.13.1 with the version you prefer

conda create -n cartenv python=$python_version
conda activate cartenv

2.3 Installing Dependencies

Once inside the environment, install the required dependencies:

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

3. Installing cartloader

Clone the repository and install it:

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

pip install -e ./

# Install its requirements:
pip install -r ./requirements.txt

4. Installing 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 punkst toolkit to use FICTURE (Si et al., Nature Methods 2024).

Please following the punkst installation guide to install punkst

What is 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 the FICTURE, designed for improved computational efficiency and scalability while producing results equivalent to the original FICTURE.

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 methods to install tippecanoe:
# (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 will return a pmtiles bin file 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

If you have already installed ImageMagick when setting conda environment, skip this step.

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

To confirm the package is installed correctly, run:

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