Update for IMP 2.20.0

rnapolii/modeling/deposition-colab.ipynb

@@ -68,8 +68,8 @@
       "source": [
         "# Study versus single model<a id=\"studyvmodel\"></a>\n",
         "\n",
-        "A frequently asked question is whether mmCIF files can be generated directly from an [IMP::Model](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1Model.html) or an\n",
-        "[RMF file](https://integrativemodeling.org/rmf/). This generally isn't possible because RMF and [IMP::Model](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1Model.html) are designed to store one or more output models, where each model is a set of coordinates for a single conformation of the system being studied. A deposition, on the other hand, aims to cover a complete modeling study, and should capture the entire ensemble of output models, all of the input data needed to reproduce the modeling, and quality metrics such as the precision of the ensemble and the degree to which it fits the output data. A deposition is also designed to\n",
+        "A frequently asked question is whether mmCIF files can be generated directly from an [IMP::Model](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1Model.html) or an\n",
+        "[RMF file](https://integrativemodeling.org/rmf/). This generally isn't possible because RMF and [IMP::Model](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1Model.html) are designed to store one or more output models, where each model is a set of coordinates for a single conformation of the system being studied. A deposition, on the other hand, aims to cover a complete modeling study, and should capture the entire ensemble of output models, all of the input data needed to reproduce the modeling, and quality metrics such as the precision of the ensemble and the degree to which it fits the output data. A deposition is also designed to\n",
         "be visualized, and so may contain additional data not used in the modeling itself, such as preset colors or views to match figures in the publication or highlight regions of interest, and more human-descriptive names for parts\n",
         "of the system. Thus, deposition is largely a data-gathering exercise, and benefits from a modeling study being tidy and well organized (for example, by storing it in a [GitHub](https://github.com) repository) so that data is easy to find and track to its source."
       ]
@@ -88,7 +88,7 @@
         "There are two main approaches to generating an mmCIF file for deposition:\n",
         "\n",
         " 1. Use the [python-ihm](https://github.com/ihmwg/python-ihm) library directly, by writing a Python script that reads in output models and input data, adds annotations, and writes out an mmCIF file.\n",
-        " 2. Use the [ProtocolOutput](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html) class to automatically capture an entire [IMP::pmi](https://integrativemodeling.org/2.19.0/doc/ref/namespaceIMP_1_1pmi.html) modeling protocol.\n",
+        " 2. Use the [ProtocolOutput](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html) class to automatically capture an entire [IMP::pmi](https://integrativemodeling.org/2.20.0/doc/ref/namespaceIMP_1_1pmi.html) modeling protocol.\n",
         "\n",
         "The first approach offers the greatest flexibility for custom protocols or for modeling outside of IMP itself, but does require everything to be done manually. For a good example of this approach, see the [modeling of Nup133](https://github.com/integrativemodeling/nup133/tree/main/outputs_foxs_ensemble_new/pdb-dev). (One example of the tradeoff between flexibility and manual coding: the cross-links used in the study are stored in a [plain text file](https://github.com/integrativemodeling/nup133/blob/main/Crosslinks/DSS_EDC_crosslinks.txt) so a [custom Python class](https://github.com/integrativemodeling/nup133/blob/main/outputs_foxs_ensemble_new/pdb-dev/xlink.py) had to be written to parse them.)\n",
         "\n",
@@ -101,7 +101,7 @@
       "source": [
         "# Basic usage of ProtocolOutput<a id=\"basicusage\"></a>\n",
         "\n",
-        "[ProtocolOutput](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html) is designed to be attached to a top-level PMI object (usually [IMP::pmi::topology::System](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1topology_1_1System.html)). Then, as the script is run, it will capture all of the information about the modeling\n",
+        "[ProtocolOutput](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html) is designed to be attached to a top-level PMI object (usually [IMP::pmi::topology::System](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1topology_1_1System.html)). Then, as the script is run, it will capture all of the information about the modeling\n",
         "study, in an [ihm.System](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System) object. Additional information not in the modeling script itself, such as the\n",
         "resulting publication, can be added using the [python-ihm API](https://python-ihm.readthedocs.io/en/latest/usage.html)."
       ]
