View

A View represents a selection at a specific structural level—atoms, residues, or chains. Views are lightweight, index-based projections of the parent BioMol.

Key characteristics of Views include:

• Powerful Selections: Select and filter data using indexing and set-like operations.

• Flexible Transitions: Transition between different structural levels with ease.

• Lightweight: Views only store indices, ensuring memory efficiency.

Basic Usage

To enter a view, first create a BioMol object:

mol = BioMol(...)

You can then access views via the atoms, residues, and chains attributes:

mol.atoms # AtomView
mol.residues # ResidueView
mol.chains # ChainView

Access features with attribute syntax or the get_feature method:

mol.atoms.name
mol.atoms.get_feature("name")

From any view, you can return to the parent BioMol via the mol attribute:

mol.atoms.mol

Indexing and Selection

Views support two primary ways to filter data: NumPy-style indexing and the PyMOL-like select method.

NumPy-style Indexing

Views support standard NumPy indexing operations, which always return a new View object.

• Slicing:

  atoms = mol.atoms[:5]
  

• Integer indexing:

  atoms = mol.atoms[[0, 2, 4]]
  last_residue = mol.residues[-1]
  

• Boolean indexing:

  ca_atoms = mol.atoms[mol.atoms.name == "CA"]
  gly_residues = mol.residues[mol.residues.name == "GLY"]
  protein_chains = mol.chains[mol.chains.entity == "PROTEIN"]
  

• Combined conditions:

  polar_residues = mol.residues[
      (mol.residues.name == "SER") | (mol.residues.name == "THR")
  ]
  

Indexing operations can be chained—an indexed view can itself be indexed again:

atoms = mol.atoms[:10]
ca_atoms = atoms[atoms.name == "CA"]

Note

View objects maintain their own index space. Always index using the view’s own indices:

atoms = mol.atoms[:10]
atoms[mol.atoms.name == "CA"] # ❌ Incorrect
atoms[atoms.name == "CA"]     # ✅ Correct

PyMOL-like Selection

The select method provides a PyMOL-like but Pythonic way of filtering.

• Single condition:

  ca_atoms = mol.atoms.select(name="CA")
  gly_residues = mol.residues.select(name="GLY")
  protein_chains = mol.chains.select(entity="PROTEIN")
  

• Multiple values for one feature:

  backbone_atoms = mol.atoms.select(name=["N", "CA", "C", "O"])
  positive_residues = mol.residues.select(name=["LYS", "ARG", "HIS"])
  chain_a_and_b = mol.chains.select(name=["A", "B"])
  

• Multiple features:

  disulfide_bond_atoms = mol.atoms.select(element="S", bond="disulfide")
  

Tip

Each keyword argument is combined with logical AND. In this example, disulfide_bond_atoms returns sulfur atoms that also participate in disulfide bonds.

Transitioning Between Levels

Views can freely transition between structural levels—atom, residue, and chain. This is not strictly hierarchical: any view can navigate to another level.

From lower to higher level:

ca_atoms = mol.atoms.select(name="CA")
ca_residues = ca_atoms.residues
ca_chains = ca_residues.chains

From higher to lower level:

chain_a = mol.chains.select(name="A")
gly_residues = chain_a.select(name="GLY")
gly_atoms = gly_residues.atoms

Note

Transitions using properties (atoms, residues, chains) always return views with unique indices. If you want to preserve duplicates (element-wise), use the explicit methods (to_atoms, to_residues, to_chains).

gly_residues = gly_atoms.residues # unique indices
gly_residues_dup = gly_atoms.to_residues() # preserve duplicates

Tip

Transitions always consider only the indices contained in the current view. In the example above, gly_atoms is restricted to the atoms within gly_residues, not all atoms of mol.

Operations

View objects support concatenation and set-wise operations.

Note

Operations are only supported between views of the same structural level within the same parent BioMol.

Concatenation:

protein_chains = mol.chains.select(entity="PROTEIN")
rna_chains = mol.chains.select(entity="RNA")
protein_and_rna = protein_chains + rna_chains

Set-like operations:

five_chains = mol.chains[:5]
protein_chains = mol.chains.select(entity="PROTEIN")

union = five_chains | protein_chains
intersection = five_chains & protein_chains
difference = five_chains - protein_chains
sym_difference = five_chains ^ protein_chains
invert = ~protein_chains # all chains except protein chains

Tip

Concatenation (+) preserves duplicates, while set-like operations (|, &, -, ^, ~) return unique indices.

Additional Methods

Index Manipulation

• .indices: Accesses the raw NumPy array of indices.

• unique: Returns a new view with duplicate indices removed.

• sort: Returns a new view with indices sorted in ascending order.

• new: Creates a new view from a raw array of indices.

State Checking

• is_empty: Checks if a view contains no elements.

• is_subset: Checks if one view is fully contained within another.