A PyMOL plugin for retrieving, integrating, visualizing, and comparing RNA structural motif annotations.
RSMViewer is a motif-centric PyMOL plugin for retrieving, consolidating, querying, and comparing RNA structural motif (RSM) annotations. It integrates annotations from multiple independent sources without forcing them into a single universal classification, so agreement and disagreement between annotation methods stay visible.
Who it's for: RNA structural biologists and bioinformaticians who want to explore, compare, and validate RNA 3D motif annotations from different databases and model-based search tools directly in PyMOL — using short commands, without writing code.
A motif is represented internally as a set of residues, with no constraint on the number of strands or chains. This lets motifs defined by sequence, secondary structure, base-interaction patterns, or 3D geometry coexist in one framework. Redundant residue sets are merged; distinct ones are preserved.
Fetch structures -> Load named sources -> Query motifs -> View · Compare · Export
- Version: 2.0.0
- Compatible with: PyMOL 3.x and later (tested on PyMOL 3.x, macOS/Linux/Windows)
- License: see LICENSE
- Features
- Installation in PyMOL
- Quick start
- Core concepts
- Command reference
- Example applications
- Annotation sources
- FR3D setup
- RNAMotifScanX setup
- Configuration
- Troubleshooting
- Testing
- Documentation
- Support
- Citation
- License
- Load structures by PDB ID or from local
.pdb/.ciffiles, one or many at a time. - Four public annotation sources:
RNA3DMotifAtlas,Rfam,FR3D,RNAMotifScanX. - Atlas and Rfam retrieved from their public APIs with local response caching.
- FR3D executed through a user-provided checkout; RNAMotifScanX loaded from preannotated data (collected live from our server, per PDB, on first use) or executed from scratch.
- Residue-set consolidation that preserves every source's own label and hierarchy.
- Deterministic, stable motif IDs (e.g.
1S72_00001). - Boolean selection across motifs, structures, and sources (
and,or,not). - Saved query groups, selectable PyMOL objects, medoid-based superimposition, and minimal coordinates-only mmCIF export.
External analysis software is not distributed with this project. FR3D is
provided by the user under external/fr3d/. RNAMotifScanX needs no manual setup:
its annotations (and, for run_from_scratch, its software) are downloaded
automatically the first time you use them.
-
Download or clone the RSMViewer repository and extract it if necessary.
-
Open PyMOL.
-
From the menu bar, select Plugin → Plugin Manager.
-
Open the Settings tab.
-
Under the plug-in search-path settings, select Add New Directory.
-
Navigate to the extracted
RSMViewer-maindirectory, open it, and select thersmviewerfolder. The selected path should end with:RSMViewer-main/rsmviewer -
Confirm the directory selection and restart PyMOL.
-
RSMViewer should load automatically after PyMOL restarts.
Note: Select the entire
rsmviewerfolder. Do not select the__init__.pyfile individually.
If the plugin is loaded successfully, you should see the startup banner in your PyMOL console:
================================================================================
RSMViewer
RNA Structural Motif Visualization and Comparative Analysis for PyMOL
Version 2.0.0 | Updated: 13 September 2026 | Compatible with PyMOL 2.x+
================================================================================
If the plugin does not load automatically, follow these steps:
- Return to Plugin → Plugin Manager → Settings.
- Under Plugin override search path, locate RSMViewer and move it to the top of the list.
- Restart PyMOL if prompted. RSMViewer should then be available from the Plugin menu.
Verify the installation in PyMOL:
rmv_help
rmv_db
The startup banner lists the four canonical source names.
RSMViewer prints a plain-ASCII banner and reconfigures standard output to UTF-8
on startup, so no special terminal setup is required. If your environment forces
a legacy code page (for example an Anaconda Prompt on Windows or a shell started
with LANG=C) and you see garbled characters in any output, enable UTF-8:
- macOS/Linux: start PyMOL from a UTF-8 locale, e.g.
LANG=en_US.UTF-8 pymol, or runexport PYTHONUTF8=1first. - Windows: run
chcp 65001in the prompt before launching PyMOL, or set the environment variablePYTHONUTF8=1.
Paste these seven commands into the PyMOL command line:
rmv_fetch 1S72 # load a structure
rmv_db RNA3DMotifAtlas # load annotations from a source
rmv_select SARCIN-RICIN, 1S72, RNA3DMotifAtlas, as group_SR
rmv_list group_SR # inspect motif IDs and residues
rmv_view group_SR # highlight the family
rmv_create_object group_SR # make selectable objects
rmv_super group_SR # medoid superimposition
What you'll see: rmv_db prints a motif-family table for 1S72; rmv_select
saves the Sarcin-Ricin family as group_SR; rmv_list shows each motif's stable
ID and residues; rmv_view colors them on the structure; and rmv_super reports
the medoid and per-instance RMSDs. New to the commands? Follow the
tutorial.
Structures. rmv_fetch loads coordinates only; it does not retrieve
annotations. Multiple structures can be loaded in one session.
Sources. rmv_db loads one or more named sources for every fetched
structure. Source names are case-insensitive and always shown canonically. Each
source's raw records are kept separate at load time; rmv_db prints one compact
table per source per structure (SELECTABLE NAME, ANNOTATION NAME, COUNT)
and performs no overlap merging. rmv_db accepts only a comma-separated
list of the four source names (RNA3DMotifAtlas, Rfam, FR3D,
RNAMotifScanX) — spaces around commas are optional (rmv_db A,B,
rmv_db A, B, and rmv_db A,B,C,D are all valid) — and nothing else; there
is no numeric-ID, filtering, or threshold argument.
Consolidation. Residue-set consolidation is applied within the requested
scope during rmv_select (one family per structure) and, across families, only
when you run rmv_combine_groups. Two residue sets are treated as the same
fragment when their Jaccard index is at least 0.60, or when one set is
largely nested inside the other (overlap coefficient at least 0.80). This
containment rule lets a tight motif core from one source and an extended
annotation of the same motif from another source share a single row, while each
source keeps its own original label on that row.
Stable motif IDs. Each consolidated row has a deterministic ID of the form
<PDBID>_00001, independent of load order.
Query groups. rmv_select ... as <group> saves a snapshot of the matching
motif IDs and the original query text. Groups drive view, object creation,
superimposition, combination, coloring, and export.
| Command | Purpose |
|---|---|
rmv_fetch <ID|path> [, <ID> ...] |
Fetch one or more structures, or load a local .pdb/.cif. |
rmv_db <source>[,<source>...] |
Select named sources and load annotations immediately. |
rmv_select <motif>, <structures>, <sources>, as <group> |
Save a Boolean query as stable motif IDs. |
rmv_list [ID|group|family] |
List all rows, one motif ID, a saved group, or every row in a family (e.g. SARCIN-RICIN). |
rmv_view <ID|group> [, color=<name>] [, padding=<n>] |
Highlight motif residues on parent structures. |
rmv_hide <ID|group|all> |
Remove highlight (recolor the structure to neutral gray). |
rmv_create_object <ID|group> |
Create selectable PyMOL objects (camera unchanged). |
rmv_super <ID|group> |
Medoid-based superimposition (sequence-independent). |
rmv_align <ID|group> |
Medoid-based superimposition (sequence-dependent). |
rmv_combine_groups <group>, <group>[, ...], as <group> |
Combine saved groups into a new group. |
rmv_set_color <group>, <color> |
Set a group color; preserved per source through rmv_combine_groups. |
rmv_color <motif>, <color> |
Set a motif-family color preference. |
rmv_bg_color <color> |
Change the background (non-motif) color. |
rmv_save <group|ID|ALL> cif |
Export minimal coordinates-only mmCIF files (prints the output directory). |
rmv_save current [file.png] |
Save the current PyMOL view as a high-resolution PNG (prints the path). |
rmv_save ALL [representation] |
Save an image of every motif (cartoon by default). |
rmv_colors |
List supported color names. |
rmv_db (no args) |
Show the four public sources and usage. |
rmv_source info [<N>] |
Show the active source configuration. |
rmv_fr3d status|setup|register|run [PDB] |
Inspect / install / register / run the FR3D pipeline. |
rmv_setup RNAMotifScanX |
Optional: prepare everything for run_from_scratch ahead of time (otherwise done automatically on first run). |
rmv_rmsx_doctor |
Check whether RNAMotifScanX is ready and what is missing. |
rmv_pair <selection> / rmv_pair_batch <selection> |
Inspect base-pair interactions. |
rmv_chains / rmv_loaded |
Show chain diagnostics / loaded structure and source tags. |
rmv_refresh [PDB] |
Bypass caches and re-fetch. With no argument, refreshes every active structure; with a PDB ID, refreshes only that one. |
rmv_debug ON|OFF |
Toggle verbose diagnostics (off by default). |
rmv_help |
Show the in-PyMOL command reference. |
rmv_reset |
Show details about rmv_reset cache/rmv_reset session; performs no reset on its own. |
rmv_reset cache |
Clear only the caches (hierarchy SQLite cache, API response cache, provider in-memory caches, FR3D run cache); loaded objects/session state untouched. |
rmv_reset session |
Delete all objects and reset session state (loaded structures, query groups, source selections, colors); on-disk caches untouched. |
The selection grammar has four comma-separated clauses:
rmv_select <motif>, <structures>, <sources>, as <group>
- motif — a family name or abbreviation (
SR,SARCIN-RICIN,KT,K-TURN,CL,C-LOOP,EL,E-LOOP,GNRA, …). Abbreviations, separators, and family-index suffixes (sarcin-ricin-1) all resolve to the same family. - structures — one ID, an
and/orlist, orall. - sources — a Boolean expression over source names with
not>and>orprecedence. A sourceandrequires both sources on the same consolidated row. - group — a name for the saved result (
as group_SR).
These mirror the applications in the RSMViewer paper.
rmv_fetch 1S72
rmv_db RNA3DMotifAtlas
rmv_select SARCIN-RICIN, 1S72, RNA3DMotifAtlas, as group_SR
rmv_list group_SR
rmv_view 1S72_00001 # a concrete motif ID from rmv_list
rmv_fetch 1S72
rmv_db RNA3DMotifAtlas
rmv_select SARCIN-RICIN, 1S72, RNA3DMotifAtlas, as group_SR
rmv_view group_SR
rmv_fetch 1S72, 1FFK
rmv_db RNA3DMotifAtlas, Rfam
rmv_select SARCIN-RICIN, 1S72 and 1FFK, RNA3DMotifAtlas and Rfam, as group_SR
rmv_select KT, all, RNA3DMotifAtlas and Rfam, as group_KT
rmv_select CL, all, RNA3DMotifAtlas and Rfam, as group_CL
rmv_select EL, all, RNA3DMotifAtlas and Rfam, as group_EL
rmv_view group_SR, group_KT, group_CL, group_EL
rmv_fetch 1S72
rmv_db RNA3DMotifAtlas
rmv_select SR, 1S72, RNA3DMotifAtlas, as group_SR
rmv_create_object group_SR
rmv_super group_SR
Uses RNA 3D Motif Atlas as ground truth for RNAMotifScanX predictions.
rmv_fetch 1S72
rmv_db RNA3DMotifAtlas, RNAMotifScanX
rmv_select SR, 1S72, RNA3DMotifAtlas and RNAMotifScanX, as group_TP # true positives
rmv_select SR, 1S72, not RNA3DMotifAtlas and RNAMotifScanX, as group_FP # false positives
rmv_select SR, 1S72, RNA3DMotifAtlas and not RNAMotifScanX, as group_FN # false negatives
rmv_fetch 1S72
rmv_db RNA3DMotifAtlas, RNAMotifScanX
rmv_select SR, 1S72, not RNA3DMotifAtlas and RNAMotifScanX, as group_FP
rmv_select SR, 1S72, RNA3DMotifAtlas, as group_known
rmv_set_color group_FP, red
rmv_set_color group_known, blue
rmv_combine_groups group_FP, group_known, as group_combined
rmv_create_object group_combined
rmv_super group_combined
Note the
rmv_set_colorsyntax: the group name follows the command with no comma after the command word —rmv_set_color group_FP, red.
Colors set on each source group are preserved per member when the groups are
combined: after rmv_create_object group_combined, the group_FP objects stay
red and the group_known objects stay blue. (An explicit color set on the
combined group itself overrides this and colors every member uniformly.)
| Source | Retrieval | Notes |
|---|---|---|
RNA3DMotifAtlas |
BGSU RNA 3D Hub API | Online, cached locally. |
Rfam |
Rfam API | Online, cached locally. |
FR3D |
Previously generated results or user-provided checkout | Cache mode serves prior results from output/fr3d_runs/; run_from_scratch mode runs official fr3d-python. |
RNAMotifScanX |
Preannotated data or from-scratch run | See setup below. |
Atlas and Rfam require network access on first retrieval; responses are cached
so repeated queries are offline. Use rmv_refresh to bypass the cache.
FR3D has two modes, selected by data_mode in config/fr3d_config.json:
cache:rmv_db FR3Dloads previously generated results for the structure fromoutput/fr3d_runs/<PDB>/. If none exist there it reports that and asks you to run from scratch. It never runs FR3D, makes no network call, and there is no external/bundled cache.run_from_scratch(default):rmv_db FR3Dalways executes the official BGSU fr3d-python pipeline on the loaded structure and loads the freshly generated results from a new timestamped run directory underoutput/fr3d_runs/.
rmv_reset cache clears the FR3D run cache at output/fr3d_runs/.
To run the pipeline from scratch:
-
Paste the official fr3d-python checkout into
external/fr3d/fr3d-python-latest/(download from https://github.com/BGSU-RNA/fr3d-python/tree/latest). It must containfr3d/__init__.pyandfr3d/search/FR3D.py. -
Set
"data_mode": "run_from_scratch"inconfig/fr3d_config.json. -
Install FR3D's dependencies and register it in one step — this also prints a readiness report:
rmv_setup FR3D -
Run it on a loaded structure:
rmv_fetch 1S72 rmv_db FR3D
Detailed FR3D instructions — both modes, query selection, the full config reference, first-run cache behavior, and troubleshooting — are in external/FR3D_SETUP.md.
RNAMotifScanX (RMSX) is controlled by data_mode in config/rmsx_config.json.
The default is preannotated, which loads precomputed results and needs no
binaries. To give you the most up-to-date RNAMotifScanX annotations, RSMViewer
collects the preannotated data live from our server: results are downloaded
automatically, per structure, the first time you request them (an internet
connection is needed for that first load only).
Keep "data_mode": "preannotated" and run:
rmv_fetch 1S72
rmv_db RNAMotifScanX
For each requested PDB RSMViewer looks for the results in this order:
-
Local folder
external/rmsx_preannotated/rmsx_work_default/<pdb>/. -
Download the PDB's archive from the public results server, extract it into the folder above, and read it from there. The link uses the lowercase PDB ID; later loads of the same PDB use the local folder and do not download again:
https://cbb.ittc.ku.edu/RNAMotifScanX_Results/RSMViewer/rmsx_work_default/<pdb>.tar.gz e.g. .../rmsx_work_default/1s72.tar.gz
A download is attempted only for a 4-character PDB ID with no local results and a
reachable server, and is accepted only if the archive extracts safely and holds at
least one *_consensus.log. The server address is preannotated_base_url in
config/rmsx_config.json. The dataset may not cover every PDB yet; if a
structure is not available RSMViewer says so and you can scan it yourself with
run_from_scratch below. To refresh a PDB, delete its local folder and rerun.
To run RNAMotifScanX yourself instead of loading precomputed annotations, set
"data_mode": "run_from_scratch" in config/rmsx_config.json, then:
rmv_fetch 1S72
rmv_db RNAMotifScanX
The first time you run it, RSMViewer downloads all the required files and
third-party software by itself from
https://cbb.ittc.ku.edu/RNAMotifScanX_Results/RSMViewer/rmsx.tar.gz
into external/rmsx/ and prepares them for your computer; later runs start
immediately. On macOS you need the Xcode command line tools
(xcode-select --install), and on Windows WSL2 or Docker Desktop; Linux needs
nothing extra. Use rmv_rmsx_doctor to check readiness.
Full RMSX setup guide (config modes, preannotated download, and run-from-scratch on macOS, Windows and Linux): external/rmsx_setup.md.
Both pipelines are configured by small JSON files under config/. See
config/README.md for every field, allowed value, and how
paths are resolved.
- P-value cutoffs live only under
pvalue_thresholdsinconfig/rmsx_config.json. Command-line P-value overrides are intentionally not supported. - The residue-overlap thresholds are code-defined, not config options. To change
them, edit
DEFAULT_JACCARD_THRESHOLD(0.60) andDEFAULT_CONTAINMENT_THRESHOLD(0.80) inrsmviewer/database/consolidated_table.py.
Multiple PDB IDs not loading. Use comma-separated IDs:
rmv_fetch 1S72, 1FFK, 3CC2.
Atlas/Rfam returns no annotations. Check network access, then
rmv_refresh and re-run rmv_db.
A source and query is empty. The two sources may annotate the motif at
residue sets that neither overlap by ≥ 0.60 Jaccard nor by ≥ 0.80 containment,
so they sit on separate rows. Inspect with rmv_list.
FR3D is unavailable. Confirm the checkout path in config/fr3d_config.json,
run rmv_setup FR3D, and check rmv_fr3d status. Geometric queries need
allow_network: true.
RMSX says no results are available for a PDB. Preannotated results are
downloaded from our server, which may not have every PDB yet, or it could not be
reached (check your internet connection). RSMViewer prints which case it is and
the URL it tried; use run_from_scratch to scan the structure yourself.
RMSX returns no motifs. A result can legitimately contain zero accepted
motifs when every reported P-value exceeds the configured threshold. Check
data_mode and pvalue_thresholds.
Pick the document that matches what you need:
| I want to… | Read |
|---|---|
| Learn RSMViewer step by step | docs/TUTORIAL.md |
| Look up exact command syntax | Command reference · in-PyMOL rmv_help |
| Configure FR3D / RNAMotifScanX | config/README.md |
| Understand the design and internals | DEVELOPED.md |
| Read the paper and its supplement | docs/SUPPLEMENT.md |
- Run
rmv_helpin PyMOL for the full command reference. - Enable
rmv_debug ONto print diagnostic messages before reporting an issue. - When reporting a problem, include your PyMOL version, operating system, the exact commands you ran, and the console output.
If you use RSMViewer in your research, please cite it. Machine-readable citation metadata is in CITATION.cff.
Rahad, R. H., Pranjal, S., Khan, N. S., Zhang, S., & Zhong, C. RSMViewer: A PyMOL plugin for RNA structural motif visualization. Bioinformatics. DOI: 10.6084/m9.figshare.33826777
RSMViewer is released under the MIT License — see LICENSE. External
analysis software and datasets under external/ are provided by the user and
retain their own licenses.