load_ensemble
Reads cryo-EM heterogeneity job volumes in trajectory order to preserve frame sequence, and detects the generating method so latent plots render correctly.
Instructions
Load a cryo-EM heterogeneity job's volumes in trajectory order.
Every method in this space writes the same thing: a directory of maps plus a table of latent coordinates. This reads them in trajectory order — naturally, so frame 10 does not sort between 1 and 2 and silently reorder the motion.
The generating method is identified from documented on-disk markers and is never guessed. A directory that matches nothing loads its volumes fine and stays unidentified, which makes latent views refuse to render: an unlabelled latent plot is what SPEC invariant I2 forbids, because each method's caveat is different and they are not interchangeable. Pass method= if you know.
Provenance defaults to "generated" rather than "unknown" — nothing observed a decoder's output — and the report says it declared that and on what evidence.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Prefix for the loaded frame objects (defaults to the directory name) | |
| method | No | Declare the generating method instead of detecting it: "cryodrgn", "3dva", "recovar", "3dflex", "dynamight", "cryospire" | |
| directory | Yes | Path to a heterogeneity job directory (cryoDRGN, 3DVA, RECOVAR, 3DFlex, DynaMight) | |
| provenance | No | How the volumes came to exist. Defaults to "generated" because heterogeneity output is decoder output or subspace interpolation. | generated |
| max_volumes | No | Ceiling on frames loaded; any excess is reported, not hidden | |
| trust_pickle | No | Permit reading a .pkl latent table. Off by default because unpickling runs arbitrary code from the file. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |