Tools · Custom Modeling

Target Rescorer

Learn a target-specific score from Vina, GNINA, Boltz-2, MM-GBSA and PLIP signals on your measured compounds, and see which signals predict activity

On this page

Prices, workflows, and method papers Open in the app

Run it from the API

Submit with Submit a job and the job_type below. Price it first with Estimate job reservation cost: submitting reserves that amount from your wallet, and the charge settles at the actual runtime.

Target Rescorer Training `train-rescorer`

Job type: train-rescorer
Hardware: cpu (default)
Typical runtime: 10 min on CPU

Payload

Payload fields
Field	Type	Description
`model_name`required	`string`	Limits: `min length 1`
`model_description`	`string`	Free-text description stored with the trained model.
`tags[]`	`string[]`	Labels stored with the trained model.
`unit`	`string`	Unit of the targets (regression); returned with every prediction from the trained model.
`labels`	`string \| object[] \| artifactRef`	Measured labels per ligand: id_column, target_column, and optionally smiles_column and split_column. CSV/JSON rows or a closed $artifact ref (e.g. bioactivity-curate's curated table).
`features`	`string \| object[] \| artifactRef`	Precomputed signal table instead of (or alongside) upstream sources: one row per ligand keyed by id_column, numeric feature columns, and optionally the smiles / target / split columns.
`feature_columns[]`	`string[]`	Columns of 'features' to use (default: every numeric column except the id, SMILES, target and split columns). Limits: `min items 1`
`id_column`	`string`	Ligand id column of labels / features; matches upstream record ids (the docked ligand name). Default: `"ligand_id"`Limits: `min length 1`
`smiles_column`	`string`	SMILES column for ligand descriptors and scaffold / cluster splits; falls back to upstream record SMILES. Default: `"smiles"`Limits: `min length 1`
`target_column`	`string`	Measured value column (pIC50 / pKd for regression, 0/1 or a value with binary_threshold for binary). Default: `"p_activity"`Limits: `min length 1`
`split_column`	`string`	Column labelling each ligand train / val / test (split_method provided). Limits: `min length 1`
`join`	`string`	How labels meet the signals: by ligand id, by canonical SMILES (a workflow that docks a SMILES list names ligands by position), or auto (whichever matches more labelled ligands). Default: `"auto"`One of: `"auto", "id", "smiles"`
`vina_poses`	`file_object[] \| file_object`	AutoDock Vina poses (vina affinity).
`gnina_poses`	`file_object[] \| file_object`	GNINA poses (GNINA affinity and CNN score).
`surfdock_poses`	`file_object[] \| file_object`	SurfDock poses (SurfDock affinity).
`diffdock_poses`	`file_object[] \| file_object`	DiffDock poses (DiffDock confidence).
`boltz2_complexes`	`file_object[] \| file_object`	Boltz-2 co-folded complexes (affinity and confidence).
`mm_gbsa_scores`	`file_object[] \| file_object`	MM-GBSA scores table (ΔG per pose).
`plip_interactions`	`file_object[] \| file_object`	PLIP interaction tables; featurized as contact counts per residue and interaction type.
`task`	`string`	Predict a measured value (regression) or the probability that a ligand is active (binary). Default: `"regression"`One of: `"regression", "binary"`
`binary_threshold`	`number`	Binary task only: label targets >= this value as active (1). Without it, binary targets must be 0 or 1.
`algorithms[]`	`string[]`	Panel compared by cross-validation (default all for the task; gp is regression-only). One of: `"linear", "lightgbm", "gp"`Limits: `min items 1`
`monotonic`	`boolean`	Constrain the linear model and LightGBM so a better docking score never lowers the prediction. Default: `true`
`descriptors`	`boolean`	Add ligand descriptors (heavy atoms, rotatable bonds, logP, ...) to correct for size bias. Default: `true`
`fingerprints`	`boolean`	Add Morgan count fingerprints of the ligand. Default: `false`
`delta_learning`	`boolean`	Regression only: learn y - a * delta_base (robust at small n). Default: `false`
`delta_base`	`string`	Signal column the Δ-learning baseline uses (default vina_affinity_kcal_mol). Limits: `min length 1`
`pose_aggregation`	`string`	Per-ligand signal from its best pose, or the mean of its top_k poses. Default: `"best"`One of: `"best", "mean_top_k"`
`top_k`	`integer`	Poses averaged by pose_aggregation mean_top_k. Default: `3`Limits: `≥ 1, ≤ 20`
`selection_metric`	`string`	Cross-validation metric that picks the winner (regression default spearman; binary default roc_auc). One of: `"spearman", "rmse", "mae", "r2", "roc_auc", "pr_auc", "ef1", "ef5", "bedroc"`
`split_method`	`string`	Fold assignment: scaffold (Bemis-Murcko groups), cluster (Butina on Morgan fingerprints at Tanimoto 0.4), random, or provided. Default: `"scaffold"`One of: `"scaffold", "cluster", "random", "provided"`
`cv_folds`	`integer`	Cross-validation folds; out-of-fold predictions carry the headline metrics. Default: `5`Limits: `≥ 3, ≤ 10`
`test_size`	`number`	Fraction held out as a test set (0 uses out-of-fold predictions only). Default: `0`Limits: `≥ 0, ≤ 0.5`
`random_seed`	`integer`	Seed for the folds and models; drawn and recorded when omitted. Limits: `≥ 0`

File fields take {"name": "x.pdb", "content_b64": "…"} or a stored artifact, {"$artifact": {"id": "art-…", "port": "…"}}. Files are up to 25 MiB each.

Example

from cognichem_client import CogniChem

client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
payload = {
    "model_name": "mr912-rescorer-tiny",
    "features": [
        {
            "ligand_id": "lig-001",
            "smiles": "CCO",
            "vina_affinity_kcal_mol": -8.56,
            "gnina_affinity_kcal_mol": -8.8,
            "gnina_cnn_score": 0.547,
            "p_activity": 6.65,
        },
        {
            "ligand_id": "lig-002",
            "smiles": "CCCO",
            "vina_affinity_kcal_mol": -7.13,
            "gnina_affinity_kcal_mol": -6.25,
            "gnina_cnn_score": 0.644,
            "p_activity": 6.53,
        },
        {
            "ligand_id": "lig-003",
            "smiles": "CCCCO",
            "vina_affinity_kcal_mol": -8.58,
            "gnina_affinity_kcal_mol": -9.2,
            "gnina_cnn_score": 0.631,
            "p_activity": 6.51,
        },
        {
            "ligand_id": "lig-004",
            "smiles": "CCCCCO",
            "vina_affinity_kcal_mol": -6.27,
            "gnina_affinity_kcal_mol": -6.42,
            "gnina_cnn_score": 0.601,
            "p_activity": 5.62,
        },
        {
            "ligand_id": "lig-005",
            "smiles": "CC(C)O",
            "vina_affinity_kcal_mol": -5.02,
            "gnina_affinity_kcal_mol": -5.37,
            "gnina_cnn_score": 0.134,
            "p_activity": 4.78,
        },
        "… 35 more",
    ],
    "task": "regression",
    "split_method": "scaffold",
    "cv_folds": 3,
    "random_seed": 7,
}

estimate = client.jobs.estimate(job_type="train-rescorer", payload=payload, resource="cpu")
print(f"Reserves ${estimate.cost:.2f}")

job = client.jobs.submit(
    job_name="my-train-rescorer-run",
    job_type="train-rescorer",
    payload=payload,
    resource="cpu",
)
status = client.jobs.wait(job.process_id)
if status.status == "completed":
    client.jobs.result(job.process_id, save_path=".")

curl -X POST "https://api.cognichem.com/api/v1/jobs/submit" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "job_name": "my-train-rescorer-run",
  "job_type": "train-rescorer",
  "payload": {
    "model_name": "mr912-rescorer-tiny",
    "features": [
      {
        "ligand_id": "lig-001",
        "smiles": "CCO",
        "vina_affinity_kcal_mol": -8.56,
        "gnina_affinity_kcal_mol": -8.8,
        "gnina_cnn_score": 0.547,
        "p_activity": 6.65
      },
      {
        "ligand_id": "lig-002",
        "smiles": "CCCO",
        "vina_affinity_kcal_mol": -7.13,
        "gnina_affinity_kcal_mol": -6.25,
        "gnina_cnn_score": 0.644,
        "p_activity": 6.53
      },
      {
        "ligand_id": "lig-003",
        "smiles": "CCCCO",
        "vina_affinity_kcal_mol": -8.58,
        "gnina_affinity_kcal_mol": -9.2,
        "gnina_cnn_score": 0.631,
        "p_activity": 6.51
      },
      {
        "ligand_id": "lig-004",
        "smiles": "CCCCCO",
        "vina_affinity_kcal_mol": -6.27,
        "gnina_affinity_kcal_mol": -6.42,
        "gnina_cnn_score": 0.601,
        "p_activity": 5.62
      },
      {
        "ligand_id": "lig-005",
        "smiles": "CC(C)O",
        "vina_affinity_kcal_mol": -5.02,
        "gnina_affinity_kcal_mol": -5.37,
        "gnina_cnn_score": 0.134,
        "p_activity": 4.78
      },
      "… 35 more"
    ],
    "task": "regression",
    "split_method": "scaffold",
    "cv_folds": 3,
    "random_seed": 7
  },
  "resource": "cpu"
}'

