tomodrgn subtomo2chimerax#

Purpose#

Generate ChimeraX command script to visualize selected particles in the spatial context of the source tomogram. Particles may be visualized as tomoDRGN train_vae-generated unique volumes, a single “consensus” volume, or spherical markers.

Sample usage#

The examples below are adapted from tomodrgn/testing/commandtest*.py, and rely on other outputs from commandtest.py to execute successfully.

# Warp v1 style inputs -- mapback particles as spherical markers
tomodrgn \
    subtomo2chimerax \
    data/10076_both_32_sim_vols.star \
    --mode markers \
    --outdir output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/mapback_markers \
    --tomoname both.tomostar \
    --star-angpix-override 10 \
    --coloring-labels data/ptcl_labels_D0_E1.pkl

# Warp v1 style inputs -- mapback particles as consensus volume
tomodrgn \
    subtomo2chimerax \
    data/10076_both_32_sim_vols.star \
    --mode volume \
    --outdir output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/mapback_volume \
    --tomoname both.tomostar \
    --star-angpix-override 10 \
    --vol-path output/backproject/classE_sim_doseweight.mrc \
    --vol-render-level 0.7 \
    --coloring-labels data/ptcl_labels_D0_E1.pkl

# Warp v1 style inputs -- mapback particles as tomoDRGN-generated unique volumes
tomodrgn \
    subtomo2chimerax \
    data/10076_both_32_sim_vols.star \
    --mode volumes \
    --outdir output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/mapback_volumes_cmaptab10 \
    --tomoname both.tomostar \
    --star-angpix-override 10 \
    --weights output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/weights.39.pkl \
    --config output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/config.pkl \
    --zfile output/vae_both_sim_zdim8_dosetiltweightmask_batchsize8/z.39.train.pkl \
    --vol-render-level 0.7 \
    --coloring-labels data/ptcl_labels_D0_E1.pkl \
    --colormap tab10

# WarpTools style inputs -- mapback particles as tomoDRGN-generated unique volumes
tomodrgn \
    subtomo2chimerax \
    data/warptools_test_4-tomos_10-ptcls_box-32_angpix-12_optimisation_set.star \
    --mode volumes \
    --outdir output/vae_warptools_70S_zdim8_dosetiltweightmask_batchsize8/mapback_volumes_cmaptab10 \
    --tomoname Unt_076.tomostar \
    --weights output/vae_warptools_70S_zdim8_dosetiltweightmask_batchsize8/weights.39.pkl \
    --config output/vae_warptools_70S_zdim8_dosetiltweightmask_batchsize8/config.pkl \
    --zfile output/vae_warptools_70S_zdim8_dosetiltweightmask_batchsize8/z.39.train.pkl \
    --vol-render-level 0.7 \
    --coloring-labels output/vae_warptools_70S_zdim8_dosetiltweightmask_batchsize8/analyze.39/kmeans20/labels.pkl \
    --colormap tab20

Arguments#

usage: subtomo2chimerax [-h] --outdir OUTDIR [--mode {volumes,volume,markers}]
                        [--ind IND] [--tomoname TOMONAME]
                        [--tomo-id-col-override TOMO_ID_COL_OVERRIDE]
                        [--star-angpix-override STAR_ANGPIX_OVERRIDE]
                        [--weights WEIGHTS] [--config CONFIG] [--zfile ZFILE]
                        [--flip] [--invert] [--downsample DOWNSAMPLE]
                        [--lowpass LOWPASS] [--skip-vol] [--vol-path VOL_PATH]
                        [--marker-radius-angstrom MARKER_RADIUS_ANGSTROM]
                        [--vol-render-level VOL_RENDER_LEVEL]
                        [--coloring-labels COLORING_LABELS]
                        [--colormap COLORMAP]
                        starfile

Positional Arguments#

starfile

Input volumeseries starfile from subtomogram export; used to specify particle XYZ coordinates and rotational pose.Can also pass in an optimisation_set star file; otherwise pass in the associated rlnTomoParticlesStarfile.

Core arguments#

--outdir

Path to directory to store ouptut script(s) and volume(s).

--mode

Possible choices: volumes, volume, markers

Choice of particle rendering mode: unique volume per particle, a single consensus volume for all particles, or ChimeraX spherical markers for all particle

Default: 'markers'

--ind

Ind.pkl specified when training tomodrgn model (if applicable). Must be specified if either –zfile, –coloring-labels are specified and the number of values in these pkl files does not match the number of rows in –starfile.

--tomoname

Name of a single tomogram in input starfile for which to write mapback script. If blank, default is to prepare scripts and volumes for all tomograms.

--tomo-id-col-override

Name of column in input starfile to filter by –tomoname

--star-angpix-override

Override pixel size of input particle_volumeseries starfile (units Å/px)

Volume specification options - generate unique-per-particle tomoDRGN volumes. Required if `–mode volumes`.#

--weights

Tomodrgn train_vae model weights to use for generating unique-per-particle volumes.

--config

Tomodrgn train_vae config.pkl file.

--zfile

Tomodrgn train_vae latent embeddings .pkl/.txt file with z-values to decode to volumes.

--flip

Optionally flip handedness of output volumes relative to trained model.

Default: False

--invert

Optionally invert contrast of output volumes relative to trained model.

Default: False

--downsample

Optionally downsample decoded volumes to this box size (pixels). Recommeneded to if model was trained with box size > 128.

--lowpass

Optionally lowpass filter volumes to this resolution in Å.

--skip-vol

Skip generation of volumes. Should only be used if volmes have been previously generated by this script. Useful for tweaking coloring_labels or colormap. Is not valid if any volume generation parameters or outdir are changed.

Default: False

Volume specification options - single pregenerated volume. Required if `–mode volume`.#

--vol-path

Path to single consensus volume to map back at each particle location in tomogram.

Volume specification options - ChimeraX spherical markers. Required if `–mode markers`.#

--marker-radius-angstrom

Radius of ChimeraX markers (units: Å).

Default: 100

ChimeraX rendering options#

--vol-render-level

Isosurface level to render all volumes in ChimeraX

Default: 0.5

--coloring-labels

Path to a .pkl file containing a unique value for each particle (e.g. kmeans class label, continuous scalar).

--colormap

Matplotlib colormap to apply to –coloring-labels (default = ChimeraX color scheme per label value). See https://matplotlib.org/stable/tutorials/colors/colormaps.html (e.g. tab20)

Common next steps#

  • Quantify spatially contextualized heterogeneity trends using custom scripts or external software, perhaps involving tomogram segmentations

  • Make cool images and/or movies in ChimeraX