proteindf_bridge.atomgroup module¶

class proteindf_bridge.atomgroup.AtomGroup(*args, **kwargs)¶

Bases: object

A hierarchical tree representation of molecular structures.

An AtomGroup represents a node in a molecular hierarchy containing child groups (AtomGroup) and atoms (Atom). Child groups typically represent structural units such as models, chains, or residues, while atoms represent the individual atomic sites.

Objects retrieved from the tree (via indexing, get_group(), or get_atom()) are direct references to the nodes within the tree; modifying them mutates the tree in-place. Conversely, inserting objects via set_group() or set_atom() deep-copies the provided objects into the tree.

The constructor accepts: - A group name string (e.g. AtomGroup("model_1") or AtomGroup(name="model_1")). - Another AtomGroup to clone (e.g. AtomGroup(other_group)). - A dictionary representing raw tree data (e.g. AtomGroup(raw_dict)). - No arguments (creates an empty group with default settings).

add_bond(atom1, atom2, order=1)¶

Registers a chemical bond between two atoms in the group hierarchy.

The bond is stored at the lowest common ancestor group of the two atoms.

Parameters:

atom1 (Atom) – The first atom.
atom2 (Atom) – The second atom.
order (int, optional) – The bond order (1 for single, 2 for double, etc.). Defaults to 1.

add_missing_hydrogens(db=None)¶

Adds missing hydrogen atoms based on CCD residue templates.

Parameters:: db (Optional[CcdTemplateDb], optional) – The CCD template database to use. If None, the global default database is used. Defaults to None.
Returns:: Summary report of added hydrogens.
Return type:: OverallHydrogenationReport

apply_secondary_structure()¶

Detects and assigns secondary structure annotations (‘H’, ‘E’, ‘-’) to residues in this chain.

Modifications are applied in-place to residue groups.

assign_charges(charges)¶

Sequentially assigns partial charges from a sequence to all atoms in the hierarchy.

The number of values in charges must exactly match the total atom count.

Parameters:

charges (Sequence[float]) – An iterable of numerical charge values.

Raises:

TypeError – If charges is not a valid sequence.
ValueError – If the length of charges does not match the total atom count.

atoms()¶

Returns a list of (key, atom) pairs for all atoms directly in this group.

If sort_atoms is set to "nice", the items are sorted naturally.

Returns:: List of (key, atom) pairs.
Return type:: List[Tuple[str, Atom]]

bonds()¶

Returns a list of bond records stored directly in this group.

Returns:: List of (atom1_path, atom2_path, order) tuples.
Return type:: List[Tuple[str, str, int]]

box()¶

Computes the axis-aligned bounding box enclosing all atoms in the hierarchy.

Returns:: A tuple of (min_position, max_position).
Return type:: Tuple[Position, Position]

center()¶

Computes the geometric center (centroid) of all atoms in the hierarchy.

Returns:: The centroid coordinates.
Return type:: Position

charge¶

Total electric charge of this group and all its descendant groups.

Returns:: Sum of atomic partial charges.
Return type:: float

del_atom(key)¶

Removes an atom with the given key from this group.

Parameters:: key (Union[str, int]) – The atom key to remove.
Returns:: The removed atom, or None if not found.
Return type:: Optional[Atom]

del_group(key)¶

Removes a child group with the given key from this group.

Parameters:: key (Union[str, int]) – The child group key to remove.
Returns:: The removed child group, or None if not found.
Return type:: Optional[AtomGroup]

static divide_path(path)¶

Splits a hierarchical path string into individual component strings.

Parameters:: path (Union[str, int]) – The path string to split.
Returns:: List of path segment strings.
Return type:: List[str]

erase_atom(key)¶

Removes an atom with the given key from this group.

Deprecated since version Use: remove_atom() instead.

Parameters:: key (Union[str, int]) – The atom key to remove.

erase_group(key)¶

Removes a child group with the given key from this group.

Deprecated since version Use: remove_group() instead.

Parameters:: key (Union[str, int]) – The child group key to remove.

formula()¶

Returns the chemical formula formatted using the Hill system.

