Chain.jl

docs/src/selections.md

@@ -185,7 +185,7 @@ input, and returns `true` or `false` depending on the conditions required for th
 
 ## Iterate over residues (or molecules)
 
-The `eachresidue` iterator allows iteration over the resiudes of a structure (in PDB files distinct molecules are associated to different residues, thus this iterates similarly over the molecules of a structure). For example:
+The `eachresidue` iterator enables iteration over the residues of a structure. In PDB files, distinct molecules are often treated as separate residues, so this iterator can be used to iterate over the molecules within a structure. For example:
 
 ```jldoctest
 julia> using PDBTools
@@ -198,8 +198,12 @@ julia> count(atom -> resname(atom) == "ALA", protein)
 julia> count(res -> resname(res) == "ALA", eachresidue(protein))
 1
 ```
+Here, the first `count` counts the number of atoms with the residue name "ALA", while the second uses `eachresidue` to count the number of residues named "ALA". This highlights the distinction between residue-level and atom-level operations.
+
+### Collecting Residues into a Vector
+
+Residues produced by `eachresidue` can be collected into a vector for further processing:
 
-The result of the iterator can also be collected, with:
 ```jldoctest
 julia> using PDBTools
 
@@ -220,9 +224,14 @@ julia> residues[1]
       12    O     ALA     A        1        1   -7.083  -13.048   -7.303  1.00  0.00     1    PROT        12
 ```
 
-These residue vector *do not* copy the data from the original atom vector. Therefore, changes performed on these vectors will be reflected on the original data.  
+### Key Note on Residue Vectors
+
+Residue vectors *do not* create copies of the original atom data. This means that any changes made to the residue vector will directly modify the corresponding data in the original atom vector.
+
+### Iterating Over Atoms Within Residues
+
+You can iterate over the atoms of one or more residues using nested loops. For example, to calculate the total mass of all atoms in residues named "ALA":
 
-It is possible also to iterate over the atoms of one or more residue:
 ```julia-repl
 julia> using PDBTools
 
@@ -239,14 +248,14 @@ julia> m_ALA = 0.
        m_ALA
 73.09488999999999
 ```
-Which, in this simple example, results in the same as:
+This method produces the same result as the more concise approaches:
 
 ```julia-repl
 julia> sum(mass(at) for at in protein if resname(at) == "ALA" )
 73.09488999999999
 ```
 
-or
+Or, alternatively:
 
 ```julia-repl
 julia> sum(mass(res) for res in eachresidue(protein) if resname(res) == "ALA" )
@@ -260,6 +269,128 @@ resname
 residuename
 ```
 
