Structural Family Classification

/ Introduction

What it does.

• Loop-centered, not sequence-centered

  Two aptamers with the same loop architecture but different stems land in the same family — capturing the structural feature that actually drives binding.

• Multi-structure suboptimal folding

  Up to 25 suboptimal folds per sequence within 4 kcal/mol of the MFE — the family the aptamer biologically samples, not just the single lowest-energy guess.

• Weak-helix dissolution merge

  Helices of ≤ 3 bp (≤ 6 paired nucleotides) are treated as part of the loop — so a real big loop chopped by a spurious 2-bp stem is recovered as one unit. Threshold is swept over 0 – 5 bp.

• Self-written motif-block classifier

  Not a clustering library and not the Aptamer Analysis Tool's engine — a from-scratch classifier. It mines short enriched k-mer cores, grows each into a consensus block, then names a family by the combination of blocks a loop carries (e.g. GCGTT+GAAGG). A member must match a block's full consensus, so background sequences stay ungrouped instead of bloating an over-broad family.

• Streams to disk, multi-core fold

  15 000 sequences × ~25 folds ≈ 375 000 folds. Folding runs one sequence per CPU core; intermediate tables are streamed to disk row-by-row, so peak RAM stays flat.

• Instant re-classify after one fold

  Folding is the slow stage. Once cached, changing the merge threshold, family-count knob (min-family), motif-mismatch tolerance, or motif-extension cutoff re-runs the classify + assign stages in seconds.

/ Pipeline

15 000 trimmed sequences
        │
        ▼  Fold  —  reuses AptaFold's seqfold / ViennaRNA suboptimals
   02_fold_predictions.csv
        │
        ▼  Loop extraction  (self-written)
   03_raw_loops.csv           dot-bracket → pair table → loops
   04_merged_loops_bp3.csv    weak-helix dissolution (≤ 3 bp)
   05_loop_map_bp3.csv        loop ↔ (seq, fold, span, ΔG)
   06_loop_corpus_bp3.fasta   de-duped loop strings + recurrence
        │
        ▼  Motif-block classifier  (self-written — the core engine)
   ·  mine enriched k-mer cores → grow consensus blocks
   ·  family = the block COMBINATION a loop carries
   ·  strict full-consensus membership; no N×N matrix
        │
        ▼  Assign + post-process  (self-written)
   ·  dual-anchor merge   — fuse families sharing a 5′ AND 3′ framework
   ·  ungrouped rescue    — recover high-read near-identical winners
   07_aptamer_family_bp3.csv        per-aptamer family
   08_family_representatives_bp3.csv  picks for validation

/ Usage

How to use it.

1. 01

   Launch & load sequencing data

   Open the GUI. Pick a FASTQ file (will be trimmed) or an already-trimmed FASTA / CSV from Aptamer Analysis Tool. Read counts are preserved if the FASTA headers carry count=N.

   

   Screenshot · 01-main-window.png

2. 02

   Configure trim, folding & family parameters

   In the four parameter panels: pick a trim mode and library length N; pick a folding engine (viennarna recommended, salt-sensitive, ~20–30× faster than alternatives); set [Na⁺] / [Mg²⁺] / [K⁺] / [Ca²⁺] and temperature to match your selection buffer; set the loop merge threshold bp (auto by default), target family count, and motif strictness.

3. 03

   Run the pipeline

   Folding (Stage 1/4) is the slow part — every sequence × fold_budget ≈ 140 constrained refolds, run in parallel across all CPU cores. Stages 2/4 (loop extraction + merge), 3/4 (motif-block classification), and 4/4 (assign + dual-anchor merge + rescue) each finish in seconds once folding is cached. The bottom-left console reports each stage's row counts and the run's headline stats (aptamers, total folds, loop corpus size, families, grouped fraction, representatives).

   

   Screenshot · 03-pipeline-complete.png

4. 04

   Review families & iterate

   The result panel renders each family in a distinct colour: highlighted bases = the family's conserved motif, gray = primer flanks, white = variable N region. Each chain card also draws the full-insert 2D secondary structure (dissolved at the merge threshold), with the conserved motif painted in the family colour. Tweak the merge bp, family count (min-family), motif-mismatch tolerance, or motif-extension cutoff and click Re-classify — the fold cache is reused, so a new family palette appears in seconds.

   

   Screenshot · 04-family-orange.png

   

5. 05

   Export representatives for wet-lab

   07_aptamer_family_bp3.csv assigns every aptamer in the pool to a family. 08_family_representatives_bp3.csv picks one representative per family (ranked by read count) — the shortlist you take into CD / ITC / FRET validation.

/ Disclaimer

Things to know.

1. Experimental — a preview build, not yet validated.

   Loop-centered family assignment is still an engineering hypothesis. Wet-lab validation (CD melting + ITC across representatives of every family from a real SELEX pool) is ongoing. The build above (v0.9.5) is a usable preview so you can try the pipeline on your own pools — but treat its families as a structure-aware shortlist for triage, not a calibrated, final answer.

