Targets

The Target class provides a hierarchical representation and manipulation interface for molecular structures in dash-molstar. Together with its related classes (Chain, Residue, Atom, Boundary, Box, Sphere), it allows users to conveniently access and modify chains, residues, atoms, and perform geometric boundary calculations, suitable for molecular visualization, analysis, and structure editing.

Users can easily loop over all the structural elements within one target, and get the boundary of the target as well. The following table illustrates the members in the Target class:

Member	Type	Description
`valid`	`bool`	`True` if the Target instance contains at least one chain, `False` otherwise.
`chains`	`List[Chain]`	A list of `Chain` objects belonging to this target.
`residues`	`List[Residue]`	A flattened list of all valid `Residue` objects from all chains within this target.
`atoms`	`List[Atom]`	A flattened list of all valid `Atom` objects from all residues in all chains within this target
`boundary`	`Optional[Boundary]`	A `Boundary` instance representing the geometric boundary of all atoms in the target.

Quick Start Example

Basic Usage

The fundamental usage is to parse the structural data returned by dash-molstar. In dash-molstar, select and focus properties are corresponding to the selected or focused molecular motif.

The following example will print the selected targets every time the selections have been changed.

import dash_molstar
from dash import Dash, html, Input
from dash_molstar.utils.target import Target
from dash_molstar.utils import molstar_helper

app = Dash(__name__)
app.layout = html.Div(
    dash_molstar.MolstarViewer(
        id='viewer', style={'width': '500px', 'height':'500px'}
    ),
)

@app.callback(Input('viewer', 'select'),
              prevent_initial_call=True)
def display_select(select):
    print("Current selection data:")
    target = Target(select)
    for chain in target.chains:
        print("Chain name:", chain.name, ",Auth name:", chain.auth_name)
        for residue in chain.residues:
            print("  Residue index:", residue.index, ",Residue number:", str(residue.number)+residue.ins_code, ",Name:", residue.name)
            for atom in residue.atoms:
                print("    Atom name:", atom.name, ",x:", atom.x, ",y:", atom.y, ",z:", atom.z)
    print("Number of chains:", len(target))
    print("Number of residues:", len(target.residues))
    print("Number of atoms:", len(target.atoms), end="\n\n")

Note

For sending structural data to dash-molstar, the user should use the helper function get_targets() to generate Target instances. See the Targets section in helper function documentations.

Search & Modify

Except for looping over all the items, you can also search for specific elements, like chain, residue, or atom.

# Already parsed select data
target = Target(select)

# Find a specific chain, residue, and atom on Target instance
# Returns an invalid instance if not found
chain = target.find_chain(name='A')
if chain.valid: print("Found chain", chain.name)

residue = target.find_residue(chain_name='A', residue_number=1)
if residue.valid: print('Found residue:', residue.name, residue.number)

atom = target.find_atom(chain_name='A', residue_number=1, atom_name='CA')
if atom.valid: print('Found atom:', atom.name)

# Add a new chain
target.add_chain('B')

# Remove chain B
target.remove_chain('B')
# Remove chain A
target.remove_chain(chain)

Getting boundaries

With the boundary property, you can get the boundary of the returned target.

# Already parsed select data
target = Target(select)

boundary = target.boundary
print("Boundary box min:", boundary.box.min)
print("Boundary box max:", boundary.box.max)
print("Boundary sphere center:", boundary.sphere.center)
print("Boundary sphere radius:", boundary.sphere.radius)

Class Reference

Target

The Target class is the main entry point for interacting with molecular structure data. It encapsulates a collection of chains, which in turn contain residues and atoms. It provides methods for initializing a structure from dash-molstar, accessing its components, finding specific elements, and modifying the selection.

class Target(data: dict = {})

Initializes a Target instance.

Parameters:: data (dict, optional) – A dictionary representing the molecular structure. It should be constructed from the data retrieved from the dash-molstar. If data is empty or malformed, an invalid Target instance will be created.

