Key Gotchas
Different field names per model
EWCL-Disorder returns residues[].disorder; EWCL-Sequence returns residues[].disorder_score; EWCL-Structure returns residues[].ewcl. They are NOT interchangeable.
EWCL-Raw is inverted
order_score from the unsupervised endpoint is HIGH for ordered residues. All other models return HIGH for disordered residues. Never mix them without normalising.
Structure endpoint uses PDB file upload
EWCL-Structure accepts multipart/form-data (or raw PDB body), not JSON. Sending JSON will result in an error.
Tau is a threshold, not a model parameter
The tau parameter controls the binary classification cutoff applied after scoring. It does not change the underlying model scores; only the binary label derived from them.
auth_seq_id is not zero-indexed
EWCL-Structure residues use auth_seq_id (author sequence numbering from the PDB file), not a zero-based index. Always use auth_asym_id + auth_seq_id + icode together as a residue key.
No authentication required
The production API is publicly accessible — no API key is needed. Rate limiting applies per IP.
CORS: call from server-side when possible
The API allows cross-origin requests but for production workloads prefer calling from a backend route to avoid exposing your client's origin or hitting browser request limits.
Endpoint Reference
Positional-context disorder predictor. Integrates local neighbourhood features alongside sequence composition for improved disorder boundary detection.
sequence (string)residues[].disorderconst res = await fetch("https://ewcl-api-production.up.railway.app/ewcl-disorder/predict", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ sequence: "MKVLWAALLVTFLAGCQ...", tau: 0.45 }),
});
const data = await res.json();
// data.residues[i].disorder ← per-residue scoreSequence-only disorder and conformational propensity prediction. No structure required — uses frozen positional and physicochemical features derived from the amino acid sequence.
sequence (string)residues[].disorder_score ⚠ different field nameconst res = await fetch("https://ewcl-api-production.up.railway.app/ewcl-sequence/predict", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ sequence: "MKVLWAALLVTFLAGCQ...", tau: 0.45 }),
});
const data = await res.json();
// data.residues[i].disorder_score ← note: NOT .disorderRuns both EWCL-Disorder and EWCL-Sequence in a single request and returns per-residue scores for both models alongside feature-family breakdowns.
sequence (string)residues[] with both .disorder and .disorder_scoreconst res = await fetch("https://ewcl-api-production.up.railway.app/api/predict/unified", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ sequence: "MKVLWAALLVTFLAGCQ...", tau: 0.45 }),
});
const data = await res.json();
// data.residues[i].disorder ← EWCL-Disorder
// data.residues[i].disorder_score ← EWCL-SequenceStructure-aware predictor incorporating per-residue pLDDT from AlphaFold. Enables EWCL–pLDDT disagreement analysis via the EDI diagnostic. Accepts a PDB file body.
/oneewcl-structure/analyze-pdbhttps://ewcl-api-production.up.railway.app/oneewcl-structure/analyze-pdbPDB file (multipart/form-data or raw body)residues[].ewcl + auth_asym_id + auth_seq_id + icodeconst form = new FormData();
form.append("file", pdbBlob, "structure.pdb");
form.append("tau", "0.45");
const res = await fetch("https://ewcl-api-production.up.railway.app/oneewcl-structure/analyze-pdb", {
method: "POST",
body: form,
});
const data = await res.json();
// data.residues[i].ewcl ← EWCL score
// data.residues[i].auth_seq_id / auth_asym_id / icodeUnsupervised latent-space order axis derived from sequence PCA. Returns order_score — HIGH means ORDERED (inverted relative to all other EWCL models). Use for exploratory analysis only.
/ewcl/unsupervised-latent/analyze-fastahttps://ewcl-api-production.up.railway.app/ewcl/unsupervised-latent/analyze-fastaFASTA string in request bodyresidues[].order_score ⚠ HIGH = ORDERED (inverted!)const res = await fetch("https://ewcl-api-production.up.railway.app/ewcl/unsupervised-latent/analyze-fasta", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ fasta: ">protein\nMKVLWAALLVTFLAGCQ..." }),
});
const data = await res.json();
// ⚠ data.residues[i].order_score — HIGH means ORDEREDTypeScript Types
// ─── Shared ─────────────────────────────────────────────────────────
interface EwclDisorderResidue {
index: number;
aa: string;
disorder: number; // EWCL-Disorder
}
interface EwclSequenceResidue {
index: number;
aa: string;
disorder_score: number; // EWCL-Sequence — different field name!
}
interface EwclStructureResidue {
auth_asym_id: string; // chain ID from PDB author numbering
auth_seq_id: number; // residue number from PDB author numbering
icode: string; // insertion code (' ' when none)
aa: string;
ewcl: number; // EWCL-Structure / EWCL-PDB P3
plddt?: number;
edi?: number;
}
interface EwclRawResidue {
index: number;
aa: string;
order_score: number; // HIGH = ORDERED (inverted vs all others!)
}
// ─── Endpoint responses ──────────────────────────────────────────────
interface EwclDisorderResponse {
residues: EwclDisorderResidue[];
model: string;
tau: number;
}
interface EwclSequenceResponse {
residues: EwclSequenceResidue[];
model: string;
tau: number;
}
interface EwclUnifiedResponse {
residues: Array<EwclDisorderResidue & Pick<EwclSequenceResidue, "disorder_score">>;
models: string[];
feature_families?: Record<string, unknown>;
}
interface EwclStructureResponse {
residues: EwclStructureResidue[];
model: string;
}
interface EwclRawResponse {
residues: EwclRawResidue[];
note?: string;
}Notebooks & Examples
Jupyter notebooks demonstrating end-to-end workflows are maintained in the ewcl-models.v1 repository.
Run EWCL-Disorder and EWCL-Sequence on a single sequence via the REST API.
Upload an AlphaFold PDB to EWCL-Structure and compute per-residue EDI conflict scores.
Call the unified endpoint and compare both model outputs side-by-side with matplotlib.
Batch-predict a list of UniProt sequences and save per-residue scores as Parquet.
Health & Status Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /health | Global health check — returns { status: 'ok' } |
| GET | /ewcl-disorder/health | EWCL-Disorder model health |
| GET | /ewcl-sequence/health | EWCL-Sequence model health |
| GET | /oneewcl-structure/health | EWCL-Structure model health |
Citation
If you use EWCL models in your research, please cite:
@unpublished{CristinoUversky_EWCL_2026,
author = {Cristino, Lucas and Uversky, Vladimir N.},
title = {Entropy-Weighted Conformational Likelihood (EWCL): sequence- and
structure-conditioned predictors of intrinsic disorder
and conformational propensity},
note = {Manuscript in preparation (preprint/journal submission forthcoming)},
year = {2026}
}