Datasets

Model inputs are lists of SMILES strings. For supervised prediction, add a numerical target array with shape (n_molecules, n_tasks). Dataset loaders return a SMILESDataset with data and target attributes; unlabeled datasets have target=None.

Collection statistics

Explore small-molecule and polymer datasets in the molecular dataset hub, including their original sources, licenses, quality tags, and available data.

Read the hub’s current counts or select the figure to explore its interactive map. Hugging Face entries include public and gated datasets, and some provide files instead of SMILES tables. Source rows can repeat structures and are not a count of unique molecules. Each dataset retains its own license.

Load a dataset

load_dataset reads any published dataset of the molecular dataset hub by its original name. Use list_datasets() to see the current collection and filter by domain, category, quality, or access. Files download on first use and are reused from local_dir.

from torch_molecule.datasets import list_datasets, load_dataset

list_datasets(category="adme", grade="ready")   # browse the collection

data = load_dataset("qm9", targets=["homo", "lumo", "gap"])
print(len(data.data))
print(data.target.shape)          # (n_molecules, 3)
print(data.info["targets"]["gap"]["units"])   # Hartree

Labels stay as the source reported them: missing labels are NaN (never 0), and censored values such as <10 are NaN unless include_censored=True. Datasets that cannot be redistributed are listed too; loading one raises an error that names the original source. Gated datasets (noncommercial terms) need huggingface-cli login and an accepted access request on the dataset page. Pass release="v2026.10.22" to pin a collection release.

Bring your own data

Pass SMILES directly to a model, or wrap them in SMILESDataset to use the built-in splitting tools. For an unlabeled CSV with a smiles column:

import csv
from torch_molecule.datasets import SMILESDataset

with open("data/molecule100.csv", newline="") as handle:
    smiles = [row["smiles"] for row in csv.DictReader(handle)]

data = SMILESDataset(data=smiles, target=None)

The source checkout includes data/molecule100.csv and data/polymer100.csv for small local examples. Both contain SMILES; the polymer dataset uses * attachment atoms. Check the selected model’s support for polymer inputs and attachment atoms before using it for polymer generation.

Choose a split

When the source defines a split, load it by name. A test split drops molecules that also appear in training:

train = load_dataset("moleculeace_chembl204_ki", split="train")
test = load_dataset("moleculeace_chembl204_ki", split="test")

Otherwise split the dataset yourself:

data = load_dataset("polymer_gas_permeability", targets=["CO2"])
train, validation = data.train_test_split(
    test_size=0.2,
    method="random",
    seed=42,
)

Pass train.data and train.target to fit; supply the validation data through X_val and y_val when the model supports them. Keep a separate test set for a final performance estimate. data.groups holds a structure key per row, but the splitters preserve this metadata without using it to assign rows. Random splitting assigns individual rows, so repeated structures can occur in both splits. Use scaffold or butina, or split by group yourself, when repeated measurements must stay together.

Method	Holdout strategy	Useful for
random	Randomly assign rows to each split; repeated structures may overlap	An initial baseline
scaffold	Keep Bemis–Murcko scaffold groups separate	Testing on unseen molecular scaffolds
butina	Separate clusters based on Morgan fingerprint Tanimoto similarity	Testing on different structural neighborhoods
size	Split by heavy-atom count	Testing transfer across molecular sizes

Use subsample(n=100, seed=42) for a quick local experiment. Evaluate benchmarks on the intended dataset and split rather than a debugging subset.

Loader reference

load_dataset(name, targets=None, config=None, split=None, task_values=None, include_censored=False, drop_leaked=True, local_dir='torchmol_data', release=None)

Load one table of a collection dataset as a SMILESDataset.

Parameters:

• name (str) – Dataset name from list_datasets(), for example "moleculeace_chembl204_ki".

• targets (list of str, optional) – Target columns; default all targets of the table.

• config (str, optional) – Table name; default the dataset’s first table.

• split (str, optional) – A source split ("train", "test", …). Default: all rows.

• task_values (list of str, optional) – For long-format tables (one row per measurement, with a task column such as an assay ID), the task values to load; each becomes one target column, and rows keep NaN for the other tasks. Required for long-format tables.

• include_censored (bool, default=False) – Censored labels such as <10 become NaN unless True, in which case the bound (10) is used.