Properties

valid
- Type: bool
- Description: Returns True if the Target instance contains at least one chain, False otherwise. Indicates if the target is considered valid and has content.
chains
- Type: List[Chain]
- Description: A list of Chain instance belonging to this target. Modifications to this list directly affect the Target’s chains.
residues
- Type: List[Residue]
- Description: A list of all valid Residue instance from all chains within this target. This is a flattened list.
atoms
- Type: List[Atom]
- Description: A list of all valid Atom instance from all residues in all chains within this target. This is a flattened list.
boundary
- Type: Optional[Boundary]
- Description: A Boundary instance representing the geometric boundary (both a bounding box and a bounding sphere) of all atoms in the target. Calculated on first access. Raises ValueError if the target is invalid or contains no atoms with coordinates.

Methods

Target.__len__()

Returns the number of chains in the Target instance.

Return type:: int

Target.find_chain(name: str) → Chain

Finds and returns a Chain instance by its name.

Parameters:: name (str) – The name of the chain to find.
Returns:: The Chain instance if found, otherwise an invalid Chain instance (where chain.valid is False).
Return type:: Chain

Target.find_residue(chain_name: str, residue_number: int, ins_code: str = '') → Residue

Finds and returns a Residue instance within a specified chain by its number and optional insertion code.

Parameters:

chain_name (str) – The name of the chain to search within.
residue_number (int) – The number of the residue to find.
ins_code (str, optional) – The insertion code of the residue (optional).

Returns:

The Residue instance if found, otherwise an invalid Residue instance (where residue.valid is False).

Return type:

Residue

Target.find_atom(chain_name: str, residue_number: int, atom_name: str, ins_code: str = '') → Atom

Finds and returns an Atom instance within a specified residue of a specified chain.

Parameters:

chain_name (str) – The name of the chain to search within.
residue_number (int) – The number of the residue to search within.
atom_name (str) – The name of the atom.
ins_code (str, optional) – The insertion code of the residue (optional).

Returns:

The Atom instance if found, otherwise an invalid Atom instance (where atom.valid is False).

Return type:

Atom

Target.add_chain(chain_name: str, residues: List = [], auth_name: str = '')

Adds a new chain to the Target instance.

Parameters:

chain_name (str) – The name for the new chain.
residues (List, optional) – A list of residue data to initialize the chain with (optional). This should be automatically provided when parsing the return data from dash-molstar.
auth_name (str, optional) – The authentic name for the new chain (optional). If not provided, chain_name is used.

Target.remove_chain(chain_name: str | Chain) → bool

Removes a chain from the Target instance, either by its name or by providing the Chain instance itself.

Parameters:: chain_name (Union[str, Chain]) – The name of the chain to remove or the Chain instance to remove.
Returns:: True if the chain was successfully removed, False otherwise.
Return type:: bool

Target.to_dict() → dict

Exports the current structure of the Target instance (including all its chains, residues, and atoms) to a dictionary.

Returns:: A dictionary representation of the Target. It will be called automatically within helper functions.
Return type:: dict

Chain

The Chain class represents a single chain within a molecular structure, containing a list of residues. It provides methods for accessing and modifying its name, residues, and atoms within those residues.

class Chain(chain_name: str = None, residues: List[dict] = [], auth_name: str = '')

Initializes a Chain instance. The instance will be valid if it’s name is not None.

Parameters:

chain_name (str, optional) – The name of the chain (e.g., ‘A’).
residues (List[dict], optional) – A list of dictionaries, where each dictionary represents a residue and its atoms. This should be automatically provided when parsing the return data from dash-molstar.
auth_name (str, optional) – The authentic (author-assigned) name of the chain, if different from chain_name.

Properties

