Skip to content

Getting Started

This guide covers installation and three ways to compute distances between molecular datasets.

Installation

Prerequisites

  • Python 3.10 or higher
pip install themap            # core
pip install "themap[all]"     # everything (ML, protein, OTDD)

Install only the extras you need:

pip install "themap[ml]"       # molecular analysis
pip install "themap[protein]"  # protein analysis (ESM2)
pip install "themap[otdd]"     # OTDD distance computation

Install from source (development)

git clone https://github.com/HFooladi/THEMAP.git
cd THEMAP
source install.sh   # creates .venv with uv, installs dev + test extras

To reactivate the environment later:

source .venv/bin/activate

The editable equivalent of the extras above is pip install -e ".[all]" (or ".[ml]", ".[dev,test]", etc.).

Verify Installation

import themap
print(f"THEMAP version: {themap.__version__}")

Quick Start

Option 1: Command Line

The fastest way to compute distances:

themap quick datasets/ -f ecfp -m euclidean -o output/

This computes Euclidean distances between all train and test datasets using ECFP fingerprints and saves results to output/molecule_distances.csv.

Option 2: Python One-Liner

from themap import quick_distance

results = quick_distance(
    data_dir="datasets",
    output_dir="output",
    molecule_featurizer="ecfp",
    molecule_method="euclidean",
)

Option 3: Config File

For reproducible experiments, use a YAML configuration:

themap init          # generates a config.yaml template
themap run config.yaml

Or from Python:

from themap import run_pipeline

results = run_pipeline("config.yaml")

Example config.yaml:

data:
  directory: "datasets"

molecule:
  enabled: true
  featurizer: "ecfp"
  method: "euclidean"

output:
  directory: "output"
  format: "csv"

Understanding Results

The output is a CSV distance matrix with source tasks as rows and target tasks as columns:

import pandas as pd

distances = pd.read_csv("output/molecule_distances.csv", index_col=0)

# Find closest source for each target
for target in distances.columns:
    closest = distances[target].idxmin()
    dist = distances[target].min()
    print(f"{target} <- {closest} (distance: {dist:.4f})")

Lower distance values indicate more similar datasets (easier transfer learning).

Data Format

Organize your data in this structure:

datasets/
├── train/
│   ├── CHEMBL123456.jsonl.gz
│   └── ...
└── test/
    ├── CHEMBL111111.jsonl.gz
    └── ...

Each .jsonl.gz file contains molecules in JSON lines format:

{"SMILES": "CCO", "Property": 1}
{"SMILES": "CCCO", "Property": 0}

Tip

Use themap convert to convert CSV files to the required JSONL.GZ format: 

themap convert data.csv CHEMBL123456

Next Steps