Alias for get_formula().

Returns:: The Hill-system chemical formula.
Return type:: str

get_atom(key)¶

Retrieves an atom matching the given key or name from this group.

Parameters:: key (Union[str, int]) – The atom key or name to search for.
Returns:: The matching atom reference, or None if not found.
Return type:: Optional[Atom]

get_atom_keys()¶

Returns a list of keys of all direct atoms.

If sort_atoms is set to "nice", the keys are sorted naturally.

Returns:: List of atom keys.
Return type:: List[str]

get_atom_kinds()¶

Returns a set of unique chemical element symbols present in the hierarchy.

Returns:: Set of element symbols (e.g. {“C”, “H”, “N”, “O”}).
Return type:: Set[str]

get_atom_kinds_count()¶

Returns a dictionary mapping element symbols to their occurrence counts.

Returns:: Counts of each chemical element.
Return type:: Dict[str, int]

get_atom_list()¶

Recursively collects and returns all atoms in this group and all descendant groups.

Returns:: Flat list of all atoms in the hierarchy.
Return type:: List[Atom]

get_bond_list()¶

Returns a list of all bonds in this group and all its descendant groups.

Returns:: List of (atom1_path, atom2_path, order) tuples.
Return type:: List[Tuple[str, str, int]]

get_box()¶

Computes the axis-aligned bounding box enclosing all atoms in the hierarchy.

Alias for box().

Returns:: A tuple of (min_position, max_position).
Return type:: Tuple[Position, Position]

get_family(query_path)¶

Navigates the hierarchy tree and retrieves the group matching an absolute path.

Searches descendants first; if not found within the subtree, traverses up through ancestor groups to search the tree. Does not support relative paths (such as "." or "..").

Parameters:: query_path (Union[str, int]) – The absolute path to navigate to (e.g. "/protein/chainA").
Returns:: The matched group, or None if not found.
Return type:: Optional[AtomGroup]

get_formula()¶

Computes the chemical formula formatted using the Hill system.

If carbon is present, carbon is listed first, followed by hydrogen, and then all other elements in alphabetical order. Otherwise, all elements are listed in alphabetical order.

Returns:: The Hill-system chemical formula (e.g. “C6H12O6”).
Return type:: str

get_group(key)¶

Retrieves a child group matching the given key or name from this group.

Parameters:: key (Union[str, int]) – The child group key or name.
Returns:: The child group reference, or None if not found.
Return type:: Optional[AtomGroup]

get_group_list()¶

Returns a list of keys of all direct child groups.

If sort_groups is set to "nice", the keys are sorted naturally.

Returns:: List of child group keys.
Return type:: List[str]

get_number_of_all_atoms()¶

Returns the total number of atoms in this group and all its descendant groups.

Returns:: Total number of atoms across the entire sub-tree.
Return type:: int

get_number_of_atoms()¶

Returns the number of direct atoms contained in this group.

Returns:: Number of direct atoms.
Return type:: int

get_number_of_bonds()¶

Returns the number of bonds stored directly in this group.

Returns:: Number of direct bonds.
Return type:: int

get_number_of_groups()¶

Returns the number of direct child groups contained in this group.

Returns:: Number of direct child groups.
Return type:: int

get_path_list()¶

Recursively collects and returns the paths of all atoms in this group and descendant groups.

Returns:: List of full paths for all atoms in the hierarchy.
Return type:: List[str]

get_raw_data()¶

Serializes the hierarchy tree into a nested dictionary representation.

Returns:: Nested dictionary containing group and atom data.
Return type:: dict

get_xyz()¶

Generates an XYZ-format coordinate block string for all atoms in the hierarchy.

Returns:: Multi-line XYZ coordinate string.
Return type:: str

groups()¶

Returns a list of (key, group) pairs for all child groups directly in this group.

If sort_groups is set to "nice", the items are sorted naturally.

Returns:: List of (key, group) pairs.
Return type:: List[Tuple[str, AtomGroup]]

has_atom(key)¶

Checks whether an atom matching the given key or name exists in this group.

