bioAssemblies = StructureIO.getBiologicalAssemblies(pdbId);
+```
## Further Reading
-The RCSB PDB web site has a great [tutorial on Biological Assemblies](http://www.rcsb.org/pdb/101/static101.do?p=education_discussion/Looking-at-Structures/bioassembly_tutorial.html).
+The RCSB PDB web site has a great [tutorial on Biological Assemblies](https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies).
@@ -233,7 +161,7 @@ The RCSB PDB web site has a great [tutorial on Biological Assemblies](http://www
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
+| [Book 3: The Structure Modules](README.md)
| Chapter 9 : Biological Assemblies
Prev: [Chapter 8 : Structure Alignments](alignment.md)
diff --git a/structure/caching.md b/structure/caching.md
index 971e0b5..7be2be1 100644
--- a/structure/caching.md
+++ b/structure/caching.md
@@ -20,7 +20,7 @@ is the same as
```
-## Where are the files getting written to?
+## Where Are the Files Written to?
By default the AtomCache writes all files into a temporary location (The system temp directory "java.io.tempdir").
@@ -31,6 +31,8 @@ you can configure the AtomCache by setting the PDB_DIR system property
-DPDB_DIR=/wherever/you/want/
+BioJava will also check for a `PDB_DIR` environmental variable. If you launch BioJava from the command line, it can be useful to include `export PDB_DIR=/wherever/you/want` in your `.bashrc` file.
+
An alternative is to hard-code the path in this way (but setting it as a property is better style)
```java
@@ -45,16 +47,14 @@ The AtomCache also provides access to configuring various options that are avail
parsing of files. The [FileParsingParameters](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/FileParsingParameters.html)
class is the main place to influence the level of detail and as a consequence the speed with which files can be loaded.
-This example turns on the use of chemical components when loading a structure. (See also the [next chapter](chemcomp.md))
+This example turns on the use of chemical components when loading a `Structure`. (See also the [next chapter](chemcomp.md))
```java
AtomCache cache = new AtomCache();
cache.setPath("/tmp/");
-
+
FileParsingParameters params = cache.getFileParsingParams();
-
- params.setLoadChemCompInfo(true);
StructureIO.setAtomCache(cache);
@@ -78,10 +78,7 @@ The AtomCache not only provides access to PDB, it can also fetch Structure repre
There are quite a number of external database IDs that are supported here. See the
AtomCache documentation for more details on the supported options.
-
-
-
-
+The non-PDB files can be cached at a different location by setting the `PDB_CACHE_DIR` property (with `java -DPDB_CACHE_DIR=...`) or environmental variable.
@@ -89,9 +86,9 @@ There are quite a number of external database IDs that are supported here. See t
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 4 : Local installations
+| [Book 3: The Structure Modules](README.md)
+| Chapter 4 : Local Installations
-Prev: [Chapter 3 : data model](structure-data-model.md)
+Prev: [Chapter 3 : Structure Data Model](structure-data-model.md)
Next: [Chapter 5 : Chemical Component Dictionary](chemcomp.md)
diff --git a/structure/chemcomp.md b/structure/chemcomp.md
index d539de6..92f7538 100644
--- a/structure/chemcomp.md
+++ b/structure/chemcomp.md
@@ -1,22 +1,22 @@
The Chemical Component Dictionary
=================================
-The [Chemical Component Dictionary](http://www.wwpdb.org/ccd.html) is an external reference file describing all residue and small molecule components found in PDB entries. This dictionary contains detailed chemical descriptions for standard and modified amino acids/nucleotides, small molecule ligands, and solvent molecules.
+The [Chemical Component Dictionary](http://www.wwpdb.org/ccd.html) is an external reference file describing all residue and small molecule components found in PDB entries. This dictionary contains detailed chemical descriptions for standard and modified amino acids/nucleotides, small molecule ligands, and solvent molecules.
-### How does BioJava decide what groups are amino acids?
+### How Does BioJava Decide what Groups Are Amino Acids?
BioJava utilizes the Chem. Comp. Dictionary to achieve a chemically correct representation of each group. To make it clear how this can work, let's take a look at how [Selenomethionine](http://en.wikipedia.org/wiki/Selenomethionine) and water is dealt with:
```java
- Structure structure = StructureIO.getStructure("1A62");
-
- for (Chain chain : structure.getChains()){
- for (Group group : chain.getAtomGroups()){
- if ( group.getPDBName().equals("MSE") || group.getPDBName().equals("HOH")){
- System.out.println(group.getPDBName() + " is a group of type " + group.getType());
- }
- }
- }
+Structure structure = StructureIO.getStructure("1A62");
+
+for (Chain chain : structure.getChains()){
+ for (Group group : chain.getAtomGroups()){
+ if ( group.getPDBName().equals("MSE") || group.getPDBName().equals("HOH")){
+ System.out.println(group.getPDBName() + " is a group of type " + group.getType());
+ }
+ }
+}
```
This will give this output:
@@ -33,54 +33,28 @@ HOH is a group of type hetatm
As you can see, although MSE is flaged as HETATM in the PDB file, BioJava still represents it correctly as an amino acid. They key is that the [definition file for MSE](http://www.rcsb.org/pdb/files/ligand/MSE.cif) flags it as "L-PEPTIDE LINKING", which is being used by BioJava.
-
-
+Note: Selenomethionine is a naturally occurring amino acid containing selenium. It has the ID MSE in the Chemical Component Dictionary.
-
+### How to Access Chemical Component Definitions
- |
-
+By default BioJava will retrieve the full chemical component definitions provided by the PDB. That way BioJava makes sure that the user gets a correct representation e.g. distinguish ligands from the polypeptide chain, correctly resolve chemically modified residues, etc.
- Selenomethionine is a naturally occurring amino acid containing selenium. It has the ID MSE in the Chemical Component Dictionary. (image source: wikipedia)
-
-
- |
-
-
-
-
-### How to access Chemical Component definitions
-By default BioJava ships with a minimal representation of standard amino acids, which is useful when you just want to work with atoms and a basic data representation. However if you want to work with a correct representation (e.g. distinguish ligands from the polypeptide chain, correctly resolve chemically modified residues), it is good to tell the library to either
-
-1. fetch missing Chemical Component definitions on the fly (small download and parsing delays every time a new chemical compound is found), or
-2. Load all definitions at startup (slow startup, but then no further delays later on, requires more memory)
-
-You can enable the first behaviour by doing using the [FileParsingParameters](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/FileParsingParameters.html) class:
+The behaviour is configurable by setting a property in the `ChemCompGroupFactory` singleton:
+1. Use a minimal built-in set of **Chemical Component Definitions**. Will only deal with most frequent cases of chemical components. Does not guarantee a correct representation, but it is fast and does not require network access.
```java
- AtomCache cache = new AtomCache();
-
- // by default all files are stored at a temporary location.
- // you can set this either via at startup with -DPDB_DIR=/path/to/files/
- // or hard code it this way:
- cache.setPath("/tmp/");
-
- FileParsingParameters params = new FileParsingParameters();
-
- params.setLoadChemCompInfo(true);
- cache.setFileParsingParams(params);
-
- StructureIO.setAtomCache(cache);
-
- Structure structure = StructureIO.getStructure(...);
+ ChemCompGroupFactory.setChemCompProvider(new ReducedChemCompProvider());
```
-
-If you want to enable the second behaviour (slow loading of all chem comps at startup, but no further small delays later on) you can use the same code but change the behaviour by switching the [ChemCompProvider](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/mmcif/ChemCompProvider.html) implementation in the [ChemCompGroupFactory](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/mmcif/ChemCompGroupFactory.html)
-
+2. Load all **Chemical Component Definitions** at startup (slow startup, but then no further delays later on, requires more memory)
```java
ChemCompGroupFactory.setChemCompProvider(new AllChemCompProvider());
```
+3. Fetch missing **Chemical Component Definitions** on the fly (small download and parsing delays every time a new chemical compound is found). Default behaviour since 4.2.0. Note that the chemical component files are cached in the local file system for subsequent uses.
+```java
+ ChemCompGroupFactory.setChemCompProvider(new DownloadChemCompProvider());
+```
+
@@ -88,9 +62,9 @@ If you want to enable the second behaviour (slow loading of all chem comps at st
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
+| [Book 3: The Structure Modules](README.md)
| Chapter 5 : Chemical Component Dictionary
-Prev: [Chapter 4 : Local installations](caching.md)
+Prev: [Chapter 4 : Local Installations](caching.md)
-Next: [Chapter 6 : work with mmCIF/PDBx files](mmcif.md)
+Next: [Chapter 6 : Work with mmCIF/PDBx Files](mmcif.md)
diff --git a/structure/contact-map.md b/structure/contact-map.md
index db2d16d..bb9236d 100644
--- a/structure/contact-map.md
+++ b/structure/contact-map.md
@@ -9,7 +9,7 @@ Contacts are a useful tool to analyse protein structures. They simplify the 3-Di
## Getting the contact map of a protein chain
-This code snippet will produce the set of contacts between all C alpha atoms for chain A of PDB entry [1SMT](http://www.rcsb.org/pdb/explore.do?structureId=1SMT):
+This code snippet will produce the set of contacts between all C alpha atoms for chain A of PDB entry [1SMT](https://www.rcsb.org/structure/1SMT):
```java
AtomCache cache = new AtomCache();
@@ -29,7 +29,7 @@ This code snippet will produce the set of contacts between all C alpha atoms for
```
-The algorithm to find the contacts uses geometric hashing without need to calculate a full distance matrix, thus it scales nicely.
+The algorithm to find the contacts uses spatial hashing without need to calculate a full distance matrix, thus it scales nicely.
## Getting the contacts between two protein chains
@@ -51,7 +51,7 @@ One can also find the contacting atoms between two protein chains. For instance
```
-See [DemoContacts](https://github.com/biojava/biojava/blob/master/biojava3-structure/src/main/java/demo/DemoContacts.java) for a fully working demo of the examples above.
+See [DemoContacts](https://github.com/biojava/biojava/blob/master/biojava-structure/src/main/java/demo/DemoContacts.java) for a fully working demo of the examples above.
@@ -68,9 +68,9 @@ See [DemoContacts](https://github.com/biojava/biojava/blob/master/biojava3-struc
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 12 : Contacts within a chain and between chains
+| [Book 3: The Structure Modules](README.md)
+| Chapter 12 : Contacts Within a Chain and between Chains
Prev: [Chapter 11 : Accessible Surface Areas](asa.md)
-Next: [Chapter 13 - Finding all interfaces in crystal: crystal contacts](crystal-contacts.md)
+Next: [Chapter 13 - Finding all Interfaces in Crystal: Crystal Contacts](crystal-contacts.md)
diff --git a/structure/crystal-contacts.md b/structure/crystal-contacts.md
index b34e560..f610610 100644
--- a/structure/crystal-contacts.md
+++ b/structure/crystal-contacts.md
@@ -11,7 +11,7 @@ Looking at crystal contacts can also be important in order to assess the quality
## Getting the set of unique contacts in the crystal lattice
-This code snippet will produce a list of all non-redundant interfaces present in the crystal lattice of PDB entry [1SMT](http://www.rcsb.org/pdb/explore.do?structureId=1SMT):
+This code snippet will produce a list of all non-redundant interfaces present in the crystal lattice of PDB entry [1SMT](https://www.rcsb.org/structure/1SMT):
```java
AtomCache cache = new AtomCache();
@@ -42,7 +42,7 @@ The algorithm to find all unique interfaces in the crystal works roughly like th
+ Searches all cells around the original one by applying crystal translations, if any 2 chains in that search is found to contact then the new contact is added to the final list.
+ The search is performend without repeating redundant symmetry operators, making sure that if a contact is found then it is a unique contact.
-See [DemoCrystalInterfaces](https://github.com/biojava/biojava/blob/master/biojava3-structure/src/main/java/demo/DemoCrystalInterfaces.java) for a fully working demo of the example above.
+See [DemoCrystalInterfaces](https://github.com/biojava/biojava/blob/master/biojava-structure/src/main/java/demo/DemoCrystalInterfaces.java) for a fully working demo of the example above.
## Clustering the interfaces
One can also cluster the interfaces based on their similarity. The similarity is measured through contact overlap: number of common contacts over average number of contact in both chains. The clustering can be done as following:
@@ -65,9 +65,9 @@ One can also cluster the interfaces based on their similarity. The similarity is
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 13 - Finding all interfaces in crystal: crystal contacts
+| [Book 3: The Structure Modules](README.md)
+| Chapter 13 - Finding all Interfaces in Crystal: Crystal Contacts
-Prev: [Chapter 12 : Contacts within a chain and between chains](contact-map.md)
+Prev: [Chapter 12 : Contacts Within a Chain and between Chains](contact-map.md)
-Next: [Chapter 16 : Special Cases](special.md)
+Next: [Chapter 14 : Protein Symmetry](symmetry.md)
diff --git a/structure/externaldb.md b/structure/externaldb.md
index cd1c279..e174944 100644
--- a/structure/externaldb.md
+++ b/structure/externaldb.md
@@ -205,7 +205,7 @@ got 4 domains
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
+| [Book 3: The Structure Modules](README.md)
| Chapter 10 : External Databases
Prev: [Chapter 9 : Biological Assemblies](bioassembly.md)
diff --git a/structure/firststeps.md b/structure/firststeps.md
index 1bec86f..ef13be2 100644
--- a/structure/firststeps.md
+++ b/structure/firststeps.md
@@ -1,19 +1,15 @@
First Steps
===========
-## First steps
+## First Steps
The simplest way to load a PDB file is by using the [StructureIO](http://www.biojava.org/docs/api/org/biojava/nbio/structure/StructureIO.html) class.
```java
- public static void main(String[] args){
- try {
- Structure structure = StructureIO.getStructure("4HHB");
- // and let's print out how many atoms are in this structure
- System.out.println(StructureTools.getNrAtoms(structure));
- } catch (Exception e){
- e.printStackTrace();
- }
+ public static void main(String[] args) throws Exception {
+ Structure structure = StructureIO.getStructure("4HHB");
+ // and let's print out how many atoms are in this structure
+ System.out.println(StructureTools.getNrAtoms(structure));
}
```
@@ -40,7 +36,7 @@ If you already have a local PDB installation, you can configure where BioJava sh
-DPDB_DIR=/wherever/you/want/
-## Memory consumption
+## Memory Consumption
Talking about startup properties, it is also good to mention the fact that many PDB entries are large molecules and the default 64k memory allowance for Java applications is not sufficient in many cases. BioJava contains several built-in caches which automatically adjust to the available memory. As such, the more memory you grant your Java applicaiton, the better it can utilize the caches and the better the performance will be. Change the maximum heap space of your Java VM with this startup parameter:
@@ -53,23 +49,17 @@ Talking about startup properties, it is also good to mention the fact that many
If you have the *biojava-structure-gui* module installed, you can quickly visualise a [Structure](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Structure.html) via this:
```java
- public static void main(String[] args){
- try {
-
- Structure struc = StructureIO.getStructure("4hhb");
-
- StructureAlignmentJmol jmolPanel = new StructureAlignmentJmol();
-
- jmolPanel.setStructure(struc);
-
- // send some commands to Jmol
- jmolPanel.evalString("select * ; color chain;");
- jmolPanel.evalString("select *; spacefill off; wireframe off; cartoon on; ");
- jmolPanel.evalString("select ligands; cartoon off; wireframe 0.3; spacefill 0.5; color cpk;");
-
- } catch (Exception e){
- e.printStackTrace();
- }
+ public static void main(String[] args) throws Exception {
+ Structure struc = StructureIO.getStructure("4hhb");
+
+ StructureAlignmentJmol jmolPanel = new StructureAlignmentJmol();
+
+ jmolPanel.setStructure(struc);
+
+ // send some commands to Jmol
+ jmolPanel.evalString("select * ; color chain;");
+ jmolPanel.evalString("select *; spacefill off; wireframe off; cartoon on; ");
+ jmolPanel.evalString("select ligands; cartoon off; wireframe 0.3; spacefill 0.5; color cpk;");
}
```
@@ -86,32 +76,27 @@ This will result in the following view:
-## Asymmetric unit and Biological Assembly
+## Asymmetric Unit and Biological Assembly
By default many people work with the *asymmetric unit* of a protein. However for many studies the correct representation to look at is the *biological assembly* of a protein. You can request it by calling
```java
- public static void main(String[] args){
-
- try {
- Structure structure = StructureIO.getBiologicalAssembly("1GAV");
- // and let's print out how many atoms are in this structure
- System.out.println(StructureTools.getNrAtoms(structure));
- } catch (Exception e){
- e.printStackTrace();
- }
+ public static void main(String[] args) throws Exception {
+ Structure structure = StructureIO.getBiologicalAssembly("1GAV");
+ // and let's print out how many atoms are in this structure
+ System.out.println(StructureTools.getNrAtoms(structure));
}
```
This topic is important, so we dedicated a [whole chapter](bioassembly.md) to it.
-## I loaded a Structure object, what now?
+## I Loaded a Structure Object, What Now?
BioJava provides a number of algorithms and visualisation tools that you can use to further analyse the structure, or look at it. Here a couple of suggestions for further reads:
+ [The BioJava Cookbook for protein structures](http://biojava.org/wiki/BioJava:CookBook#Protein_Structure)
+ How does BioJava [represent the content](structure-data-model.md) of a PDB/mmCIF file?
-+ [How to calculate a protein structure alignment using BioJava](http://biojava.org/wiki/BioJava:CookBook:PDB:align)
++ How to calculate a protein structure alignment using BioJava: [tutorial](alignment.md) or [cookbook](http://biojava.org/wiki/BioJava:CookBook:PDB:align)
+ [How to work with Groups (AminoAcid, Nucleotide, Hetatom)](http://biojava.org/wiki/BioJava:CookBook:PDB:groups)
@@ -123,9 +108,9 @@ BioJava provides a number of algorithms and visualisation tools that you can use
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
+| [Book 3: The Structure Modules](README.md)
| Chapter 2 : First Steps
Prev: [Chapter 1 : Installation](installation.md)
-Next: [Chapter 3 : data model](structure-data-model.md)
+Next: [Chapter 3 : Structure Data Model](structure-data-model.md)
diff --git a/structure/img/multiple_gui.png b/structure/img/multiple_gui.png
new file mode 100644
index 0000000..aee96a8
Binary files /dev/null and b/structure/img/multiple_gui.png differ
diff --git a/structure/img/multiple_jmol_globins.png b/structure/img/multiple_jmol_globins.png
new file mode 100644
index 0000000..445528a
Binary files /dev/null and b/structure/img/multiple_jmol_globins.png differ
diff --git a/structure/img/multiple_panel_globins.png b/structure/img/multiple_panel_globins.png
new file mode 100644
index 0000000..dc744e7
Binary files /dev/null and b/structure/img/multiple_panel_globins.png differ
diff --git a/structure/img/symm_combined.png b/structure/img/symm_combined.png
new file mode 100644
index 0000000..84f8f02
Binary files /dev/null and b/structure/img/symm_combined.png differ
diff --git a/structure/img/symm_helical.png b/structure/img/symm_helical.png
new file mode 100644
index 0000000..0edaff7
Binary files /dev/null and b/structure/img/symm_helical.png differ
diff --git a/structure/img/symm_hierarchy.png b/structure/img/symm_hierarchy.png
new file mode 100644
index 0000000..21acb72
Binary files /dev/null and b/structure/img/symm_hierarchy.png differ
diff --git a/structure/img/symm_internal.png b/structure/img/symm_internal.png
new file mode 100644
index 0000000..af9a219
Binary files /dev/null and b/structure/img/symm_internal.png differ
diff --git a/structure/img/symm_local.png b/structure/img/symm_local.png
new file mode 100644
index 0000000..7e7eb84
Binary files /dev/null and b/structure/img/symm_local.png differ
diff --git a/structure/img/symm_pg.png b/structure/img/symm_pg.png
new file mode 100644
index 0000000..521afc5
Binary files /dev/null and b/structure/img/symm_pg.png differ
diff --git a/structure/img/symm_pseudo.png b/structure/img/symm_pseudo.png
new file mode 100644
index 0000000..417db56
Binary files /dev/null and b/structure/img/symm_pseudo.png differ
diff --git a/structure/img/symm_subunits.png b/structure/img/symm_subunits.png
new file mode 100644
index 0000000..ec322a3
Binary files /dev/null and b/structure/img/symm_subunits.png differ
diff --git a/structure/installation.md b/structure/installation.md
index 099cbf7..e585df8 100644
--- a/structure/installation.md
+++ b/structure/installation.md
@@ -16,13 +16,13 @@ As of version 4, BioJava is available in maven central. This is all you would ne
-->
org.biojava
biojava-structure
- 4.0.0
+ 4.2.0
org.biojava
biojava-structure-gui
- 4.0.0
+ 4.2.0
@@ -36,6 +36,25 @@ If you run
on your project, the BioJava dependencies will be automatically downloaded and installed for you.
+### (Optional) Configuration
+
+BioJava can be configured through several properties:
+
+| Property | Description |
+| --- | --- |
+| `PDB_DIR` | Directory for caching structure files from the PDB. Mirrors the PDB's FTP server directory structure, with `PDB_DIR` equivalent to ftp://ftp.wwpdb.org/pub/pdb/. Default: temp directory |
+| `PDB_CACHE_DIR` | Cache directory for other files related to the structure package. Default: temp directory |
+
+These can be set either as java properties or as environmental variables. For example:
+
+```
+# This could be added to .bashrc
+export PDB_DIR=...
+# Or override for a particular execution
+java -DPDB_DIR=... -cp ...
+```
+
+Note that your IDE may ignore `.bashrc` settings, but should have a preference for passing VM arguments.
@@ -43,7 +62,7 @@ If you run
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
+| [Book 3: The Structure Modules](README.md)
| Chapter 1 : Installation
Next: [Chapter 2 : First Steps](firststeps.md)
diff --git a/structure/lists.md b/structure/lists.md
index 2c75344..f76d761 100644
--- a/structure/lists.md
+++ b/structure/lists.md
@@ -26,7 +26,7 @@ The following provides information about the status of a PDB entry
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 17 : status information
+| [Book 3: The Structure Modules](README.md)
+| Chapter 18 : Status Information
-Prev: [Chapter 16 : Special Cases](special.md)
+Prev: [Chapter 17 : Special Cases](special.md)
diff --git a/structure/mmcif.md b/structure/mmcif.md
index 9fa069b..769b851 100644
--- a/structure/mmcif.md
+++ b/structure/mmcif.md
@@ -1,4 +1,4 @@
-# How to parse mmCIF files using BioJava
+# How to Parse mmCIF Files using BioJava
A quick tutorial how to work with mmCIF files.
@@ -10,14 +10,17 @@ The Protein Data Bank (PDB) has been distributing its archival files as PDB file
The mmCIF file format has been around for some time (see [Westbrook 2000][] and [Westbrook 2003][] ) [BioJava](http://www.biojava.org) has been supporting mmCIF already for several years. This tutorial is meant to provide a quick introduction into how to parse mmCIF files using [BioJava](http://www.biojava.org)
-## The basics
+## The Basics
-BioJava provides you with both a mmCIF parser and a data model that reads PDB and mmCIF files into a biological and chemically meaningful data model (BioJava supports the [Chemical Components Dictionary](mmcif.md)). If you don't want to use that data model, you can still use BioJava's file parsers, and more on that later, let's start first with the most basic way of loading a protein structure.
+BioJava uses the [CIFTools-java](https://github.com/rcsb/ciftools-java) library to parse mmCIF. BioJava then has its own data model that reads PDB and mmCIF files
+into a biological and chemically meaningful data model (BioJava supports the [Chemical Components Dictionary](chemcomp.md)).
+If you don't want to use that data model, you can still use the CIFTools-java parser, please refer to its documentation.
+Let's start first with the most basic way of loading a protein structure.
-## First steps
+## First Steps
-The simplest way to load a PDB file is by using the [StructureIO](http://www.biojava.org/docs/api/org/biojava/nbio/structure/StructureIO.html) class.
+The simplest way to load a PDBx/mmCIF file is by using the [StructureIO](http://www.biojava.org/docs/api/org/biojava/nbio/structure/StructureIO.html) class.
```java
Structure structure = StructureIO.getStructure("4HHB");
@@ -25,9 +28,7 @@ The simplest way to load a PDB file is by using the [StructureIO](http://www.bio
System.out.println(StructureTools.getNrAtoms(structure));
```
-
-
-BioJava automatically downloaded the PDB file for hemoglobin [4HHB](http://www.rcsb.org/pdb/explore.do?structureId=4HHB) and copied it into a temporary location. This demonstrates two things:
+BioJava automatically downloaded the PDB file for hemoglobin [4HHB](http://www.rcsb.org/pdb/explore.do?structureId=4HHB) and copied it into a temporary location. This demonstrates two things:
+ BioJava can automatically download and install files locally
+ BioJava by default writes those files into a temporary location (The system temp directory "java.io.tempdir").
@@ -38,14 +39,16 @@ If you already have a local PDB installation, you can configure where BioJava sh
-DPDB_DIR=/wherever/you/want/
-## From PDB to mmCIF
+## Switching AtomCache to use different file types
-By default BioJava is using the PDB file format for parsing data. In order to switch it to use mmCIF, we can take control over the underlying [AtomCache](http://www.biojava.org/docs/api/org/biojava/nbio/structure/align/util/AtomCache.html) which manages your PDB ([and btw. also SCOP, CATH](externaldb.md)) installations.
+By default BioJava is using the BCIF file format for parsing data. In order to switch it to use mmCIF, we can take control over
+the underlying [AtomCache](http://www.biojava.org/docs/api/org/biojava/nbio/structure/align/util/AtomCache.html) which
+manages your PDB ([and btw. also SCOP, CATH](externaldb.md)) installations.
```java
AtomCache cache = new AtomCache();
-
- cache.setUseMmCif(true);
+
+ cache.setFiletype(StructureFiletype.CIF);
// if you struggled to set the PDB_DIR property correctly in the previous step,
// you could set it manually like this:
@@ -59,47 +62,43 @@ By default BioJava is using the PDB file format for parsing data. In order to sw
System.out.println(structure.getChains().size());
```
-As you can see, the AtomCache will again download the missing mmCIF file for 4HHB in the background.
+See other supported file types in the `StructureFileType` enum.
-## Low level access
+## URL based parsing of files
-If you want to learn how to use the BioJava mmCIF parser to populate your own data structure, let's first take a look this lower-level code:
+StructureIO can also access files via URLs and fetch the data dynamically. E.g. the following code shows how to load a file from a remote server.
```java
- InputStream inStream = new FileInputStream(fileName);
-
- MMcifParser parser = new SimpleMMcifParser();
-
- SimpleMMcifConsumer consumer = new SimpleMMcifConsumer();
-
- // The Consumer builds up the BioJava - structure object.
- // you could also hook in your own and build up you own data model.
- parser.addMMcifConsumer(consumer);
-
- try {
- parser.parse(new BufferedReader(new InputStreamReader(inStream)));
- } catch (IOException e){
- e.printStackTrace();
- }
-
- // now get the protein structure.
- Structure cifStructure = consumer.getStructure();
+ String u = "http://ftp.wwpdb.org/pub/pdb/data/biounit/mmCIF/divided/nw/4nwr-assembly1.cif.gz";
+ Structure s = StructureIO.getStructure(u);
+ System.out.println(s);
```
-The parser operates similar to a XML parser by triggering "events". The [SimpleMMcifConsumer](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/mmcif/SimpleMMcifConsumer.html) listens to new categories being read from the file and then builds up the BioJava data model.
+### Local URLs
+BioJava can also access local files, by specifying the URL as
+
+
+ file:///path/to/local/file
+
+
+
+## Low Level Access
+
+You can load a BioJava `Structure` object using the ciftools-java parser with:
-To re-use the parser for your own datamodel, just implement the [MMcifConsumer](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/mmcif/MMcifConsumer.html) interface and add it to the [SimpleMMcifParser](http://www.biojava.org/docs/api/org/biojava/nbio/structure/io/mmcif/SimpleMMcifParser.html).
```java
- parser.addMMcifConsumer(myOwnConsumerImplementation);
+ InputStream inStream = new FileInputStream(fileName);
+ // now get the protein structure.
+ Structure cifStructure = CifStructureConverter.fromInputStream(inStream);
```
-## I loaded a Structure object, what now?
+## I Loaded a Structure Object, What Now?
BioJava provides a number of algorithms and visualisation tools that you can use to further analyse the structure, or look at it. Here a couple of suggestions for further reads:
+ [The BioJava Cookbook for protein structures](http://biojava.org/wiki/BioJava:CookBook#Protein_Structure)
+ How does BioJava [represent the content](structure-data-model.md) of a PDB/mmCIF file?
-+ [How to calculate a protein structure alignment using BioJava](http://biojava.org/wiki/BioJava:CookBook:PDB:align)
++ How to calculate a protein structure alignment using BioJava: [tutorial](alignment.md) or [cookbook](http://biojava.org/wiki/BioJava:CookBook:PDB:align)
+ [How to work with Groups (AminoAcid, Nucleotide, Hetatom)](http://biojava.org/wiki/BioJava:CookBook:PDB:groups)
## Further reading
@@ -121,9 +120,9 @@ See the [http://mmcif.rcsb.org/](http://mmcif.rcsb.org/) site for more documenta
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 6 : work with mmCIF/PDBx files
+| [Book 3: The Structure Modules](README.md)
+| Chapter 6 : Work with mmCIF/PDBx Files
Prev: [Chapter 5 : Chemical Component Dictionary](chemcomp.md)
-Next: [Chapter 7 : SEQRES and ATOM records](seqres.md)
+Next: [Chapter 7 : SEQRES and ATOM Records](seqres.md)
diff --git a/structure/secstruc.md b/structure/secstruc.md
new file mode 100644
index 0000000..fbd0f94
--- /dev/null
+++ b/structure/secstruc.md
@@ -0,0 +1,289 @@
+Protein Secondary Structure
+===========================
+
+## What is Protein Secondary Structure?
+
+Protein secondary structure (SS) is the general three-dimensional form of local segments of proteins.
+Secondary structure can be formally defined by the pattern of hydrogen bonds of the protein
+(such as alpha helices and beta sheets) that are observed in an atomic-resolution structure.
+
+More specifically, the secondary structure is defined by the patterns of hydrogen bonds formed between
+amine hydrogen (-NH) and carbonyl oxygen (C=O) atoms contained in the backbone peptide bonds of the protein.
+
+For more info see the Wikipedia article
+on [protein secondary structure](https://en.wikipedia.org/wiki/Protein_secondary_structure).
+
+## Secondary Structure Annotation
+
+### Information Sources
+
+There are various ways to obtain the SS annotation of a protein structure:
+
+- **Authors assignment**: the authors of the structure describe the SS, usually identifying helices
+and beta-sheets, and they assign the corresponding type to each residue involved. The authors assignment
+can be found in the `PDB` and `mmCIF` file formats deposited in the PDB, and it can be parsed in **BioJava**
+when a `Structure` is loaded.
+
+- **Assignment from Atom coordinates**: there exist various programs to assign the SS of a protein.
+The algorithms use the atom coordinates of the aminoacids to determine hydrogen bonds and geometrical patterns
+that define the different types of protein secondary structure. One of the first and most popular algorithms
+is `DSSP` (Dictionary of Secondary Structure of Proteins). **BioJava** has an implementation of the algorithm,
+written originally in C++, which will be described in the next section.
+
+- **Prediction from sequence**: Other algorithms use only the aminoacid sequence (primary structure) of the protein,
+nd predict the SS using the SS propensities of each aminoacid and multiple alignments with homologous sequences
+(i.e. [PSIPRED](http://bioinf.cs.ucl.ac.uk/psipred/)). At the moment **BioJava** does not have an implementation
+of this type, which would be more suitable for the sequence and alignment modules.
+
+### Secondary Structure Types
+
+Following the `DSSP` convention, **BioJava** defines 8 types of secondary structure:
+
+ E = extended strand, participates in β ladder
+ B = residue in isolated β-bridge
+ H = α-helix
+ G = 3-helix (3-10 helix)
+ I = 5-helix (π-helix)
+ T = hydrogen bonded turn
+ S = bend
+ _ = loop (any other type)
+
+## Parsing Secondary Structure in BioJava
+
+Currently there exist two alternatives to parse the secondary structure in **BioJava**: either from the PDB/mmCIF
+files of deposited structures (author assignment) or from the output file of a DSSP prediction. Both file types
+can be obtained from the PDB serevers, if available, so they can be automatically fetched by BioJava.
+
+As an example,you can find here the links of the structure **5PTI** to its
+[PDB file](http://www.rcsb.org/pdb/files/5PTI.pdb) (search for the HELIX and SHEET lines) and its
+[DSSP file](http://www.rcsb.org/pdb/files/5PTI.dssp).
+
+Note that the DSSP prediction output is more detailed and complete than the authors assignment.
+The choice of one or the other will depend on the use case.
+
+Below you can find some examples of how to parse and assign the SS of a `Structure`:
+
+```java
+ String pdbID = "5pti";
+ FileParsingParameters params = new FileParsingParameters();
+ //Only change needed to the normal Structure loading
+ params.setParseSecStruc(true); //this is false as DEFAULT
+
+ AtomCache cache = new AtomCache();
+ cache.setFileParsingParams(params);
+
+ //The loaded Structure contains the SS assigned
+ Structure s = cache.getStructure(pdbID);
+
+ //If the more detailed DSSP prediction is required call this afterwards
+ DSSPParser.fetch(pdbID, s, true); //Second parameter true overrides the previous SS
+```
+
+For more examples search in the **demo** package for `DemoLoadSecStruc`.
+
+## Assignment of Secondary Structure in BioJava
+
+### Algorithm
+
+The algorithm implemented in BioJava for the assignment of SS is `DSSP`. It is described in the paper from
+[Kabsch W. & Sander C. in 1983](http://onlinelibrary.wiley.com/doi/10.1002/bip.360221211/abstract)
+[](http://www.ncbi.nlm.nih.gov/pubmed/6667333).
+A brief explanation of the algorithm and the output format can be found
+[here](http://swift.cmbi.ru.nl/gv/dssp/DSSP_3.html).
+
+The interface is very easy: a single method, named *calculate()*, calculates the SS and can assign it to the
+input Structure overriding any previous annotation, like in the DSSPParser. An example can be found below:
+
+```java
+ String pdbID = "5pti";
+ AtomCache cache = new AtomCache();
+
+ //Load structure without any SS assignment
+ Structure s = cache.getStructure(pdbID);
+
+ //Predict and assign the SS of the Structure
+ SecStrucCalc ssp = new SecStrucCalc(); //Instantiation needed
+ ssp.calculate(s, true); //true assigns the SS to the Structure
+```
+
+BioJava Class:
+[org.biojava.nbio.structure.secstruc.SecStrucCalc](http://www.biojava.org/docs/api/org/biojava/nbio/structure/secstruc/SecStrucCalc.html)
+
+### Storage and Data Structures
+
+Because there are different sources of SS annotation, the data structure in **BioJava** that stores SS assignments
+has two levels. The top level `SecStrucInfo` is very general and only contains two properties: **assignment**
+(String describing the source of information) and **type** the SS type.
+
+However, there is an extended container `SecStrucState`, which is a subclass of `SecStrucInfo`, that stores
+all the information of the hydrogen bonding, turns, bends, etc. used for the SS prediction and present in the
+DSSP output file format. This information is only used in certain applications, and that is the reason for the
+more general `SecStrucInfo` class being used by default.
+
+In order to access the SS information of a `Structure`, the `SecStrucInfo` object needs to be obtained from the
+`Group` properties. Below you find an example of how to access and print residue by residue the SS information of
+a `Structure`:
+
+```java
+ //This structure should have SS assigned (by any of the methods described)
+ Structure s;
+
+ for (Chain c : s.getChains()) {
+ for (Group g: c.getAtomGroups()){
+ if (g.hasAminoAtoms()){ //Only AA store SS
+ //Obtain the object that stores the SS
+ SecStrucInfo ss = (SecStrucInfo) g.getProperty(Group.SEC_STRUC);
+ //Print information: chain+resn+name+SS
+ System.out.println(c.getChainID()+" "+
+ g.getResidueNumber()+" "+
+ g.getPDBName()+" -> "+ss);
+ }
+ }
+ }
+```
+
+### Output Formats
+
+Once the SS has been assigned (either loaded or calculated), there are some easy formats to visualize it in **BioJava**:
+
+- **DSSP format**: the SS can be printed as a DSSP oputput file format, following the standards so that it can be
+parsed again. It is the safest way to serialize a SS annotation and recover it later, but it is probably the most
+complicated to visualize.
+
+
+ # RESIDUE AA STRUCTURE BP1 BP2 ACC N-H-->O O-->H-N N-H-->O O-->H-N TCO KAPPA ALPHA PHI PSI X-CA Y-CA Z-CA
+ 1 1 A R 0 0 168 0, 0.0 54,-0.1 0, 0.0 5,-0.1 0.000 360.0 360.0 360.0 139.2 32.2 14.7 -11.8
+ 2 2 A P > - 0 0 45 0, 0.0 3,-1.8 0, 0.0 4,-0.3 -0.194 360.0-122.0 -61.4 144.9 34.9 13.6 -9.4
+ 3 3 A D G > S+ 0 0 122 1,-0.3 3,-1.6 2,-0.2 4,-0.2 0.790 108.3 71.4 -62.8 -28.5 35.8 10.0 -9.5
+ 4 4 A F G > S+ 0 0 26 1,-0.3 3,-1.7 2,-0.2 -1,-0.3 0.725 83.7 70.4 -64.1 -23.3 35.0 9.7 -5.9
+
+
+- **FASTA format**: simple format that prints the SS type of each residue sequentially in the order of the aminoacids.
+It is the easiest to visualize, but the less informative of all.
+
+
+>5PTI_SS-annotation
+ GGGGS S EEEEEEETTTTEEEEEEE SSS SS BSSHHHHHHHH
+
+
+- **Helix Summary**: similar to the FASTA format, but contain also information about the helical turns.
+
+
+3 turn: >>><<<
+4 turn: >444< >>>>XX<<<<
+5 turn: >5555<
+SS: GGGGS S EEEEEEETTTTEEEEEEE SSS SS BSSHHHHHHHH
+AA: RPDFCLEPPYTGPCKARIIRYFYNAKAGLCQTFVYGGCRAKRNNFKSAEDCMRTCGGA
+
+
+- **Secondary Structure Elements**: another way to visualize the SS annotation is by compacting those sequential residues that share the same SS type and assigning an ID to the range. In this way, a structure can be described by
+a collection of helices, strands, turns, etc. and each one of the elements can be identified by an ID (i.e. helix 1 (H1), beta-strand 6 (E6), etc).
+
+
+G1: 3 - 6
+S1: 7 - 7
+S2: 13 - 13
+E1: 18 - 24
+T1: 25 - 28
+E2: 29 - 35
+S3: 37 - 39
+S4: 42 - 43
+B1: 45 - 45
+S5: 46 - 47
+H1: 48 - 55
+
+
+You can find examples of how to get the different file formats in the class `DemoSecStrucPred` in the **demo**
+package.
+
+### Example
+
+Use dependencies from maven
+
+```xml
+
+ org.biojava
+ biojava-core
+ 4.2.4
+
+
+ org.biojava
+ biojava-modfinder
+ 4.2.4
+
+```
+
+This is taken from the DemoLoadSecStruc example in the **demo** package.
+
+```java
+
+import org.biojava.nbio.structure.Structure;
+import org.biojava.nbio.structure.StructureException;
+import org.biojava.nbio.structure.align.util.AtomCache;
+import org.biojava.nbio.structure.io.FileParsingParameters;
+import org.biojava.nbio.structure.secstruc.DSSPParser;
+import org.biojava.nbio.structure.secstruc.SecStrucCalc;
+import org.biojava.nbio.structure.secstruc.SecStrucInfo;
+import org.biojava.nbio.structure.secstruc.SecStrucTools;
+
+public static void main(String[] args) throws IOException,
+ StructureException {
+
+ String pdbID = "5pti";
+
+ // Only change needed to the DEFAULT Structure loading
+ FileParsingParameters params = new FileParsingParameters();
+ params.setParseSecStruc(true);
+
+ AtomCache cache = new AtomCache();
+ cache.setFileParsingParams(params);
+
+ // Use PDB format, because SS cannot be parsed from mmCIF yet
+ cache.setUseMmCif(false);
+
+ // The loaded Structure contains the SS assigned by Author (simple)
+ Structure s = cache.getStructure(pdbID);
+
+ // Print the Author's assignment (from PDB file)
+ System.out.println("Author's assignment: ");
+ printSecStruc(s);
+
+ // If the more detailed DSSP prediction is required call this
+ DSSPParser.fetch(pdbID, s, true);
+
+ // Print the assignment residue by residue
+ System.out.println("DSSP assignment: ");
+ printSecStruc(s);
+
+ // finally use BioJava's built in DSSP-like secondary structure assigner
+ SecStrucCalc secStrucCalc = new SecStrucCalc();
+
+ // calculate and assign
+ secStrucCalc.calculate(s,true);
+ printSecStruc(s);
+
+ }
+
+ public static void printSecStruc(Structure s){
+ List ssi = SecStrucTools.getSecStrucInfo(s);
+ for (SecStrucInfo ss : ssi) {
+ System.out.println(ss.getGroup().getChain().getName() + " "
+ + ss.getGroup().getResidueNumber() + " "
+ + ss.getGroup().getPDBName() + " -> " + ss.toString());
+ }
+ }
+```
+
+
+
+
+---
+
+Navigation:
+[Home](../README.md)
+| [Book 3: The Structure Modules](README.md)
+| Chapter 15 : Protein Secondary Structure
+
+Prev: [Chapter 14 : Protein Symmetry](symmetry.md)
+
+Next: [Chapter 17 : Special Cases](special.md)
diff --git a/structure/seqres.md b/structure/seqres.md
index cd2a21d..2d03e04 100644
--- a/structure/seqres.md
+++ b/structure/seqres.md
@@ -1,24 +1,23 @@
-SEQRES and ATOM records, mapping to Uniprot (SIFTs)
+SEQRES and ATOM Records, Mapping to Uniprot (SIFTs)
===================================================
How molecular sequences are linked to experimentally observed atoms.
## Sequences and Atoms
-In many experiments not all atoms that are part of the molecule under study can be observed. As such the ATOM records in PDB oftein contain missing atoms or only the part of a molecule that could be experimentally determined. In case of multi-domain proteins the PDB often contains only one of the domains (and in some cases even shorter fragments).
+In many experiments not all atoms that are part of the molecule under study can be observed. As such the ATOM records in PDB often contain missing atoms or only the part of a molecule that could be experimentally determined. In case of multi-domain proteins the PDB often contains only one of the domains (and in some cases even shorter fragments).
-Let's take a look at an example. The [Protein Feature View](https://github.com/andreasprlic/proteinfeatureview) provides a graphical summary of how the regions that have been observed in an experiment and are available in the PDB map to UniProt.
+Let's take a look at an example. The [Protein Feature View](https://github.com/andreasprlic/proteinfeatureview) provides a graphical summary of the regions that have been observed in an experiment and are available in the PDB map to UniProt.
-![Screenshot of Protein Feature View at RCSB]
-(https://raw.github.com/andreasprlic/proteinfeatureview/master/images/P06213.png "Insulin receptor - P06213 (INSR_HUMAN)")
+
As you can see, there are three PDB entries (PDB IDs [3LOH](http://www.rcsb.org/pdb/explore.do?structureId=3LOH), [2HR7](http://www.rcsb.org/pdb/explore.do?structureId=2RH7), [3BU3](http://www.rcsb.org/pdb/explore.do?structureId=3BU3)) that cover different regions of the UniProt sequence for the insulin receptor.
The blue-boxes are regions for which atoms records are available. For the grey regions there is sequence information available in the PDB, but no coordinates.
-## Seqres and Atom records
+## Seqres and Atom Records
-The sequence that has been used in the experiment is stored in the **Seqres** records in the PDB. It is often not the same sequences as can be found in Uniprot, since it can contain cloning-artefacts and modifications that were necessary in order to crystallize a structure.
+The sequence that has been used in the experiment is stored in the **Seqres** records in the PDB. It is often not the same sequence as can be found in Uniprot, since it can contain cloning-artefacts and modifications that were necessary in order to crystallize a structure.
The **Atom** records provide coordinates where it was possible to observe them.
@@ -40,7 +39,7 @@ The *mmCIF/PDBx* file format contains the information how the Seqres and atom re
```
-## Accessing Seqres and Atom groups
+## Accessing Seqres and Atom Groups
By default BioJava loads both the Seqres and Atom groups into the [Chain](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Chain.html)
objects.
@@ -53,9 +52,7 @@ objects.
Groups that are part of the Seqres sequence as well as of the Atom records are mapped onto each other. This means you
can iterate over all Seqres groups in a chain and check, if they have observed atoms.
-
-
-## Mapping from Uniprot to Atom records
+## Mapping from Uniprot to Atom Records
The mapping between PDB and UniProt changes over time, due to the dynamic nature of biological data. The [PDBe](http://www.pdbe.org) has a project that provides up-to-date mappings between the two databases, the [SIFTs](http://www.ebi.ac.uk/pdbe/docs/sifts/) project.
@@ -105,9 +102,9 @@ This gives the following output:
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 7 : SEQRES and ATOM records
+| [Book 3: The Structure Modules](README.md)
+| Chapter 7 : SEQRES and ATOM Records
-Prev: [Chapter 6 : work with mmCIF/PDBx files](mmcif.md)
+Prev: [Chapter 6 : Work with mmCIF/PDBx Files](mmcif.md)
Next: [Chapter 8 : Structure Alignments](alignment.md)
diff --git a/structure/special.md b/structure/special.md
index da1b3be..ea14816 100644
--- a/structure/special.md
+++ b/structure/special.md
@@ -130,9 +130,9 @@ DYG is an unusual group - it has 3 characters as a result of .getOne_letter_code
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 16 : Special Cases
+| [Book 3: The Structure Modules](README.md)
+| Chapter 17 : Special Cases
-Prev: [Chapter 13 - Finding all interfaces in crystal: crystal contacts](crystal-contacts.md)
+Prev: [Chapter 15 : Protein Secondary Structure](secstruc.md)
-Next: [Chapter 17 : status information](lists.md)
+Next: [Chapter 18 : Status Information](lists.md)
diff --git a/structure/structure-data-model.md b/structure/structure-data-model.md
index 19d0ef2..6ea6ce4 100644
--- a/structure/structure-data-model.md
+++ b/structure/structure-data-model.md
@@ -1,17 +1,17 @@
-# The BioJava-structure data model
+# The BioJava-Structure Data Model
A biologically and chemically meaningful data representation of PDB/mmCIF.
-## The basics
+## The Basics
-BioJava at its core is a collection of file parsers and (in some cases) data models to represent frequently used biological data. The protein-structure modules represent macromolecular data in a way that should make it easy to work with. The representation is essentially independ of the underlying file format and the user can chose to work with either PDB or mmCIF files and still get an almost identical data representation. (There can be subtile differences between PDB and mmCIF data, for example the atom indices in a few entries are not 100% identical)
+BioJava at its core is a collection of file parsers and (in some cases) data models to represent frequently used biological data. The protein-structure modules represent macromolecular data in a way that should make it easy to work with. The representation is essentially independent of the underlying file format and the user can chose to work with either PDB or mmCIF files and still get an almost identical data representation. (There can be subtile differences between PDB and mmCIF data, for example the atom indices in a few entries are not 100% identical)
-## The main hierarchy
+## The Main Hierarchy
BioJava provides a flexible data structure for managing protein structural data. The
-[http://www.biojava.org/docs/api/org/biojava/nbio/structure/Structure.html Structure] class is the main container.
+[Structure](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Structure.html) class is the main container.
-A Structure has a hierarchy of sub-objects:
+A `Structure` has a hierarchy of sub-objects:
Structure
@@ -25,28 +25,27 @@ Structure
Atom(s)
-All structure objects contain one or more "models". That means also X-ray structures contain a "virtual" model which serves as a container for the chains. The most common way to access chains will be via
+All `Structure` objects contain one or more `Models`. That means also X-ray structures contain a "virtual" model which serves as a container for the chains. This allows to represent multi-model X-ray structures, e.g. from time-series analysis. The most common way to access chains is via:
```java
- List chains = structure.getChains();
+ List chains = structure.getChains();
```
-This works for both NMR and X-ray based structures and by default the first model is getting accessed.
+This works for both NMR and X-ray based structures and by default the first `Model` is getting accessed.
-
-## Working with atoms
+## Working with Atoms
Different ways are provided how to access the data contained in a [Structure](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Structure.html).
-If you want to directly access an array of [Atoms](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Atom.html) you can use the utility class called [StructureTools](http://www.biojava.org/docs/api/org/biojava/nbio/structure/StructureTools.html)
+If you want to directly access an array of representative [Atoms](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Atom.html) (CA for proteins, P in nucleotides),you can use the utility class called [StructureTools](http://www.biojava.org/docs/api/org/biojava/nbio/structure/StructureTools.html)
```java
- // get all C-alpha atoms in the structure
- Atom[] caAtoms = StructureTools.getAtomCAArray(structure);
+ // get all representative atoms in the structure, one for residue
+ Atom[] caAtoms = StructureTools.getRepresentativeAtomArray(structure);
```
Alternatively you can access atoms also by their parent-group.
-## Loop over all the data
+## Loop over All the Data
Here an example that loops over the whole data model and prints out the HEM groups of hemoglobin:
@@ -59,7 +58,7 @@ Here an example that loops over the whole data model and prints out the HEM grou
for (Chain c : chains) {
- System.out.println(" Chain: " + c.getChainID() + " # groups with atoms: " + c.getAtomGroups().size());
+ System.out.println(" Chain: " + c.getId() + " # groups with atoms: " + c.getAtomGroups().size());
for (Group g: c.getAtomGroups()){
@@ -77,36 +76,35 @@ Here an example that loops over the whole data model and prints out the HEM grou
}
```
-## Working with groups
+## Working with Groups
The [Group](http://www.biojava.org/docs/api/org/biojava/nbio/structure/Group.html) interface defines all methods common to a group of atoms. There are 3 types of Groups:
-* [AminoAcid](http://www.biojava.org/docs/api/org/biojava/nbio/structure/AminoAcid.html)
-* [Nucleotide](http://www.biojava.org/docs/api/org/biojava/nbio/structure/NucleotideImpl.html)
-* [Hetatom](http://www.biojava.org/docs/api/org/biojava/nbio/structure/HetatomImpl.html)
+* [AminoAcid](http://www.biojava.org/docs/api4.2.1/org/biojava/nbio/structure/AminoAcid.html)
+* [Nucleotide](http://www.biojava.org/docs/api4.2.1/org/biojava/nbio/structure/NucleotideImpl.html)
+* [Hetatom](http://www.biojava.org/docs/api4.2.1/org/biojava/nbio/structure/HetatomImpl.html)
In order to get all amino acids that have been observed in a PDB chain, you can use the following utility method:
```java
- Chain chain = s.getChainByPDB("A");
- List groups = chain.getAtomGroups("amino");
+ Chain chain = structure.getPolyChainByPDB("A");
+ List groups = chain.getAtomGroups(GroupType.AMINOACID);
for (Group group : groups) {
- AminoAcid aa = (AminoAcid) group;
+ SecStrucInfo secStrucInfo = (SecStrucInfo) group.getProperty(Group.SEC_STRUC);
- // do something amino acid specific, e.g. print the secondary structure assignment
- System.out.println(aa + " " + aa.getSecStruc());
+ // print the secondary structure assignment
+ System.out.println(group + " -- " + secStrucInfo);
}
```
-
In a similar way you can access all nucleotide groups by
```java
- chain.getAtomGroups("nucleotide");
+ chain.getAtomGroups(GroupType.NUCLEOTIDE);
```
The Hetatom groups are access in a similar fashion:
```java
- chain.getAtomGroups("hetatm");
+ chain.getAtomGroups(GroupType.HETATM);
```
@@ -114,10 +112,10 @@ Since all 3 types of groups are implementing the Group interface, you can also i
```java
List allgroups = chain.getAtomGroups();
- for (Group group : groups) {
- if ( group instanceof AminoAcid) {
- AminoAcid aa = (AminoAcid) group;
- System.out.println(aa.getSecStruc());
+ for (Group group : allgroups) {
+ if (group.isAminoAcid()) {
+ SecStrucInfo secStrucInfo = (SecStrucInfo) group.getProperty(Group.SEC_STRUC);
+ System.out.println(group + " -- " + secStrucInfo);
}
}
```
@@ -128,7 +126,7 @@ The detection of the groups works really well in connection with the [Chemical C
## Entities and Chains
-Entities (in the BioJava API called compounds) are the distinct chemical components of structures in the PDB.
+Entities are the distinct chemical components of structures in the PDB.
Unlike chains, entities do not include duplicate copies and each entity is different from every other
entity in the structure. There are different types of entities. Polymer entities include Protein, DNA,
and RNA. Ligands are smaller chemical components that are not part of a polymer entity.
@@ -142,15 +140,15 @@ and beta. Each of the entities has two copies (= chains) in the structure. IN 4H
has the two chains with the IDs A, and C and beta the chains B, and D. In total, hemoglobin is
built up out of four chains.
-This prints all the compounds/entities in a structure
+This prints all the entities in a structure
```java
Structure structure = StructureIO.getStructure("4hhb");
System.out.println(structure);
- System.out.println(" # of compounds (entities) " + structure.getCompounds().size());
+ System.out.println(" # of compounds (entities) " + structure.getEntityInfos().size());
- for ( Compound entity: structure.getCompounds()) {
+ for ( EntityInfo entity: structure.getEntityInfos()) {
System.out.println(" " + entity);
}
```
@@ -167,9 +165,9 @@ This prints all the compounds/entities in a structure
Navigation:
[Home](../README.md)
-| [Book 3: The Protein Structure modules](README.md)
-| Chapter 3 : data model
+| [Book 3: The Structure Modules](README.md)
+| Chapter 3 : Structure Data Model
Prev: [Chapter 2 : First Steps](firststeps.md)
-Next: [Chapter 4 : Local installations](caching.md)
+Next: [Chapter 4 : Local Installations](caching.md)
diff --git a/structure/symmetry.md b/structure/symmetry.md
index e5f910a..cfe5186 100644
--- a/structure/symmetry.md
+++ b/structure/symmetry.md
@@ -1,16 +1,258 @@
-Detection of Protein Symmetry and Pseudo-symmetry using BioJava
+Protein Symmetry using BioJava
================================================================
-This chapter is still under construction. See the [protein symmetry](https://github.com/rcsb/symmetry) project for more information for now.
+BioJava can be used to detect, analyze, and visualize **symmetry** and
+**pseudo-symmetry** in the **quaternary** (biological assembly) and tertiary
+(**internal**) structural levels of proteins.
-BioJava can be used to
- - Detect, analyze, and visualize **protein symmetry**
- - Detect symmetry in **biological assemblies**
-
-
+## Quaternary Symmetry
- - Detect **internal pseudo-symmetry** in protein chains
-
-
+The **quaternary symmetry** of a structure defines the relation and arrangement of the individual chains or groups of chains that are part of a biological assembly.
+For a more exhaustive explanation about protein quaternary symmetery and the different types visit the [PDB help page](http://www.rcsb.org/pdb/staticHelp.do?p=help/viewers/jmol_symmetry_view.html).
-- Visualize results in [Jmol](http://www.jmol.org)
\ No newline at end of file
+In the **quaternary symmetry** detection problem, we are given a set of chains (subunits) that are part of a biological assembly as input, defined by their atomic coordinates, and we are required to find the higest overall symmetry group that
+relates them as ouptut.
+The solution is divided into the following steps:
+
+1. First, we need to identify the chains that are identical (or similar
+in the pseudo-symmetry case). For that purpose, we perform a pairwise alignment of all
+chains and identify **clusters of identical or similar subunits**.
+2. Next, we reduce each of the polypeptide chains to a single point, their **centroid** (center of mass).
+3. Afterwards, we try different **symmetry operations** using a grid search to superimpose the chain centroids
+and score them using the RMSD.
+4. Finally, based on the parameters (cutoffs), we determine the **overall symmetry** of the
+structure, with the symmetry relations obtained in the previous step.
+5. In case of asymmetric structure, we discard combinatorially a number of chains and try
+to detect any **local symmetries** present (symmetry that does not involve all subunits of the biological assembly).
+
+The **quaternary symmetry** detection algorithm is implemented in the biojava class
+[QuatSymmetryDetector](http://www.biojava.org/docs/api/org/biojava/nbio/structure/symmetry/core/QuatSymmetryDetector).
+An example of how to use it programatically is shown below:
+
+```java
+// First download the structure in the biological assembly form
+Structure s;
+
+// Set some parameters if needed different than DEFAULT - see descriptions
+QuatSymmetryParameters parameters = new QuatSymmetryParameters();
+SubunitClustererParameters clusterParams = new SubunitClustererParameters();
+
+// Instantiate the detector
+QuatSymmetryDetector detector = QuatSymmetryDetector(s, parameters, clusterParams);
+
+// Static methods in QuatSymmetryDetector perform the calculation
+QuatSymmetryResults globalResults = QuatSymmetryDetector.getGlobalSymmetry(s, parameters, clusterParams);
+List localResults = QuatSymmetryDetector.getLocalSymmetries(s, parameters, clusterParams);
+
+```
+See also the [demo](https://github.com/biojava/biojava/blob/885600670be75b7f6bc5216bff52a93f43fff09e/biojava-structure/src/main/java/demo/DemoSymmetry.java#L37-L59) provided in **BioJava** for a real case working example.
+
+The returned `QuatSymmetryResults` object contains all the information of the subunit clustering and structural symmetry.
+This object will be used later to obtain axes of symmetry, point group name, stoichiometry or even display the results in Jmol.
+The return object of quaternary symmetry (`QuatSymmetryResults`) contains the
+In case of asymmetrical structure, the result is a C1 point group.
+The return type of the local symmetry is a `List` because there can be multiple valid options of local symmetry.
+The list will be empty if there exist no local symmetries in the structure.
+
+
+### Global Symmetry
+
+In the **global symmetry** mode all chains have to be part of the symmetry result.
+
+#### Point Group
+
+In a **point group** a single or multiple rotation axes define the overall symmetry
+operations, with the property that all the axes coincide in the same point.
+
+
+
+#### Helical
+
+In **helical** symmetry there is a single axis with rotation and translation
+components.
+
+
+
+### Local Symmetry
+
+In **local symmetry** a number of chains is left out, so that the symmetry only applies to a subset of chains.
+
+
+
+### Pseudo-Symmetry
+
+In **pseudo-symmetry** the chains related by the symmetry are not completely
+identical, but they share a sequence or structural similarity above the pseudo-symmetry
+similarity threshold.
+
+If we consider hemoglobin, at a 95% sequence identity threshold the alpha and
+beta subunits are considered different, which correspond to an A2B2 stoichiometry
+and a C2 point group. At the structural similarity level, all four chains are
+considered homologous (~45% sequence identity) with an A4 pseudostoichiometry and
+D2 pseudosymmetry.
+
+
+
+## Internal Symmetry
+
+**Internal symmetry** refers to the symmetry present in a single chain, that is,
+the tertiary structure. The algorithm implemented in biojava to detect internal
+symmetry is called **CE-Symm**.
+
+### CE-Symm
+
+The **CE-Symm** algorithm was originally developed by [Myers-Turnbull D., Bliven SE.,
+Rose PW., Aziz ZK., Youkharibache P., Bourne PE. & Prlić A. in 2014]
+(http://www.sciencedirect.com/science/article/pii/S0022283614001557) [](http://www.ncbi.nlm.nih.gov/pubmed/24681267).
+As the name of the algorithm explicitly states, **CE-Symm** uses the Combinatorial
+Extension (**CE**) algorithm to generate an alignment of the structure chain to itself,
+disabling the identity alignment (the diagonal of the **DotPlot** representation of a
+structure alignment). This allows the identification of alternative self-alignments,
+which are related to symmetry and/or structural repeats inside the chain.
+
+By a procedure called **refinement**, the subunits of the chain that are part of the symmetry
+are defined and a **multiple alignment** is created. This process can be thought as to
+divide the chain into other subchains, and then superimposing each subchain to each other to
+create a multiple alignment of the subunits, respecting the symmetry axes.
+
+The **internal symmetry** detection algorithm is implemented in the biojava class
+[CeSymm](http://www.biojava.org/docs/api/org/biojava/nbio/structure/symmetry/internal/CeSymm).
+It returns a `MultipleAlignment` object, see the explanation of the model in [Data Models](alignment-data-model.md),
+that describes the similarity of the internal repeats. In case of no symmetry detected, the
+returned alignment represents the optimal self-alignment produced by the first step of the **CE-Symm**
+algorithm.
+
+```java
+//Input the atoms in a chain as an array
+Atom[] atoms = StructureTools.getRepresentativeAtomArray(chain);
+
+//Initialize the algorithm
+CeSymm ceSymm = new CeSymm();
+
+//Choose some parameters
+CESymmParameters params = ceSymm.getParameters();
+params.setRefineMethod(RefineMethod.SINGLE);
+params.setOptimization(true);
+params.setMultipleAxes(true);
+
+//Run the symmetry analysis - alignment as an output
+MultipleAlignment symmetry = ceSymm.analyze(atoms, params);
+
+//Test if the alignment returned was refined with
+boolean refined = SymmetryTools.isRefined(symmetry);
+
+//Get the axes of symmetry from the aligner
+SymmetryAxes axes = ceSymm.getSymmetryAxes();
+
+//Display the results in jmol with the SymmetryDisplay
+SymmetryDisplay.display(symmetry, axes);
+
+//Show the point group, if any of the internal symmetry
+QuatSymmetryResults pg = SymmetryTools.getQuaternarySymmetry(symmetry);
+System.out.println(pg.getSymmetry());
+
+```
+
+To enable some extra features in the display, a `SymmetryDisplay`
+class has been created, although the `MultipleAlignmentDisplay` method
+can also be used for that purpose (it will not show symmetry axes or
+symmetry menus).
+
+Lastly, the `SymmetryGUI` class in the **structure-gui** package
+provides a GUI to trigger internal symmetry analysis, equivalent
+to the GUI to trigger structure alignments.
+
+### Symmetry Display
+
+The symmetry display is similar to the **quaternary symmetry**, because
+part of the code is shared. See for example this beta-propeller (1U6D),
+where the repeated beta-sheets are connected by a linker forming a C6
+point group internal symmetry:
+
+
+
+#### Hierarchical Symmetry
+
+One additional feature of the **internal symmetry** display is the representation
+of hierarchical symmetries and repeats. Contrary to point groups, some structures
+have different **levels** of symmetry. That is, the whole strucutre has, e.g. C2
+symmetry and, at the same time, each of the two parts has C2 symmetry, but the axes
+of both levels are not related by a point group (i.e. they do not cross to a single
+point).
+
+A very clear example are the beta-gamma-crystallins, like 4GCR:
+
+
+
+#### Subunit Multiple Alignment
+
+Another feature of the display is the option to show the **multiple alignment** of
+the symmetry related subunits created during the **refinement** process. Search for
+the option *Subunit Superposition* in the *symmetry* menu of the Jmol window. For
+the previous example the display looks like that:
+
+
+
+The subunit display highlights the differences and similarities between the symmetry
+related subunits of the chain, and helps the user to identify conseved and divergent
+regions, with the help of the *Sequence Alignment Panel*.
+
+## Quaternary + Internal Overall Symmetry
+
+Finally, the internal and quaternary symmetries can be merged to obtain the
+overall combined symmetry. As we have seen before, the protein 1VYM is a DNA-clamp that
+has three chains arranged in a C3 symmetry.
+Each chain is internally fourfold symmetric with two levels of symmetry. We can analyze the overall symmetry of the structure by considering together the C3 quaternary symmetry and the fourfold internal symmetry.
+In this case, the internal symmetry **augments** the point group of the quaternary symmetry to a D6 overall symmetry, as we can see in the figure below:
+
+
+
+An example of how to toggle the **combined symmetry** (quaternary + internal symmetries) programatically is shown below:
+
+```java
+// First download the structure in the biological assembly form
+Structure s;
+
+// Initialize default parameters
+QuatSymmetryParameters parameters = new QuatSymmetryParameters();
+SubunitClustererParameters clusterParams = new SubunitClustererParameters();
+
+// In SubunitClustererParameters set the clustering method to STRUCTURE and the internal symmetry option to true
+clusterParams.setClustererMethod(SubunitClustererMethod.STRUCTURE);
+clusterParams.setInternalSymmetry(true);
+
+// You can lower the default structural coverage to improve the recall
+clusterParams.setStructureCoverageThreshold(0.75);
+
+// Instantiate the detector
+QuatSymmetryDetector detector = QuatSymmetryDetector(s, parameters, clusterParams);
+
+// Static methods in QuatSymmetryDetector perform the calculation
+QuatSymmetryResults overallResults = QuatSymmetryDetector.getGlobalSymmetry(s, parameters, clusterParams);
+
+```
+
+See also the [test](https://github.com/biocryst/biojava/blob/df22da37a86a0dba3fb35bee7e17300d402ab469/biojava-integrationtest/src/test/java/org/biojava/nbio/structure/test/symmetry/TestQuatSymmetryDetectorExamples.java#L167-L192) provided in **BioJava** for a real case working example.
+
+
+## Please Cite
+
+**Analyzing the symmetrical arrangement of structural repeats in proteins with CE-Symm**
+*Spencer E Bliven, Aleix Lafita, Peter W Rose, Guido Capitani, Andreas Prlić, & Philip E Bourne*
+[PLOS Computational Biology (2019) 15 (4):e1006842.](https://journals.plos.org/ploscompbiol/article/citation?id=10.1371/journal.pcbi.1006842)
+[](https://doi.org/10.1371/journal.pcbi.1006842) [](http://www.ncbi.nlm.nih.gov/pubmed/31009453)
+
+
+
+
+
+---
+
+Navigation:
+[Home](../README.md)
+| [Book 3: The Structure Modules](README.md)
+| Chapter 14 : Protein Symmetry
+
+Prev: [Chapter 13 - Finding all Interfaces in Crystal: Crystal Contacts](crystal-contacts.md)
+
+Next: [Chapter 15 : Protein Secondary Structure](secstruc.md)
Tutorial
+===
-A brief introduction into [BioJava](https://github.com/biojava/biojava).
-==
+A brief introduction into [BioJava](https://www.biojava.org).
+-----
-The goal of this tutorial is to provide an educational introduction into some of the features that are provided by BioJava.
+The goal of this tutorial is to provide an educational introduction into some of the features that are provided by BioJava. This tutorial is still under development, hence not yet comprehensive for the entire library. Please also check other sources of [documentation](https://biojava.org/wiki/Documentation).
-At the moment this tutorial is still under development. Please check the [BioJava Cookbook](http://biojava.org/wiki/BioJava:CookBook3.0) for a more comprehensive collection of many examples of what is possible with BioJava and how to do things.
+The examples within the tutorial are intended to work with the most recent version of BioJava. Please do submit a [new issue](https://github.com/biojava/biojava-tutorial/issues) if you find any problems.
+
+The tutorial is subdivided into several books, corresponding to the respective BioJava modules. Each book is further subdivided into several chapters that intend to describe the main functionality of the module in order of increasing complexity.
## Index
-Quick [Installation](installation.md)
+[Quick Installation](installation.md)
-Book 1: [The Core module](core/README.md), basic working with sequences.
+Book 1: [The Core Module](core/README.md), basic working with sequences.
-Book 2: [The Alignment module](alignment/README.md), pairwise and multiple alignments of protein sequences.
+Book 2: [The Alignment Module](alignment/README.md), pairwise and multiple alignments of protein sequences.
-Book 3: [The Protein Structure modules](structure/README.md), everything related to working with 3D structures.
+Book 3: [The Structure Modules](structure/README.md), everything related to working with 3D structures.
-Book 4: [The Genomics Module](genomics/README.md), working with genomic data
+Book 4: [The Genomics Module](genomics/README.md), working with genomic data.
+Book 5: [The Protein-Disorder Module](protein-disorder/README.md), predicting protein-disorder.
-## License
+Book 6: [The ModFinder Module](modfinder/README.md), identifying protein modifications in 3D structures
-The content of this tutorial is available under the [CC-BY](http://creativecommons.org/licenses/by/3.0/) license.
+## License
-[view license](license.md)
+The content of this tutorial is available under the [CC-BY](http://creativecommons.org/licenses/by/3.0/) license, available [here](license.md).
-## Please cite
+## Please Cite
-**BioJava: an open-source framework for bioinformatics in 2012**
+ 