{
  "model_name": "mr912-rescorer-tiny",
  "features": [
    {
      "ligand_id": "lig-001",
      "smiles": "CCO",
      "vina_affinity_kcal_mol": -8.56,
      "gnina_affinity_kcal_mol": -8.8,
      "gnina_cnn_score": 0.547,
      "p_activity": 6.65
    },
    {
      "ligand_id": "lig-002",
      "smiles": "CCCO",
      "vina_affinity_kcal_mol": -7.13,
      "gnina_affinity_kcal_mol": -6.25,
      "gnina_cnn_score": 0.644,
      "p_activity": 6.53
    },
    {
      "ligand_id": "lig-003",
      "smiles": "CCCCO",
      "vina_affinity_kcal_mol": -8.58,
      "gnina_affinity_kcal_mol": -9.2,
      "gnina_cnn_score": 0.631,
      "p_activity": 6.51
    },
    {
      "ligand_id": "lig-004",
      "smiles": "CCCCCO",
      "vina_affinity_kcal_mol": -6.27,
      "gnina_affinity_kcal_mol": -6.42,
      "gnina_cnn_score": 0.601,
      "p_activity": 5.62
    },
    {
      "ligand_id": "lig-005",
      "smiles": "CC(C)O",
      "vina_affinity_kcal_mol": -5.02,
      "gnina_affinity_kcal_mol": -5.37,
      "gnina_cnn_score": 0.134,
      "p_activity": 4.78
    },
    "… 35 more"
  ],
  "task": "regression",
  "split_method": "scaffold",
  "cv_folds": 3,
  "random_seed": 7
}

Sample data from the job catalog; long values are shortened here. Each job_name must be unique among your jobs.

Workflow inputs

Structures (list) · optionalCIF, PDB
Docked poses (list) · optionalSDF
Table (list) · optionalCSV, TSV, JSON
Docked poses (list) · optionalSDF
Table (list) · optionalCSV, TSV, JSON
Table (list) · optionalCSV
Table (list) · optionalCSV
Docked poses (list) · optionalSDF
Docked poses (list) · optionalPDBQT, SDF

Workflow outputs

ArchiveZIP
TableCSV
TableCSV
TableCSV
Trained modelOPAQUE

Run it from the API

Target Rescorer Training train-rescorer

Target Rescorer Training `train-rescorer`