2. Folding inherits AptaFold's limits; the classifier is new.

   The folding stage reuses AptaFold, so all of AptaFold's accuracy caveats (uncalibrated divalent-cation treatment, experimental engines) apply to the structures this tool classifies. The motif-block classifier, by contrast, is written from scratch for this pipeline — it is not the Aptamer Analysis Tool's k-mer / DBSCAN engine, and its loop-family assignments are themselves the experimental part still under validation.

3. Local processing, no telemetry.

   No network calls during the pipeline. Sequences, folds, loops, clusters, and family assignments all live on your machine.

4. Will be free for academic use when released.

   Free for academic / non-commercial use, on the same terms as the other Liu Lab tools (MIT-style permissive license). Please point colleagues to this page rather than redistributing the EXE, so they always get the latest preview as the pipeline is calibrated.

5. Provided as-is, without warranty.

   Family assignments are best-effort. Treat them as a structure-aware shortlist for wet-lab triage, not as final answers. Bug reports + early collaboration inquiries: [email protected].

/ Acknowledgments

Built with the lab.

• 

  Prof. Juewen Liu

  Advisor

  Professor of Chemistry at the University of Waterloo. Tier 1 Canada Research Chair in Biosensors & Bionanotechnology. Framed the loop-centered hypothesis and provides the SELEX pools and wet-lab validation pipeline that the families are tested against.

• 

  Xiaohan Zhang

  Author · Pipeline & bridge code

  Postdoctoral researcher at the University of Waterloo under Prof. Juewen Liu. Designed the loop-extraction + weak-helix-dissolution bridge, the GUI, and the family-assignment join — wiring AptaFold and the Aptamer Analysis classifier into one structure-aware pipeline.

1. Folding — reused from AptaFold

   Suboptimal folding via AptaFold's enumerate_seqfold_suboptimals() — up to 25 structures per sequence within 4 kcal/mol of the MFE, ranked by ΔG. This is the only borrowed stage; the classifier never recomputes a fold.

2. Motif-block classifier — written from scratch

   The core engine is original to this project, not the Aptamer Analysis Tool's k-mer / DBSCAN. It mines enriched k-mer cores, grows each into a consensus block, and names a family by the block combination a loop carries — with strict full-consensus membership and no N×N distance matrix. Two original post-processing passes follow: a dual-anchor merge (fuses families that share both a 5′ and a 3′ framework with a variable middle) and an ungrouped rescue (recovers near-identical high-read winners that fall below the motif-seeding threshold).

3. seqfold & ViennaRNA

   The two folding engines underneath AptaFold. ViennaRNA is the default in this pipeline for salt sensitivity and runtime; seqfold is the pure-Python fallback when ViennaRNA is unavailable.

• seqfold
• ViennaRNA
• NumPy
• matplotlib
• PySide6

The motif-block classifier itself uses only the Python standard library — no clustering dependency.

/ FAQ

Questions people actually ask.

1. How is this different from clustering sequences directly?

   Conventional post-SELEX clustering matches aptamers by full-length string similarity, which conflates "same fold, different stem" cases. This pipeline compares the loop region after weak-helix dissolution instead, so two aptamers with different stems but the same loop architecture land in the same family.

2. What is weak-helix dissolution?

   Helices of 3 base pairs or fewer are dissolved, which lets the loops flanking them merge into a single larger loop. The rationale is that very short helices are marginally stable and should not be treated as hard boundaries between loop regions.

3. Does it use only the minimum-free-energy structure?

   No — each sequence is folded into up to 25 suboptimal structures, and loops are extracted from each of them. Using a structure ensemble rather than a single MFE prediction is what makes the family assignment robust to near-degenerate folds.

4. How are the merged loops grouped?

   By a purpose-built conserved-motif classifier written from scratch for this task — not a reuse of the Aptamer Analysis Tool's k-mer / DBSCAN engine. Whole-loop string distance was rejected because it dilutes a short conserved core inside a long variable loop.

5. How far should I trust the output?

   Treat it as a structure-aware shortlist, not a conclusion. The tool is marked experimental and the loop families are still under wet-lab validation.

/ Citation

How to cite.

If this tool contributed to work you are publishing, a citation is the most useful thing you can send back — it is what keeps the tool maintained and lets other people find it.

@software{zhang_structural_family_classification_2026,
  author  = {Zhang, Xiaohan},
  title   = {Structural Family Classification},
  year    = {2026},
  version = {0.9.5},
  url     = {https://aptapilot.com/tools/structural-family-classification/}
}

/ Also in the toolkit

Other tools.

Desktop · Windows + macOS

Aptamer Analysis Tool

Sibling SELEX tool — sequence-level family clustering by k-mer + DBSCAN. This pipeline takes the loop-family question its own way, with a self-written motif classifier.

Desktop · Windows · Single-file

AptaFold

Four-cation aware DNA aptamer folding. Provides the suboptimal-folding engine this pipeline reuses.

Web · Online

K_d Fitting Tool

Quadratic binding-model K_d fitting from concentration / signal data. Browser-only, no upload.