name
- Type: str
- Description: The primary identifier for the chain.
auth_name
- Type: str
- Description: The authentic (author-assigned) name of the chain. Defaults to name if not specified.
residues
- Type: List[Residue]
- Description: A list of Residue objects belonging to this chain.
atoms
- Type: List[Atom]
- Description: A flattened list of all Atom objects from all residues within this chain.
valid
- Type: bool
- Description: Returns True if the chain has a name, False otherwise.

Methods

Chain.__len__()

Returns the number of residues in the chain.

Return type:: int

Chain.find_residue(number: int, ins_code: str = '') → Residue

Finds and returns a Residue instance by its number and optional insertion code.

Parameters:

number (int) – The number of the residue to find.
ins_code (str, optional) – The insertion code of the residue (optional).

Returns:

The Residue instance if found, otherwise an invalid Residue instance.

Return type:

Residue

Chain.find_atom(residue_number: int, atom_name: str, ins_code: str = '') → Atom

Finds and returns an Atom instance within a specified residue of this chain.

Parameters:

residue_number (int) – The number of the residue.
atom_name (str) – The name of the atom.
ins_code (str, optional) – The insertion code of the residue (optional).

Returns:

The Atom instance if found, otherwise an invalid Atom instance.

Return type:

Atom

Chain.add_residue(index: int, number: int = None, ins_code: str = '', name: str = '', atoms: List[dict] = [])

Adds a new residue to the chain.

Parameters:

index (int) – The index for the new residue.
number (int, optional) – The number for the new residue. If None, defaults to index.
ins_code (str, optional) – The insertion code for the new residue.
name (str, optional) – The name of the new residue (e.g., ‘ALA’).
atoms (List[dict], optional) – A list of atom data dictionaries to initialize the residue with.

Chain.remove_residue(number: int | Residue, ins_code: str = '') → bool

Removes a residue from the chain, either by its number and insertion code or by providing the Residue instance itself.

Parameters:

number (Union[int, Residue]) – The number of the residue to remove or the Residue instance.
ins_code (str, optional) – The insertion code of the residue (if removing by number).

Returns:

True if the residue was successfully removed, False otherwise.

Return type:

bool

Residue

The Residue class represents a single residue (e.g., an amino acid or nucleotide) within a chain, containing a list of atoms.

class Residue(index: int = None, number: int = None, ins_code: str = '', name: str = '', atoms: List[dict] = [])

Initializes a Residue instance. The instance will be valid if it’s index is not None.

Parameters:

index (int, optional) – The index of the residue within its chain.
number (int, optional) – The residue number (sequence number). If None, defaults to index.
ins_code (str, optional) – The insertion code for the residue (e.g., ‘A’).
name (str, optional) – The name of the residue (e.g., ‘GLY’, ‘A’).
atoms (List[dict], optional) – A list of dictionaries, where each dictionary represents an atom. This should be automatically provided when parsing the return data from dash-molstar.

Properties

name
- Type: str
- Description: The name of the residue.
index
- Type: int
- Description: The sequential index of the residue.
number
- Type: int
- Description: The residue number as assigned in the structure file.
ins_code
- Type: str
- Description: The insertion code, used to distinguish residues with the same number.
atoms
- Type: List[Atom]
- Description: A list of Atom objects belonging to this residue.
valid
- Type: bool
- Description: Returns True if the residue has an index, False otherwise.

Methods

Residue.__len__()

Returns the number of atoms in the residue.

Return type:: int

Residue.find_atom(name: str) → Atom

Finds and returns an Atom instance by its name within this residue.

Parameters:: name (str) – The name of the atom to find (e.g., ‘CA’).
Returns:: The Atom instance if found, otherwise an invalid Atom instance.
Return type:: Atom

Residue.add_atom(index: int, name: str = None, x: float = None, y: float = None, z: float = None)

Adds a new atom to the residue.

Parameters:

index (int) – The index for the new atom.
name (str, optional) – The name of the new atom (e.g., ‘N’, ‘CA’).
x (float, optional) – The x-coordinate of the new atom.
y (float, optional) – The y-coordinate of the new atom.
z (float, optional) – The z-coordinate of the new atom.

