moleculekit.tools.survey module

Survey an input structure before building an MD system, and verify the build result afterwards.

surveyStructure() runs, in one call, every detection a structure needs before anything is submitted to a builder: what the structure is (a candidate RCSB entry recovered by sequence search when the input is a file of unknown origin), whether it is a membrane protein (entry keywords, when the entry is known), the full reference sequence of every chain (RCSB entity sequences, a sequence search, a UniProt accession, or a caller-supplied sequence), the unresolved stretches (gaps) and sequence mismatches (mutations) against that reference, and every residue whose bonds and formal charges are unknown. It also classifies each protein chain terminus as a real biological end or a cut, which is what decides whether that terminus is capped or left charged. The results are returned as a printable SurveyReport and persisted under outdir (input.cif, sequences.json, survey.json) so later sessions can act on them. Rerunning is how findings are refined: the resolved sequences are reused (sequences.json is the source of truth once written), and each parameter (pdbid=, sequences=, keep_mutations=) folds one decision into the stored state.

verifyBuildResult() is the closing bracket: it compares a produced structure against the pre-build input and reports backbone breaks, leftover ACE/NME-style caps, and per-chain protein residue counts - the checks a job status cannot make.

class moleculekit.tools.survey.SurveyReport(structure, outdir, pdbid, membrane, candidate_pdbid, chains, unresolved, gaps, mismatches, skipped_ncaa_chains, nonstandard, termini)

Bases: object

What surveyStructure() found, printable as a per-topic summary.

Every field is JSON-serializable; the same content is written to survey.json under the survey’s outdir.

termini holds two entries per protein chain (see detectTermini()): each end classified as natural (a real biological terminus - leave it charged), truncated (a construct boundary or an unfilled break - cap it) or unknown, with the sel and proposed_cap a build request needs. It is the last field so positional construction of the earlier ones keeps working.

candidate_pdbid: str | None

chains: dict

gaps: list

membrane: bool | None

mismatches: list

nonstandard: list

outdir: str

pdbid: str | None

skipped_ncaa_chains: list

structure: str

termini: list

unresolved: list

class moleculekit.tools.survey.VerifyReport(reference, result, breaks, caps, caps_missing, caps_extra, residues_in, residues_out)

Bases: object

What verifyBuildResult() found, printable as a per-check summary.

clean is True when the produced structure has no backbone breaks, no protein residues were lost relative to the input, and the caps are the ones asked for. A cap patching a backbone break still shows as the distance between the residues the cap sits between and is caught by the breaks check.

breaks: list

caps: list

caps_extra: dict

caps_missing: dict

property clean: bool

True when no breaks, no lost residues, and the caps are the ones asked for.

Returns:

clean – Whether all checks passed.

Return type:

bool

reference: str

residues_in: dict

residues_out: dict

result: str

moleculekit.tools.survey.surveyStructure(structure, outdir, pdbid=None, sequences=None, keep_mutations=False, trim=True)

Survey a structure: everything a builder needs decided, in one call.

Loads the structure, writes it as {outdir}/input.cif, resolves each protein chain’s full reference sequence, detects gaps, mismatches and non-standard residues, classifies every protein chain terminus as a real biological end or a cut (which is what decides its cap), and (when the entry is known) checks the RCSB membrane keywords. The resolved sequences are written to {outdir}/sequences.json (plain {chain: sequence}) and the full report to {outdir}/survey.json.

Rerunning refines the stored state instead of redoing it: chains already in sequences.json are not re-resolved (delete the file to start over), except that passing a new pdbid re-resolves every chain whose sequence did not come from the user, upgrading search hits to exact entity sequences.

Parameters:

• structure (str) – A structure file path, or a 4-letter RCSB PDB id.

• outdir (str) – Directory for input.cif, sequences.json and survey.json. Created if missing.

• pdbid (str | None) – The structure’s RCSB entry when known. Inferred automatically when structure is itself a PDB id. For a file input, pass the id the user confirmed (e.g. the report’s candidate_pdbid) to unlock the membrane keyword check and exact entity sequences.

• sequences (dict | None) – {chain: reference} supplied by the user, where each value is either a UniProt accession (fetched, and trimmed from the full-length precursor to the span the structure covers unless trim=False) or a raw one-letter sequence (used verbatim). These chains are never overwritten by later reruns.

• keep_mutations (bool) – When True, patch the reference sequences to the residues actually observed at mismatch positions before detecting gaps - modelling the construct as crystallised rather than reverting it to the reference.

• trim (bool) – Trim user-supplied precursor sequences to the span the structure covers (see sequences). Disable only to deliberately extend a terminus.

Returns:

report – The printable survey findings; the same content is in {outdir}/survey.json.

Return type:

SurveyReport

moleculekit.tools.survey.verifyBuildResult(reference, result, expected_caps=None)

Verify a built or prepared structure against the pre-build input.

Three checks a job status cannot make: backbone continuity of the produced structure (an unclosed break is an unmodelled gap or one the builder capped), leftover ACE/NME-style caps (legitimate only at a real chain terminus), and per-chain protein residue counts against the input (a drop means residues were silently discarded).

Parameters:

• reference (str) – Path of the pre-build input structure (what the build was asked to build).

• result (str) – Path of the produced structure (a build output or a prepared file).

• expected_caps (dict or None) – The dict of caps passed to the builder: {selection: capname}. When given, the function compares only cap names and counts (never resids or chains), measured as result-minus-reference, because the builder renumbers every resid after capping and re-letters chains, so the input selections cannot be resolved in the output. A "none" entry means that terminus was to stay charged and is not a cap to find. An unrequested cap — including one patching a break — surfaces as caps_extra. When None (the default), no cap comparison is done.

Returns:

report – The findings; report.clean says whether every check passed, and printing the report gives the per-check summary.

Return type:

VerifyReport