+## Iterate over chains
+
+The `eachchain` iterator in PDBTools allows users to iterate over the chains in a PDB structure. A PDB file may contain multiple protein chains, and in some cases, it may also include different models of the same protein. This iterator simplifies operations involving individual chains.
+
+
+```jldoctest
+julia> using PDBTools
+
+julia> ats = read_pdb(PDBTools.CHAINSPDB);
+
+julia> chain.(eachchain(ats))              # Retrieve the names of all chains in the structure
+4-element Vector{InlineStrings.String3}:
+ "A"
+ "B"
+ "C"
+ "A"
+
+julia> model.(eachchain(ats))          # Retrieve the model numbers associated with each chain
+4-element Vector{Int32}:
+ 1
+ 1
+ 1
+ 2
+
+julia> chain_A1 = first(eachchain(ats));   # Access the first chain in the iterator
+
+julia> resname.(eachresidue(chain_A1))     # Retrieve residue names for chain A in model 1
+3-element Vector{InlineStrings.String7}:
+ "ASP"
+ "GLN"
+ "LEU"
+
+julia> chain_A2 = last(eachchain(ats));    # Access the last chain in the iterator
+
+julia> resname.(eachresidue(chain_A2))     # Retrieve residue names for chain A in model 2
+3-element Vector{InlineStrings.String7}:
+ "ASP"
+ "GLN"
+ "VAL"
+
+```
+In the example above, the `chain.` command retrieves the names of all chains in the structure, while  `model.` command lists the model numbers for each chain. This PDB structure contains two models for chain A, where the third residue changes from leucine (LEU) in model 1 to valine (VAL) in model 2.
+
+### Accessing Chains by Index
+
+As seen in the previous example, The `first` and `last` commands allow quick access to the first and last chains in the iterator, respectively. For more specific indexing, you can collect all chains into an array and then use numerical indices to access them.
+
+```julia-repl
+julia> using PDBTools
+
+julia> ats = read_pdb(PDBTools.CHAINSPDB);
+
+julia> chains = collect(eachchain(ats))
+   Array{Chain,1} with 3 chains.
+
+julia> chain_B = chains[2]
+ Chain of name B with 48 atoms.
+   index name resname chain   resnum  residue        x        y        z occup  beta model segname index_pdb
+      49    N     ASP     B        4        4  135.661  123.866  -22.311  1.00  0.00     1    ASYN        49
+      50   CA     ASP     B        4        4  136.539  123.410  -21.227  1.00  0.00     1    ASYN        50
+      51    C     ASP     B        4        4  137.875  122.934  -21.788  1.00  0.00     1    ASYN        51
+                                                       ⋮ 
+      94 HD22     LEU     B        6        6  139.485  119.501  -16.418  1.00  0.00     1    ASYN        94
+      95 HD23     LEU     B        6        6  138.780  120.216  -17.864  1.00  0.00     1    ASYN        95
+      96    O     LEU     B        6        6  141.411  117.975  -21.923  1.00  0.00     1    ASYN        96
+
+```
+
+### Modifying Atom Properties in a Chain
+
+Any changes made to the atoms of a chain variable directly overwrite the properties of the original atoms in the structure. For example, modifying the occupancy and beta-factor columns of atoms in model 2 of chain A will update the corresponding properties in the original structure.
+
+In the example below, the `occup` and `beta` properties of all atoms in model 2 of chain A are set to 0.00. The changes are reflected in the original `ats` vector, demonstrating that the modifications propagate to the parent data structure.
+
+```julia-repl
+julia> using PDBTools
+
+julia> ats = read_pdb(PDBTools.CHAINSPDB);
+
+julia> last(eachchain(ats))
+ Chain of name A with 45 atoms.
+   index name resname chain   resnum  residue        x        y        z occup  beta model segname index_pdb
+     145    N     ASP     A        1       10  133.978  119.386  -23.646  1.00  0.00     2    ASYN         1
+     146   CA     ASP     A        1       10  134.755  118.916  -22.497  1.00  0.00     2    ASYN         2
+     147    C     ASP     A        1       10  135.099  117.439  -22.652  1.00  0.00     2    ASYN         3
+                                                       ⋮ 
+     187 HD22     VAL     A        3       12  130.704  113.003  -27.586  1.00  0.00     2    ASYN        43
+     188 HD23     VAL     A        3       12  130.568  111.868  -26.242  1.00  0.00     2    ASYN        44
+     189    O     VAL     A        3       12  132.066  112.711  -21.739  1.00  0.00     2    ASYN        45
+
+
+julia> for chain in eachchain(ats)
+           if name(chain) == "A" && model(chain) == 2
+               for atom in chain
+               atom.occup = 0.00
+               atom.beta = 0.00
+               end
+           else continue
+           end
+       end
+
+julia> last(eachchain(ats))
+ Chain of name A with 45 atoms.
+   index name resname chain   resnum  residue        x        y        z occup  beta model segname index_pdb
+     145    N     ASP     A        1       10  133.978  119.386  -23.646  0.00  0.00     2    ASYN         1
+     146   CA     ASP     A        1       10  134.755  118.916  -22.497  0.00  0.00     2    ASYN         2
+     147    C     ASP     A        1       10  135.099  117.439  -22.652  0.00  0.00     2    ASYN         3
+                                                       ⋮ 
+     187 HD22     VAL     A        3       12  130.704  113.003  -27.586  0.00  0.00     2    ASYN        43
+     188 HD23     VAL     A        3       12  130.568  111.868  -26.242  0.00  0.00     2    ASYN        44
+     189    O     VAL     A        3       12  132.066  112.711  -21.739  0.00  0.00     2    ASYN        45
+
+
+```
+
+This behavior ensures efficient data manipulation but requires careful handling to avoid unintended changes. 
+
+```@docs
+Chain
+eachchain
+```
+
 ## Using VMD
 
 [VMD](https://www.ks.uiuc.edu/Research/vmd/) is a very popular and