• drop_leaked (bool, default=True) – When loading a non-train split, drop molecules that also appear in the source’s train split.

• release (str, optional) – Collection release tag (e.g. "v2026.10.22") for reproducible results; default the latest release. New datasets appear here as soon as the collection publishes them.

• local_dir (str)

Returns:

data holds canonical SMILES (mixture components joined with .), target is (rows, targets) with NaN for missing labels, groups holds the structure key of each row (use it to keep one molecule in one split), and info holds units, label kinds, license, original sources, and quality tags.

Return type:

SMILESDataset

list_datasets(domain=None, category=None, grade=None, access=None, license_class=None, local_dir='torchmol_data', release=None)

Summaries of datasets in the collection, filtered by any given field.

Parameters:

• domain ({"small_molecules", "polymers"}, optional)

• category (str, optional) – For example "adme", "toxicity", "thermodynamics".

• grade ({"ready", "care", "caution", "unmeasured"}, optional) – Rough data-quality grade; see dataset_info(name)["quality"] for its tags.

• access ({"public", "gated", "link"}, optional) – link datasets are not redistributed; get them from their original source.

• license_class ({"open", "share_alike", "noncommercial", "unverified"}, optional)

• release (str, optional) – Collection release tag (e.g. "v2026.10.22"); default the latest release.

• local_dir (str)

Return type:

List[dict]

dataset_info(name, local_dir='torchmol_data', release=None)

Full index entry: license, links to original sources, quality tags, tables, and targets.

Parameters:

• name (str)

• local_dir (str)

• release (str | None)

Return type:

dict

Deprecated loaders

These functions still work but call load_dataset and will be removed. Rows come from the collection’s clean tables: canonical SMILES, unparseable structures removed, identical rows collapsed.

Function	Replacement
load_qm9	load_dataset("qm9", targets=["gap"])
load_chembl2k	load_dataset("chembl2k")
load_broad6k	load_dataset("broad6k")
load_toxcast	load_dataset("toxcast")
load_admet	load_dataset("admet_ai")
load_gasperm	load_dataset("polymer_gas_permeability")
load_zinc250k	load_dataset("zinc250k", targets=[])

Dataset interface

class SMILESDataset(data, target, target_names=None, groups=None, info=<factory>)

Data class for storing molecular SMILES dataset with input and target data.

Parameters:

• data (List[str])

• target (ndarray | None)

• target_names (List[str] | None)

• groups (List[str] | None)

• info (dict)

data

Input data (e.g., list of SMILES strings)

Type:

List[str]

target

Target property values as 2D numpy array (rows=molecules, cols=targets) or None

Type:

np.ndarray | None

target_names

Name of each target column, when known

Type:

List[str] | None

groups

Structure key per row; rows with the same key are the same molecule

Type:

List[str] | None

info

Provenance, units, label kinds, and quality tags for hub datasets

Type:

dict

subsample(n, seed=0)

Draw a random subset without replacement.

Intended for local debugging and CI, not as a way to make structure- aware splits cheaper. Do not subsample a benchmark (for example QM9) because Butina is slow or memory-heavy; that changes what the split measures.

Parameters:

• n (int) – Number of molecules to keep.

• seed (int, default=0) – Random seed.

Return type:

SMILESDataset

train_test_split(test_size=0.2, method='random', seed=42, **kwargs)

Split into train and holdout SMILESDataset objects.

Parameters:

• test_size (float, default=0.2) – Requested holdout fraction.

• method ({"random", "scaffold", "butina", "size"}, default="random") – random assigns individual rows, so duplicate structures can appear in both splits. groups metadata is not used to assign rows. scaffold holds out unseen Bemis-Murcko scaffolds; butina holds out unseen Taylor-Butina clusters; size splits by heavy-atom count.

• seed (int, default=42) – Random seed (used by random).

• **kwargs – Extra options forwarded to the splitter (use_csk for scaffold, similarity_cutoff for butina, direction / mode for size).

Returns:

train, holdout – The second dataset is intended as validation data for fit.

Return type:

SMILESDataset

load_qm9 reference load_chembl2k reference load_broad6k reference load_toxcast reference load_admet reference load_gasperm reference load_zinc250k reference