Residue.remove_atom(name: str | Atom) → bool

Removes an atom from the residue, either by its name or by providing the Atom instance itself.

Parameters:: name (Union[str, Atom]) – The name of the atom to remove or the Atom instance.
Returns:: True if the atom was successfully removed, False otherwise.
Return type:: bool

Atom

The Atom class represents a single atom within a residue, storing its properties like name, index, and coordinates.

class Atom(index: int = None, name: str = None, x: float = None, y: float = None, z: float = None)

Initializes an Atom instance. The instance will be valid if the atom has a name.

Parameters:

index (int, optional) – The index of the atom.
name (str, optional) – The name of the atom (e.g., ‘N’, ‘CA’, ‘C1’).
x (float, optional) – The x-coordinate of the atom.
y (float, optional) – The y-coordinate of the atom.
z (float, optional) – The z-coordinate of the atom.

Properties

name
- Type: str
- Description: The name of the atom.
index
- Type: int
- Description: The index of the atom.
x
- Type: float
- Description: The x-coordinate of the atom.
y
- Type: float
- Description: The y-coordinate of the atom.
z
- Type: float
- Description: The z-coordinate of the atom.
valid
- Type: bool
- Description: Returns True if the atom has an index, False otherwise.

Boundary, Box, and Sphere Classes

These classes are used to define and calculate the geometric boundaries of a set of atoms. The Target.boundary property returns a Boundary instance.

Boundary Class

The Boundary class calculates and holds the bounding box and bounding sphere for a given set of coordinates.

class Boundary(coords: np.ndarray = None)

Initializes a Boundary instance.

Parameters:: coords (np.ndarray, optional) – A NumPy array of shape (N, 3) representing N atomic coordinates.

Properties

box
- Type: Optional[Box]
- Description: A Box instance representing the minimal bounding box enclosing all provided coordinates. None if no coordinates were provided.
sphere
- Type: Optional[Sphere]
- Description: A Sphere instance representing the minimal bounding sphere enclosing all provided coordinates. None if no coordinates were provided.

Box Class

The Box class defines an axis-aligned bounding box.

class Box(min_coords: tuple[float, float, float] = None, max_coords: tuple[float, float, float] = None)

Initializes a Box instance.

Parameters:

min_coords (tuple[float, float, float], optional) – A tuple (min_x, min_y, min_z) representing the minimum coordinates of the box.
max_coords (tuple[float, float, float], optional) – A tuple (max_x, max_y, max_z) representing the maximum coordinates of the box.

Properties

min
- Type: tuple[float, float, float]
- Description: The minimum (x, y, z) coordinates of the box.
max
- Type: tuple[float, float, float]
- Description: The maximum (x, y, z) coordinates of the box.
center
- Type: tuple[float, float, float]
- Description: The center (x, y, z) coordinates of the box.
size
- Type: tuple[float, float, float]
- Description: The dimensions (width, height, depth) of the box.

Methods

Box.to_sphere() → Sphere

Calculates and returns a Sphere instance that minimally encloses this box.

Returns:: The bounding sphere.
Return type:: Sphere

Sphere Class

The Sphere class defines a sphere by its center and radius.

class Sphere(center: tuple[float, float, float] = None, radius: float = None)

Initializes a Sphere instance.

Parameters:

center (tuple[float, float, float], optional) – A tuple (x, y, z) representing the center of the sphere.
radius (float, optional) – The radius of the sphere.

Properties

center
- Type: tuple[float, float, float]
- Description: The center (x, y, z) coordinates of the sphere.
radius
- Type: float
- Description: The radius of the sphere.

Methods

Sphere.to_box() → Box

Calculates and returns an axis-aligned Box instance that minimally encloses this sphere.

Returns:: The bounding box.
Return type:: Box