Selectors

Key Concept

Selectors are how you choose which atoms, residues, or chains to display in your visualization. They’re used in component() and color() nodes.

Selectors in MolViewSpec allow you to define substructures (components) and apply colors, labels, or tooltips to specific parts of a molecule. There are three types of selectors:

Static selectors - Simple string keywords
Component expressions - Objects specifying structural properties
Union component expressions - Arrays combining multiple selections

Static Selectors

Static selectors are simple strings that select atoms based on entity type:

Selector	Description
`"all"`	All atoms in the structure
`"polymer"`	All polymer chains (protein + nucleic acid)
`"protein"`	Protein chains only
`"nucleic"`	Nucleic acid chains only
`"branched"`	Branched entities (carbohydrates)
`"ligand"`	Small molecule ligands
`"ion"`	Ion atoms
`"water"`	Water molecules

Try It!

In the example above, try changing 'polymer' to 'ligand', 'water', or 'protein' to see different parts of the structure.

Component Expressions

Component expressions are objects that select atoms based on specific structural properties. All fields are optional, and specifying multiple fields requires atoms to match all criteria (AND logic).

Available Fields

{
    label_entity_id?: string,    // Entity identifier
    label_asym_id?: string,      // Chain ID (label numbering)
    auth_asym_id?: string,       // Chain ID (author numbering)
    label_seq_id?: number,       // Residue number (label numbering)
    auth_seq_id?: number,        // Residue number (author numbering)
    pdbx_PDB_ins_code?: string,  // PDB insertion code
    beg_label_seq_id?: number,   // Start residue (label, inclusive)
    end_label_seq_id?: number,   // End residue (label, inclusive)
    beg_auth_seq_id?: number,    // Start residue (author, inclusive)
    end_auth_seq_id?: number,    // End residue (author, inclusive)
    label_atom_id?: string,      // Atom name (e.g., 'CA', 'N', 'O')
    auth_atom_id?: string,       // Atom name (author numbering)
    type_symbol?: string,        // Element symbol (e.g., 'C', 'N', 'O')
    atom_id?: number,            // Unique atom identifier
    atom_index?: number,         // 0-based atom index
    instance_id?: string         // Instance ID (for symmetry/assemblies)
}

Label vs Auth Numbering

label_* uses standardized mmCIF numbering (starts at 1, no gaps)
auth_* uses the original author’s numbering (may have gaps, insertions)

Most PDB files use author numbering that matches the publication. Use auth_* fields to match literature references.

Common Selection Patterns

// Select entire chain A
{ label_asym_id: 'A' }

// Select residues 100-200 in chain B
{ label_asym_id: 'B', beg_label_seq_id: 100, end_label_seq_id: 200 }

// Select C-alpha atoms in residue 100
{ auth_seq_id: 100, type_symbol: 'C', auth_atom_id: 'CA' }

// Select residue 42 in chain A
{ label_asym_id: 'A', label_seq_id: 42 }

// Select all zinc atoms
{ type_symbol: 'ZN' }

// Select residues 1-50 in chain A
{ label_asym_id: 'A', end_label_seq_id: 50 }

// Select residues from 100 onwards in chain B
{ label_asym_id: 'B', beg_label_seq_id: 100 }

Union Component Expressions

Union component expressions are arrays of component expressions. They select atoms that match any of the expressions (OR logic).

Examples

// Select chains A, B, and C
selector: [
    { label_asym_id: 'A' },
    { label_asym_id: 'B' },
    { label_asym_id: 'C' }
]

// Select residues 1-100 in chain A OR all magnesium atoms
selector: [
    { label_asym_id: 'A', end_label_seq_id: 100 },
    { type_symbol: 'MG' }
]

// Select two separate regions in chain A
selector: [
    { label_asym_id: 'A', beg_label_seq_id: 10, end_label_seq_id: 20 },
    { label_asym_id: 'A', beg_label_seq_id: 40, end_label_seq_id: 50 }
]