SUBSEQ.BIO
DOCS-FILTER

Filter

Post-process a completed batch of sequence or structure results by numeric metrics and keep the selected files together.

Overview

  • Shortlisting ProteinMPNN sequence designs by confidence or sequence recovery.
  • Keeping top structure predictions by confidence, pLDDT, pTM, or ipTM.
  • Applying multi-metric gates before manual review or downstream jobs.

Modes

ModeInput shapeWhen to use it
metric_filter
Metric Filter Default		 Consumes a folder or output set; useful for batches and pipeline handoffs. Copy files whose metadata satisfies all metric requirements.

Canonical Job Configuration

These are the fields exposed by the default job configuration for filter. They are also returned by GET /api/v1/program/params?program=filter and submitted as the params JSON object to POST /api/v1/job/submit.

ParameterTypeModesWhat it does
requirements
Requirements		 Repeatable group All modes All requirements must pass. Top N keeps the best N candidates for that metric.
Required; Items: 1-32
requirements.metric_name
Metric		 Text All modes overall_confidence
Required; Options: binder_ptm, complex_iplddt, complex_plddt, confidence, confidence_score, iptm, ligand_confidence, mean_confidence, mean_plddt, overall_confidence, plddt, ptm, seq_rec
requirements.requirement_type
Requirement		 Text All modes
Required; Default: Greater Than; Options: Greater Than, Less Than, Top N
requirements.value
Threshold		 Number All modes 0.5
Required; Shown when requirement_type is one of Greater Than, Less Than
requirements.top_n
N		 Integer All modes 100
Required; Minimum: 1; Shown when requirement_type is Top N
Advanced configuration fields
ParameterTypeModesWhat it does
recursive
Recursive		 Yes/no All modes Search subfolders for SubSeq seq JSON and structure files.
Default: true
copy_companions
Copy Companions		 Yes/no All modes Copy directly referenced or same-stem sidecar files for selected items.
Default: true

Outputs And Metrics

  • A filtered result folder containing selected sequence JSONs or structure files.
  • Companion sidecars and metadata when copying companions is enabled.
  • filter_summary.json with requirements, candidate counts, selected counts, warnings, and pass/fail reasons.
  • Filter does not compute new metrics; it uses numeric metrics already present in the input results.
  • Top N keeps the best N candidates for that metric after threshold requirements are applied.

Common Examples

  • ProteinMPNN shortlist: overall_confidence > 0.5, then seq_rec Top N 100.
  • Structure triage: iptm > 0.7 and plddt above a source-appropriate cutoff.
  • Boltz ranking: confidence_score Top N 25 with Copy Companions on.

Example API params

{
  "mode": "metric_filter",
  "requirements": [
    {
      "metric_name": "confidence_score",
      "requirement_type": "Top N",
      "top_n": 25
    }
  ],
  "recursive": true,
  "copy_companions": true
}

Caveats

  • Missing or non-numeric metrics fail their requirement.
  • Do not compare thresholds across programs unless the metric scale and meaning match.
  • High computational confidence is not experimental validation.

Advanced Submit

Advanced submit is still available for direct program arguments through POST /api/v1/job/submit-advanced. Prefer canonical configuration unless you need exact low-level arguments or are reproducing a known command line.

  • Advanced submit can run the filtering wrapper directly against a result folder with explicit metric rules.
  • Canonical configuration is usually clearer because it names the allowed metrics and requirement types.
curl -X POST https://subseq.bio/api/v1/job/submit \
  -H "Authorization: Bearer <api_key>" \
  -F program=filter \
  -F 'params={"mode":"metric_filter","requirements":[{"metric_name":"confidence_score","requirement_type":"Top N","top_n":25}],"recursive":true,"copy_companions":true}'

Further Reading