Parameters:: key (Union[str, int]) – The atom key or name to search for.
Returns:: True if a matching atom is found, False otherwise.
Return type:: bool

has_atomkey(key)¶

Checks whether an atom with the given key exists directly in this group.

Parameters:: key (Union[str, int]) – The atom key.
Returns:: True if an atom with the key exists, False otherwise.
Return type:: bool

has_atomname(name)¶

Checks whether an atom with the given name exists directly in this group.

Parameters:: name (Union[str, int]) – The atom name.
Returns:: True if an atom with the name exists, False otherwise.
Return type:: bool

has_group(key)¶

Checks whether a child group matching the given key or name exists in this group.

Parameters:: key (Union[str, int]) – The child group key or name.
Returns:: True if a matching child group is found, False otherwise.
Return type:: bool

has_groupkey(key)¶

Checks whether a child group with the given key exists directly in this group.

Parameters:: key (Union[str, int]) – The child group key.
Returns:: True if a child group with the key exists, False otherwise.
Return type:: bool

has_groupname(name)¶

Checks whether a child group with the given name exists directly in this group.

Parameters:: name (Union[str, int]) – The child group name.
Returns:: True if a child group with the name exists, False otherwise.
Return type:: bool

is_chain_level()¶

Checks whether this group is at the chain level (path depth 2).

Returns:: True if at chain level, False otherwise.
Return type:: bool

is_model_level()¶

Checks whether this group is at the model level (path depth 1).

Returns:: True if at model level, False otherwise.
Return type:: bool

is_residue_level()¶

Checks whether this group is at the residue level (path depth 3).

Returns:: True if at residue level, False otherwise.
Return type:: bool

merge(other)¶

Merges another AtomGroup hierarchy into this group in-place.

Subgroups and atoms are merged recursively. Existing bonds and secondary structure information from other are also incorporated.

Parameters:: other (AtomGroup) – The atom group to merge into this group.

name¶

Name of this atom group.

Returns:: The group name.
Return type:: str

nuclei_charge¶

Nuclear charge of all atoms in this group and all descendant groups.

For atoms where atomic number is zero, their partial charge is used instead.

Returns:: Total nuclear charge.
Return type:: float

parent¶

Parent AtomGroup in the hierarchy, or None if this is a root group.

Returns:: The parent group reference, or None.
Return type:: Optional[AtomGroup]

path¶

Hierarchical path of this group from the root (e.g. “/model_1/A/”).

Returns:: The hierarchical path.
Return type:: str

path_depth()¶

Returns the depth of this group in the hierarchy.

Returns:: The path depth (0 for root, 1 for model, 2 for chain, 3 for residue).
Return type:: int

pickup_atoms(key_or_name)¶

Recursively searches and collects atoms whose key or name matches the target string.

Parameters:: key_or_name (Union[str, int]) – The atom key or name to match.
Returns:: List of matching atoms found across the hierarchy.
Return type:: List[Atom]

real_nuclei_charge¶

Sum of atomic numbers of all atoms in this group and all descendant groups.

Returns:: Sum of atomic numbers.
Return type:: float

remove_atom(key)¶

Removes an atom with the given key from this group.

Parameters:: key (Union[str, int]) – The atom key to remove.
Returns:: The removed atom, or None if not found.
Return type:: Optional[Atom]

remove_group(key)¶

Removes a child group with the given key from this group.

Parameters:: key (Union[str, int]) – The child group key to remove.
Returns:: The removed child group, or None if not found.
Return type:: Optional[AtomGroup]

restructure(reference, range=1e-05)¶

Reorganizes atoms to match the hierarchy of a reference AtomGroup based on coordinate proximity.

Parameters:

reference (AtomGroup) – Reference structure providing the target hierarchy.
range (float, optional) – Proximity distance threshold in Angstroms. Defaults to 1.0e-5.

Returns:

A new restructured atom group.

Return type:

AtomGroup

rotate(rotmat)¶

Rotates all atomic coordinates in this hierarchy using a 3x3 rotation matrix.

Parameters:

rotmat (Union[Matrix, Any]) – A 3x3 rotation matrix. Accepts a Matrix instance or any object providing rows, cols, and get(row, col).