@@ -222,7 +222,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Next, as soon as the top-level [IMP::pmi::topology::System](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1topology_1_1System.html) object is created, we attach a ProtocolOutput object (BuildSystem contains a `system` member):"
+        "Next, as soon as the top-level [IMP::pmi::topology::System](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1topology_1_1System.html) object is created, we attach a ProtocolOutput object (BuildSystem contains a `system` member):"
       ]
     },
     {
@@ -410,7 +410,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "As it is generally undesirable to rerun the entire modeling just to generate an mmCIF file, we can save a lot of time when we do the replica exchange by turning on [ReplicaExchange](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1macros_1_1ReplicaExchange.html)'s `test_mode`, which skips the actual Monte Carlo simulation (so we use the previously-generated trajectory):"
+        "As it is generally undesirable to rerun the entire modeling just to generate an mmCIF file, we can save a lot of time when we do the replica exchange by turning on [ReplicaExchange](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1macros_1_1ReplicaExchange.html)'s `test_mode`, which skips the actual Monte Carlo simulation (so we use the previously-generated trajectory):"
       ]
     },
     {
@@ -446,7 +446,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Once we're done with our PMI protocol, we call the [ProtocolOutput.finalize](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html#a7b8395a33cbd3211cdf28e943c35dfa5) method to collect all of the information about the integrative modeling protocol in [ihm.System](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System):"
+        "Once we're done with our PMI protocol, we call the [ProtocolOutput.finalize](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html#a7b8395a33cbd3211cdf28e943c35dfa5) method to collect all of the information about the integrative modeling protocol in [ihm.System](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System):"
       ]
     },
     {
@@ -462,7 +462,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Note that the [ihm.System](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System) object, stored as the `system` attribute of [ProtocolOutput](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html), contains a full description of the system:"
+        "Note that the [ihm.System](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System) object, stored as the `system` attribute of [ProtocolOutput](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1mmcif_1_1ProtocolOutput.html), contains a full description of the system:"
       ]
     },
     {
@@ -673,7 +673,7 @@
       "source": [
         "## Cross-linker type<a id=\"xltype\"></a>\n",
         "\n",
-        "For cross-linking experiments, the mmCIF file contains a description of the cross-linking reagent used. This information is not in the CSV file. It can be provided in the Python script with the `linker` argument to passed to the PMI [CrossLinkingMassSpectrometryRestraint](https://integrativemodeling.org/2.19.0/doc/ref/classIMP_1_1pmi_1_1restraints_1_1crosslinking_1_1CrossLinkingMassSpectrometryRestraint.html), but if this argument was missing (or incorrect) we can correct it here. By checking the publications for the cross-link datasets from [Al Burlingame's lab](https://www.mcponline.org/content/13/2/420.long) and\n",
+        "For cross-linking experiments, the mmCIF file contains a description of the cross-linking reagent used. This information is not in the CSV file. It can be provided in the Python script with the `linker` argument to passed to the PMI [CrossLinkingMassSpectrometryRestraint](https://integrativemodeling.org/2.20.0/doc/ref/classIMP_1_1pmi_1_1restraints_1_1crosslinking_1_1CrossLinkingMassSpectrometryRestraint.html), but if this argument was missing (or incorrect) we can correct it here. By checking the publications for the cross-link datasets from [Al Burlingame's lab](https://www.mcponline.org/content/13/2/420.long) and\n",
         "[Juri Rappsilber's lab](http://emboj.embopress.org/content/29/4/717)), we can determine that the [DSS](https://en.wikipedia.org/wiki/Disuccinimidyl_suberate) and [BS3](https://en.wikipedia.org/wiki/Bissulfosuccinimidyl_suberate) cross-linkers were used, respectively. These are common enough cross-linkers that python-ihm already includes definitions for them in the [ihm.cross_linkers](https://python-ihm.readthedocs.io/en/latest/cross_linkers.html#module-ihm.cross_linkers) module (for less common linkers we can create an [ihm.ChemDescriptor](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.ChemDescriptor) object from scratch to describe its chemistry). Then we just set the linker type for each [cross-linking restraint](https://python-ihm.readthedocs.io/en/latest/restraint.html#ihm.restraint.CrossLinkRestraint) in the [list of all restraints](https://python-ihm.readthedocs.io/en/latest/main.html#ihm.System.restraints):"
       ]
     },
@@ -801,7 +801,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "To add a model to the file, we create an [ihm.model.Model](https://python-ihm.readthedocs.io/en/latest/model.html#ihm.model.Model) object, add atoms or coarse-grained objects to it, and then add that to the previously-created [ModelGroup](https://python-ihm.readthedocs.io/en/latest/model.html#ihm.model.ModelGroup). ProtocolOutput provides a convenience function `add_model` which does this, converting the current IMP structure to python-ihm (we just need to load an IMP structure first, e.g. from an RMF file using [IMP.rmf.load_frame](https://integrativemodeling.org/2.19.0/doc/ref/namespaceIMP_1_1rmf.html#abc15209a0aef0e859c99ce00659ebdfb))."
+        "To add a model to the file, we create an [ihm.model.Model](https://python-ihm.readthedocs.io/en/latest/model.html#ihm.model.Model) object, add atoms or coarse-grained objects to it, and then add that to the previously-created [ModelGroup](https://python-ihm.readthedocs.io/en/latest/model.html#ihm.model.ModelGroup). ProtocolOutput provides a convenience function `add_model` which does this, converting the current IMP structure to python-ihm (we just need to load an IMP structure first, e.g. from an RMF file using [IMP.rmf.load_frame](https://integrativemodeling.org/2.20.0/doc/ref/namespaceIMP_1_1rmf.html#abc15209a0aef0e859c99ce00659ebdfb))."
       ]
     },
     {