Integrate dynophore generation and visualization

.gitignore

@@ -115,4 +115,7 @@ ENV/
 docs/examples/data
 
 # Sphinx
-docs/autosummary/
+docs/autosummary/
+
+# Dynophore JAR file
+dynophores/generate/*.jar

devtools/conda-envs/test_env.yaml

@@ -5,6 +5,7 @@ channels:
 dependencies:
     # Base depends
   - python>=3.6
+  - openjdk
   - pip
   - numpy
   - pandas  

docs/getting-started.rst

@@ -1,48 +1,81 @@
 Getting started
 ===============
 
-Generate dynophores
--------------------
+IO data
+-------
 
-Download
-^^^^^^^^
+Input
+~~~~~
 
-TBA
+The ``dynophores`` package will generate a dynophore based on the following input data:
 
-Usage
-^^^^^
+* ``startframe.(pdb|pmz)``: Topology as PDB file or PMZ file.
+
+    The PMZ file contains the binding site of interest and assigns atoms to either the macromolecule 
+    or the ligand side. Interactions will be detected between these two sides.
+    Such PMZ files can be generated with the software LigandScout.
+
+    If you do not have such a PMZ file, you can also start from a PDB file. 
+    The ``dynophores`` package either infers the binding site automatically or you specify 
+    the chain and ligand of interest yourself.
+
+* ``trajectory.dcd``: Trajectory as DCD file.
 
-TBA
+    Make sure that the trajectory is matching the input PDB or PMZ file.
 
+* ``feature_definitions.xml`` (optional!): Set customized feature definitions.
 
-Visualize dynophores
---------------------
+    Change the default feature definitons by editing `this file <https://github.com/wolberlab/dynophores/tree/master/dynophores/data/custom-chemicalfeature-definitions.xml>`_.
 
-Dynophores can be easily visualized in Jupyter Notebooks with the ``dynophores`` Python package.
+Output
+~~~~~~
 
+The ``dynophores`` package will generate the following dynophore data::
+
+    dynophore_out_YYYY-MM-DD_hh-mm-ss/
+    ├── dynophore.pml     # Point cloud data
+    ├── dynophore.cgo     # Point cloud data as PyMol script
+    ├── dynophore.json    # Statistics
+    └── dynophore.ipynb   # Visualization notebook
+
+Data from the PML and JSON files are visualized in the interactive Jupyter notebook ``dynophore.ipynb``.
 
 Installation
-^^^^^^^^^^^^
+------------
 
 Install the ``dynophores`` package as described `here <https://dynophores.readthedocs.io/en/latest/installing.html>`_.
 
 Usage
-^^^^^
+-----
+
+* Take a look at a demo notebook showing the dynophore from an MD simulation for ligand-bound kinase CDK2 (PDB ID: 1KE7)::
+
+    dynophore demo path/to/output/folder
+
+  Generates a dynophore demo notebook at ``path/to/output/folder/dynophore.ipynb``.
+
+* If you have an input PDB (topology) and DCD (trajectory) file, run::
+
+    dynophore create -p path/to/pdb/file -d path/to/dcd/file -o path/to/output/folder -n dynophore_name
+
+  Generates dynophore data at ``path/to/output/folder/dynophore_out_YYYY-MM-DD_hh-mm-ss``, which contains the dynophore notebook.
+
+* If you have an input PDB (topology) and DCD (trajectory) file *and* you want to specify the chain or ligand to be used for the binding site definiton, run::
+
+    dynophore create -p path/to/pdb/file -c chain_id -3 three_letter_ligand_code -d path/to/dcd/file -o path/to/output/folder -n dynophore_name
 
-You have different options what to do next:
+  Generates dynophore data at ``path/to/output/folder/dynophore_out_YYYY-MM-DD_hh-mm-ss``, which contains the dynophore notebook.
 
-a. Take a look at a demo notebook showing the dynophore from an MD simulation for ligand-bound kinase CDK2 (PDB ID: 1KE7)::
+* If you have an input PMZ (topology) and DCD (trajectory) file, run::
 
-    dynoviz demo path/to/some/folder
+    dynophore create -p path/to/pmz/file -d path/to/dcd/file -o path/to/output/folder -n dynophore_name
 
-b. Explore your own dynophore data in a new notebook::
+  Generates dynophore data at ``path/to/output/folder/dynophore_out_YYYY-MM-DD_hh-mm-ss``. 
+  To generate the corresponding dynophore notebook, run ``dynophore visualize``.
 
-    dynoviz create --dyno path/to/dyno/folder --pdb path/to/pdb/file --dcd path/to/dcd/file --workspace path/to/workspace/folder
+* If you already have a dynophore data folder, run::
 
-c. If you already have set up your dynophore notebook (i.e. if you want to revisit a notebook created with option b), run::
+    dynophore visualize -i path/to/dynophore/folder -p path/to/pdb/file -d path/to/dcd/file
 
-    dynoviz open path/to/your/dyno/notebook
+  Adds the dynophore notebook to the dynophore data files at ``path/to/dynophore/folder/dynophore.ipynb``.
 
-   Note: This command is equivalent to::
-
-    jupyter lab path/to/your/dyno/notebook

docs/installing.rst

@@ -20,7 +20,7 @@ Install from the conda package
 
 3. Test that your installation works::
 
-    dynoviz -h
+    dynophore -h
 
 
 Install from the latest development snapshot
@@ -43,4 +43,4 @@ Install the latest development snapshot from the `GitHub repository's master bra
 
 4. Test that your installation works::
 
-    dynoviz -h
+    dynophore -h

dynophores/api/__init__.py

@@ -0,0 +1,3 @@
+from . import create
+from . import visualize
+from . import demo

dynophores/api/create.py

@@ -0,0 +1,107 @@
+"""
+Python API to create (i.e. generate and visualize) dynophore data.
+"""
+
+from pathlib import Path
+import subprocess
+import glob
+
+from ..utils import _download_file
+from ..definitions import DYNOPHORE_JAR_URL, DYNOPHORE_JAR_PATH
+from .visualize import visualize
+
+
+def create(pmz_or_pdb_path, dcd_path, out_path, name, feature_def_path, three_letter_code, chain):
+    """
+    Generate and visualize (Jupyter notebook) dynophore data.
+
+    Parameters
+    ----------
+    pmz_or_pdb_path : str or pathlib.Path
+        PMZ or PDB file.
+    dcd_path : str or pathlib.Path
+        DCD file.
+    out_path : str or pathlib.Path
+        Output folder.
+    name : str
+        Dynophore name.
+    feature_def_path : str
+        Optional: Feature definition file.
+    three_letter_code : str
+        Optional: Three letter code of ligand to be used for binding site definition.
+        In combination with PDB file.
+    chain : str
+        Optional: Chain to be used for binding site definition.
+        In combination with PDB file.
+    """
+
+    # Generate dynophore data
+    generate(pmz_or_pdb_path, dcd_path, out_path, name, feature_def_path, three_letter_code, chain)
+
+    # Visualize dynophore data
+    if pmz_or_pdb_path.suffix == ".pdb":
+        pdb_path = pmz_or_pdb_path
+        dyno_paths = sorted(glob.glob(str(out_path / "dynophore_out_*")), reverse=True)
+        dyno_path = Path(dyno_paths[0])
+        if (dyno_path / f"{name}_dynophore.pml").exists() and (
+            dyno_path / f"{name}_dynophore.json"
+        ).exists():
+            visualize(dyno_path, pdb_path, dcd_path)
+        else:
+            print(
+                "Dynophore visualization notebook could not be generated "
+                "due to missing dynophore data."
+            )
+    else:
+        print(
+            "To generate the dynophore visualization notebook, "
+            "please run the `dynophore visualize` command."
+        )
+
+
+def generate(
+    pmz_or_pdb_path,
+    dcd_path,
+    out_path,
+    name,
+    feature_def_path=None,
+    three_letter_code=None,
+    chain=None,
+):
+    """
+    Generate dynophore data using the dynophore Java library.
+
+    Parameters
+    ----------
+    pmz_or_pdb_path : str or pathlib.Path
+        PMZ or PDB file.
+    dcd_path : str or pathlib.Path
+        DCD file.
+    out_path : str or pathlib.Path
+        Output folder.
+    name : str
+        Dynophore name.
+    feature_def_path : str
+        Optional: Feature definition file.
+    three_letter_code : str
+        Optional: Three letter code of ligand to be used for binding site definition.
+        In combination with PDB file.
+    chain : str
+        Optional: Chain to be used for binding site definition.
+        In combination with PDB file.
+    """
+
+    _download_file(DYNOPHORE_JAR_URL, DYNOPHORE_JAR_PATH)
+
+    command = (
+        f"java -jar {DYNOPHORE_JAR_PATH} "
+        f"-p {pmz_or_pdb_path} "
+        f"-d {dcd_path} "
+        f"-o {out_path} "
+        f"-n {name} "
+        f"{'' if feature_def_path is None else f'-f {feature_def_path}'} "
+        f"{'' if three_letter_code is None else f'-3 {three_letter_code}'} "
+        f"{'' if chain is None else f'-c {chain}'} "
+    )
+    command = command.split()
+    subprocess.run(command)

dynophores/api/demo.py

@@ -0,0 +1,30 @@
+"""
+Python API to visualize demo dynophore data.
+"""
+
+from pathlib import Path
+
+from .utils import _copy_notebook, _update_paths_in_notebook, _open_notebook
+
+PATH_TEST_DATA = Path(__file__).parent / ".." / "tests" / "data"
+
+
+def demo(out_path):
+    """
+    Create and open demo visualization notebook based.
+
+    Parameters
+    ----------
+    out_path : str or pathlib.Path
+        Output folder.
+    """
+
+    new_notebook_path = Path(out_path) / "dynophore_demo.ipynb"
+    _copy_notebook(new_notebook_path)
+    _update_paths_in_notebook(
+        new_notebook_path,
+        (PATH_TEST_DATA / "out").absolute(),
+        (PATH_TEST_DATA / "in/startframe.pdb").absolute(),
+        (PATH_TEST_DATA / "in/trajectory.dcd").absolute(),
+    )
+    _open_notebook(new_notebook_path)