Merge pull request #519 from padix-key/doc

Update documentation

Author: padix-key

.gitignore

@@ -23,6 +23,7 @@ htmlcov
 # Ignore autogenerated example gallery
 /doc/examples/gallery
 /doc/examples/backreferences
+/doc/sg_execution_times.rst
 
 # Ignore autogenerated tutorial
 /doc/tutorial/target

doc/conf.py

@@ -164,6 +164,7 @@
     "doc_module"                : ("biotite",),
     # Set the NCBI API key
     "reset_modules"             : (key.set_ncbi_api_key_from_env,),
+    "remove_config_comments": True,
 }
 
 

doc/examples/scripts/structure/biological_assembly.py

@@ -75,5 +75,6 @@
 temp = NamedTemporaryFile(suffix=".cif")
 strucio.save_structure(temp.name, biological_unit)
 # Visualization with PyMOL...
+# sphinx_gallery_pymol_image
 
 temp.close()

doc/examples/scripts/structure/contact_sites.py

@@ -7,7 +7,7 @@
 *In contact* is defined as a pairwise atom distance below a given
 threshold (in this case 4.0 Å).
 
-The identified contact residues are highlighted as sticks. 
+The identified contact residues are highlighted as sticks.
 """
 
 # Code source: Patrick Kunzmann
@@ -77,4 +77,5 @@
     res_name = protein_l.res_name[protein_l.res_id == res_id][0]
     print(res_name.capitalize() + str(res_id))
 
-# Visualization with PyMOL...
+# Visualization with PyMOL...
+# sphinx_gallery_pymol_image

doc/examples/scripts/structure/docking.py

@@ -99,11 +99,11 @@
 ref_ligand = ref_ligand[info.standardize_order(ref_ligand)]
 
 # Calculate the RMSD of the docked models to the correct binding mode
-# No superimposition prior to RMSD calculation, as we want to see 
+# No superimposition prior to RMSD calculation, as we want to see
 # conformation differences with respect to the binding pocket
 rmsd = struc.rmsd(ref_ligand, docked_ligand)
 
-# Evaluate correlation between RMSD and binding energies 
+# Evaluate correlation between RMSD and binding energies
 correlation, p_value = spearmanr(energies, rmsd)
 
 figure, ax = plt.subplots(figsize=(8.0, 6.0))
@@ -133,7 +133,7 @@
 # with the lowest RMSD in this case.
 # The docked conformation is shown as ball-and-stick model, the original
 # experimentally determined biotin conformation is shown in transparent
-# blue. 
+# blue.
 
 
 # Get the best fitting model,
@@ -146,5 +146,6 @@
 ref_ligand = ref_ligand[ref_ligand.element!= "H"]
 docked_ligand = docked_ligand[docked_ligand.element!= "H"]
 
+# Visualization with PyMOL...
 # sphinx_gallery_thumbnail_number = 2
-# Visualization with PyMOL...
+# sphinx_gallery_pymol_image

doc/examples/scripts/structure/leaflet.py

@@ -54,15 +54,15 @@ def find_leaflets(structure, head_atom_mask,
     periodic : bool, optional,
         If true, periodic boundary conditions are considered.
         This requires that `structure` has an associated `box`.
-    
+
     Returns
     -------
     leaflets : ndarray, dtype=bool, shape=(m,n)
         Multiple boolean masks, one for each identified leaflet.
         Each masks indicates which atoms of the input `structure`
         are in the leaflet.
     """