Raises:

TypeError – If rotmat is not a Matrix or lacks rows, cols, or get.
ValueError – If the dimensions of rotmat are not 3x3.

save_csv(path)¶

Exports the hierarchical atom and group data to a CSV file.

The CSV is written atomically via a temporary file.

Parameters:: path (str) – Destination file path for the CSV file.
Raises:: BrInputError – If file creation, writing, or renaming fails.

secondary_structure¶

Secondary structure code of this residue group (‘H’, ‘E’, ‘-’, or None).

Returns:: ‘H’ for helix, ‘E’ for strand, ‘-’ for loop, or None.
Return type:: Optional[str]

select(selector)¶

Extracts a subset of atoms/groups matching a selector into a new AtomGroup.

Parameters:: selector (Union[Selector, Any]) – A selector object (e.g. SelectSymbol, SelectName, SelectPath, etc.) or any object providing an is_match method.
Returns:: A new atom group containing only the matched components.
Return type:: AtomGroup
Raises:: TypeError – If selector is not a recognized selector type.

set_atom(key, atom)¶

Inserts an atom into this group or at a specified hierarchical path.

If key contains path separators (e.g. "subgroup/C1"), intermediate child groups are created as needed and the atom is inserted at the leaf. The inserted atom is deep-copied into the tree.

Parameters:

key (Union[str, int]) – The atom key or relative/absolute path.
atom (Atom) – The atom to insert.

Raises:

TypeError – If atom is not an Atom instance.

set_by_dict_data(data)¶

Replaces the group content with data loaded from a nested dictionary.

Unrecognized keys at top level are ignored.

Parameters:

data (dict) – Nested dictionary representing tree data.

Returns:

Self, populated with the dictionary data.

Return type:

AtomGroup

Raises:

TypeError – If data is not a dict.
BrValueError – If nested atom data within the dictionary is invalid.

set_group(key, group)¶

Inserts a child group into this group with the specified key.

The inserted group is deep-copied into the tree.

Parameters:

key (Union[str, int]) – The child group key.
group (AtomGroup) – The child group to insert.

Raises:

TypeError – If group is not an AtomGroup instance.

setup()¶

Assigns standard bonds, bond orders, and atom types using the built-in CCD template database.

Raises:: BrValueError – If an atom has an unrecognized symbol or lacks covalent radius data.

setup_with_db(db)¶

Assigns bonds, bond orders, and atom types using a provided CCD template database.

Parameters:: db (CcdTemplateDb) – The Chemical Component Dictionary template database.
Raises:: BrValueError – If an atom has an unrecognized symbol or lacks covalent radius data.

shift_by(dir)¶

Translates all atomic coordinates in this hierarchy by a displacement vector.

Parameters:: dir (Union[Position, str, Sequence[float]]) – The translation displacement vector.
Raises:: TypeError – If dir cannot be converted to a Position.

sort_atoms¶

Sorting mode for direct atoms.

Setting to "nice" enables natural (alphanumeric) sorting of atom keys (e.g. “C1”, “C2”, “C10” instead of alphabetical “C1”, “C10”, “C2”) when accessing atoms. Setting to None maintains insertion order.

Returns:: The sorting mode ("nice" or None).
Return type:: Optional[str]

sort_groups¶

Sorting mode for direct child groups.

Setting to "nice" enables natural (alphanumeric) sorting of group keys (e.g. “res1”, “res2”, “res10” instead of alphabetical “res1”, “res10”, “res2”) when accessing child groups. Setting to None maintains insertion order.

Returns:: The sorting mode ("nice" or None).
Return type:: Optional[str]

sum_of_atomic_number()¶

Returns the sum of atomic numbers of all atoms in this group and descendant groups.

Returns:: Sum of atomic numbers.
Return type:: float

validate_schema()¶

Validates this group against the standard hierarchy schema.

Returns:: A list of detected schema violations.
Return type:: List[SchemaViolation]

weight¶

Total molecular weight of all atoms in this group and descendant groups.

Returns:: Total molecular weight in atomic mass units (Da).
Return type:: float