-    
+
     cell_list = struc.CellList(
         structure, cell_size=cutoff_distance, selection=head_atom_mask,
         periodic=periodic
@@ -75,7 +75,7 @@ def find_leaflets(structure, head_atom_mask,
                      # This also removes all entries
                      # for atoms not in 'head_atom_mask'
                      if len(c) > 1]
-    
+
     # 'leaflets' contains indices to head atoms
     # Broadcast each head atom index to all atoms in its corresponding
     # residue
@@ -112,5 +112,6 @@ def find_leaflets(structure, head_atom_mask,
 temp = NamedTemporaryFile(suffix=".pdb")
 strucio.save_structure(temp.name, structure)
 # Visualization with PyMOL...
+# sphinx_gallery_pymol_image
 
 temp.close()

doc/examples/scripts/structure/normal_modes.py

@@ -85,7 +85,7 @@
 # Rescale, so that the largest vector has the length 'MAX_AMPLITUDE'
 vector_lenghts = np.sqrt(np.sum(mode_vectors**2, axis=-1))
 scale = MAX_AMPLITUDE / np.max(vector_lenghts)
-mode_vectors *= scale 
+mode_vectors *= scale
 
 
 # Stepwise application of eigenvectors as smooth sine oscillation
@@ -111,6 +111,6 @@
 # Save as PDB for rendering a video with PyMOL
 temp = NamedTemporaryFile(suffix=".pdb")
 strucio.save_structure(temp.name, oscillating_structure)
-# biotite_static_image = normal_modes.gif
+# sphinx_gallery_static_image = "normal_modes.gif"
 
 temp.close()

doc/examples/scripts/structure/peptide_assembly.py

@@ -42,8 +42,8 @@
 # Reference peptide bond atom coordinates taken from 1l2y:
 # CA, C, N, O, H
 peptide_coord = np.array([
-    [-8.608, 3.135, -1.618], 
-    [-7.117, 2.964, -1.897],  
+    [-8.608, 3.135, -1.618],
+    [-7.117, 2.964, -1.897],
     [-6.379, 4.031, -2.228],
     [-6.634, 1.849, -1.758],
     [-6.821, 4.923, -2.394]
@@ -95,7 +95,7 @@ def append_residue(chain, residue):
         return residue
 
     last_res_id = chain.res_id[-1]
-    
+
     # Remove atoms removed by peptide bond
     chain = chain[
         (chain.res_id != last_res_id) |
@@ -125,8 +125,8 @@ def append_residue(chain, residue):
 # Reference peptide bond atom coordinates taken from 1l2y:
 # CA, C, N, O, H
 peptide_coord = np.array([
-    [-8.608, 3.135, -1.618], 
-    [-7.117, 2.964, -1.897],  
+    [-8.608, 3.135, -1.618],
+    [-7.117, 2.964, -1.897],
     [-6.379, 4.031, -2.228],
     [-6.634, 1.849, -1.758],
     [-6.821, 4.923, -2.394]
@@ -178,7 +178,7 @@ def append_residue(chain, residue):
         return residue
 
     last_res_id = chain.res_id[-1]
-    
+
     # Remove atoms removed by peptide bond
     chain = chain[
         (chain.res_id != last_res_id) |
@@ -217,14 +217,14 @@ def assemble_peptide(sequence):
     chain = struc.AtomArray(0)
     for i, res_name in enumerate(res_names):
         residue = info.residue(res_name)
-        
-        # Superimpose residue to corresponding backbone coordinates 
+
+        # Superimpose residue to corresponding backbone coordinates
         _, transformation = struc.superimpose(
             backbone_coord[3*i : 3*i + 3],
             residue.coord[np.isin(residue.atom_name, ["N", "CA", "C"])]
         )
         residue = struc.superimpose_apply(residue, transformation)
-        
+
         chain = append_residue(chain, residue)
 
         if i != 0:
@@ -253,5 +253,6 @@ def assemble_peptide(sequence):
 out_file = NamedTemporaryFile(suffix=".mmtf", delete=False)
 strucio.save_structure(out_file.name, chain)
 # Visualization with PyMOL...
+# sphinx_gallery_pymol_image
 
 out_file.close()

doc/index.rst

@@ -22,7 +22,7 @@ This package bundles popular tasks in computational molecular biology
 into a uniform *Python* library.
 It can handle a major part of the typical workflow
 for sequence and biomolecular structure data:
-   
+
    - Searching and fetching data from biological databases
    - Reading and writing popular sequence/structure file formats
    - Analyzing and editing sequence/structure data
@@ -40,11 +40,13 @@ As a result the user can skip writing code for basic functionality (like
 file parsers) and can focus on what their code makes unique - from
 small analysis scripts to entire bioinformatics software packages.
 
-If you use *Biotite* in a scientific publication, please cite:
+If you use *Biotite* in a scientific publication, please cite one of the
+following articles:
 
 .. bibliography::
 
    Kunzmann2018
+   Kunzmann2023
 
 ----
 
@@ -134,7 +136,7 @@ databases, including the arguably most important ones: the *RCSB PDB* and the
 .. toctree::
    :maxdepth: 1
    :hidden:
-   
+
    install
    tutorial/target/index
    apidoc/index

doc/references.bib

@@ -196,7 +196,7 @@ @article{Daniloski2021
 }
 
 @article{Edgar2021,
-  title = {Syncmers Are More Sensitive than Minimizers for Selecting Conserved K-mers in Biological Sequences},
+  title = {Syncmers Are More Sensitive than Minimizers for Selecting Conserved K‑mers in Biological Sequences},
   author = {Edgar, Robert},
   year = {2021},
   month = feb,
@@ -248,7 +248,7 @@ @article{Frith2011
 
 @article{Gabb1996,
   title = {Finding and Visualizing Nucleic Acid Base Stacking},
-  author = {Gabb, H. A. and Sanghani, S. R. and Robert, C. H. and Pr{\'e}vost, C.},
+  author = {Gabb, H. A. and Sanghani, S. R. and Robert, C. H. and Prévost, C.},
   year = {1996},
   month = feb,
   journal = {Journal of Molecular Graphics},
@@ -260,7 +260,7 @@ @article{Gabb1996
 }
 
 @article{Gasteiger1980,
-  title = {Iterative Partial Equalization of Orbital Electronegativity{\textemdash}a Rapid Access to Atomic Charges},
+  title = {Iterative Partial Equalization of Orbital Electronegativity—a Rapid Access to Atomic Charges},
   author = {Gasteiger, Johann and Marsili, Mario},
   year = {1980},
   month = jan,
@@ -274,7 +274,7 @@ @article{Gasteiger1980
 
 @article{Gibrat2018,
   title = {A Short Note on Dynamic Programming in a Band},
-  author = {Gibrat, Jean-Fran{\c c}ois},
+  author = {Gibrat, Jean-François},
   year = {2018},
   month = jun,
   journal = {BMC Bioinformatics},
@@ -301,7 +301,7 @@ @article{Gotoh1982
 @article{Hauser2013,
   title = {{{kClust}}: Fast and Sensitive Clustering of Large Protein Sequence Databases},
   shorttitle = {{{kClust}}},
-  author = {Hauser, Maria and Mayer, Christian E. and S{\"o}ding, Johannes},
+  author = {Hauser, Maria and Mayer, Christian E. and Söding, Johannes},
   year = {2013},
   month = aug,
   journal = {BMC Bioinformatics},
@@ -315,7 +315,7 @@ @article{Hauser2013
 @article{Hess2014,
   title = {Serious Games for Solving Protein Sequence Alignments - {{Combining}} Citizen Science and Gaming},
   author = {Hess, Martin and Wiemeyer, Josef and Hamacher, Kay and Goesele, Michael},
-  editor = {G{\"o}bel, Stefan and Wiemeyer, Josef},
+  editor = {Göbel, Stefan and Wiemeyer, Josef},
   year = {2014},
   journal = {Games for Training, Education, Health and Sports},
   series = {Lecture {{Notes}} in {{Computer Science}}},
@@ -345,15 +345,6 @@ @article{Iyamu2023
   issn = {2235-2988}
 }
 
-@article{iyamuConservedEpitopeVAR2CSA2023,
-  title = {A Conserved Epitope in {{VAR2CSA}} Is Targeted by a Cross-Reactive Antibody Originating from {{Plasmodium}} Vivax {{Duffy}} Binding Protein},
-  author = {Iyamu, Uwa and Vinals, Daniel Ferrer and Tornyigah, Bernard and Arango, Eliana and Bhat, Rakesh and Adra, Trixie Rae and Grewal, Simranjit and Martin, Kimberly and Maestre, Amanda and Overduin, Michael and Hazes, Bart and Yanow, Stephanie K.},
-  year = {2023},
-  journal = {Frontiers in Cellular and Infection Microbiology},
-  volume = {13},
-  issn = {2235-2988}
-}
-
 @article{Kabsch1976,
   title = {A Solution for the Best Rotation to Relate Two Sets of Vectors},
   author = {Kabsch, W.},
@@ -399,7 +390,7 @@ @article{Kim2018
 }
 
 @article{Kojoma2006,
-  title = {{{DNA}} Polymorphisms in the Tetrahydrocannabinolic Acid ({{THCA}}) Synthase Gene in ``Drug-Type'' and ``Fiber-Type'' {{Cannabis}} Sativa {{L}}.},
+  title = {{{DNA}} Polymorphisms in the Tetrahydrocannabinolic Acid ({{THCA}}) Synthase Gene in “Drug-Type” and “Fiber-Type” {{Cannabis}} Sativa {{L}}.},
   author = {Kojoma, Mareshige and Seki, Hikaru and Yoshida, Shigeo and Muranaka, Toshiya},
   year = {2006},
   month = jun,
@@ -438,8 +429,23 @@ @article{Kunzmann2020
   doi = {10.1186/s12859-020-3526-6}
 }
 
+@article{Kunzmann2023,
+  title = {Biotite: New Tools for a Versatile {{Python}} Bioinformatics Library},
+  shorttitle = {Biotite},
+  author = {Kunzmann, Patrick and Müller, Tom David and Greil, Maximilian and Krumbach, Jan Hendrik and Anter, Jacob Marcel and Bauer, Daniel and Islam, Faisal and Hamacher, Kay},
+  year = {2023},
+  month = dec,
+  journal = {BMC Bioinformatics},
+  volume = {24},
+  number = {1},
+  pages = {1--19},
+  publisher = {{BioMed Central}},
+  issn = {1471-2105},
+  doi = {10.1186/s12859-023-05345-6}
+}
+
 @article{Labesse1997,
-  title = {P-{{SEA}}: A New Efficient Assignment of Secondary Structure from {{C$\alpha$}} Trace of Proteins},
+  title = {P-{{SEA}}: A New Efficient Assignment of Secondary Structure from {{Cα}} Trace of Proteins},
   shorttitle = {P-{{SEA}}},
   author = {Labesse, G. and Colloc'h, N. and Pothier, J. and Mornon, J.-P.},
   year = {1997},
@@ -551,7 +557,7 @@ @article{Martin2005
 
 @article{Meija2016,
   title = {Atomic Weights of the Elements 2013 ({{IUPAC Technical Report}})},
-  author = {Meija, Juris and Coplen, Tyler B. and Berglund, Michael and Brand, Willi A. and Bi{\`e}vre, Paul De and Gr{\"o}ning, Manfred and Holden, Norman E. and Irrgeher, Johanna and Loss, Robert D. and Walczyk, Thomas and Prohaska, Thomas},
+  author = {Meija, Juris and Coplen, Tyler B. and Berglund, Michael and Brand, Willi A. and Bièvre, Paul De and Gröning, Manfred and Holden, Norman E. and Irrgeher, Johanna and Loss, Robert D. and Walczyk, Thomas and Prohaska, Thomas},
   year = {2016},
   month = mar,
   journal = {Pure and Applied Chemistry},
@@ -741,7 +747,7 @@ @article{Steele2021
 
 @article{Steinegger2017,
   title = {{{MMseqs2}} Enables Sensitive Protein Sequence Searching for the Analysis of Massive Data Sets},
-  author = {Steinegger, Martin and S{\"o}ding, Johannes},
+  author = {Steinegger, Martin and Söding, Johannes},
   year = {2017},
   month = nov,
   journal = {Nature Biotechnology},
@@ -807,7 +813,7 @@ @article{Tsai1999
 }
 
 @article{Tyler2018,
-  title = {Evaluation of {{Oxford Nanopore}}'s {{MinION}} Sequencing Device for Microbial Whole Genome Sequencing Applications},
+  title = {Evaluation of {{Oxford Nanopore}}’s {{MinION}} Sequencing Device for Microbial Whole Genome Sequencing Applications},
   author = {Tyler, Andrea D. and Mataseje, Laura and Urfano, Chantel J. and Schmidt, Lisa and Antonation, Kym S. and Mulvey, Michael R. and Corbett, Cindi R.},
   year = {2018},
   month = jul,
@@ -875,7 +881,7 @@ @article{Yang2003
 @article{Yates2022,
   title = {Ensembl {{Genomes}} 2022: An Expanding Genome Resource for Non-Vertebrates},
   shorttitle = {Ensembl {{Genomes}} 2022},
-  author = {Yates, Andrew~D and Allen, James and Amode, Ridwan M and Azov, Andrey G and Barba, Matthieu and Becerra, Andr{\'e}s and Bhai, Jyothish and Campbell, Lahcen~I and Carbajo~Martinez, Manuel and Chakiachvili, Marc and Chougule, Kapeel and Christensen, Mikkel and {Contreras-Moreira}, Bruno and Cuzick, Alayne and Da~Rin~Fioretto, Luca and Davis, Paul and De~Silva, Nishadi~H and Diamantakis, Stavros and Dyer, Sarah and Elser, Justin and Filippi, Carla V and Gall, Astrid and Grigoriadis, Dionysios and {Guijarro-Clarke}, Cristina and Gupta, Parul and {Hammond-Kosack}, Kim~E and Howe, Kevin L and Jaiswal, Pankaj and Kaikala, Vinay and Kumar, Vivek and Kumari, Sunita and Langridge, Nick and Le, Tuan and Luypaert, Manuel and Maslen, Gareth L and Maurel, Thomas and Moore, Benjamin and Muffato, Matthieu and Mushtaq, Aleena and Naamati, Guy and Naithani, Sushma and Olson, Andrew and Parker, Anne and Paulini, Michael and Pedro, Helder and Perry, Emily and Preece, Justin and {Quinton-Tulloch}, Mark and Rodgers, Faye and Rosello, Marc and Ruffier, Magali and Seager, James and Sitnik, Vasily and Szpak, Michal and Tate, John and {Tello-Ruiz}, Marcela~K and Trevanion, Stephen~J and Urban, Martin and Ware, Doreen and Wei, Sharon and Williams, Gary and Winterbottom, Andrea and Zarowiecki, Magdalena and Finn, Robert~D and Flicek, Paul},
+  author = {Yates, Andrew~D and Allen, James and Amode, Ridwan M and Azov, Andrey G and Barba, Matthieu and Becerra, Andrés and Bhai, Jyothish and Campbell, Lahcen~I and Carbajo~Martinez, Manuel and Chakiachvili, Marc and Chougule, Kapeel and Christensen, Mikkel and {Contreras-Moreira}, Bruno and Cuzick, Alayne and Da~Rin~Fioretto, Luca and Davis, Paul and De~Silva, Nishadi~H and Diamantakis, Stavros and Dyer, Sarah and Elser, Justin and Filippi, Carla V and Gall, Astrid and Grigoriadis, Dionysios and {Guijarro-Clarke}, Cristina and Gupta, Parul and {Hammond-Kosack}, Kim~E and Howe, Kevin L and Jaiswal, Pankaj and Kaikala, Vinay and Kumar, Vivek and Kumari, Sunita and Langridge, Nick and Le, Tuan and Luypaert, Manuel and Maslen, Gareth L and Maurel, Thomas and Moore, Benjamin and Muffato, Matthieu and Mushtaq, Aleena and Naamati, Guy and Naithani, Sushma and Olson, Andrew and Parker, Anne and Paulini, Michael and Pedro, Helder and Perry, Emily and Preece, Justin and {Quinton-Tulloch}, Mark and Rodgers, Faye and Rosello, Marc and Ruffier, Magali and Seager, James and Sitnik, Vasily and Szpak, Michal and Tate, John and {Tello-Ruiz}, Marcela~K and Trevanion, Stephen~J and Urban, Martin and Ware, Doreen and Wei, Sharon and Williams, Gary and Winterbottom, Andrea and Zarowiecki, Magdalena and Finn, Robert~D and Flicek, Paul},
   year = {2022},
   month = jan,
   journal = {Nucleic Acids Research},