Corrected the examples (#79)

* renamed tempoSOAP to timeSOAP

* added getTimeSOAPSimple

* refined tests and re-executed the timeSOAP jupyter

* updated the notebooks with the examples

Changelog.md

@@ -7,8 +7,9 @@ Until we get to a release version you may encounter different broken interface p
 - `SOAPify.HDF5er.isTrajectoryGroup` now returns `False` with Datasets
 - Added some simple cli interfaces
 - Added examples for LENS and tSOAP and for generating hdf5 files
-- Added getSOAPSettings for getting the SOAP oragnization fro a dataset
-- now `createUniverseFromSlice()` returns also types
+- Added `getSOAPSettings()` for getting the SOAP organization from a hdf5 dataset
+- Added `getTimeSOAPSimple()` to give the user a shortcut to solve memory problem with large SOAP datasets
+- Now `createUniverseFromSlice()` returns also types
 
 ## Changes since v0.0.6
 

docs/source/Tutorials.rst

@@ -4,5 +4,5 @@ Tutorials and Examples
 .. nbgallery::
    FileHandling
    TimeAnalysis
-   tempoSOAP
+   timeSOAP
    LENS

docs/source/timeSOAP.ipynb

@@ -0,0 +1 @@
+../../Examples/timeSOAP.ipynb

src/SOAPify/analysis.py

@@ -2,19 +2,23 @@
 
 import numpy
 from numpy import ndarray
-from .distances import simpleSOAPdistance
 from MDAnalysis import Universe, AtomGroup
 from MDAnalysis.lib.NeighborSearch import AtomNeighborSearch
+import h5py
+
+from .distances import simpleSOAPdistance
+from .utils import getSOAPSettings, normalizeArray, fillSOAPVectorFromdscribe
 
 
-def tempoSOAP(
+def timeSOAP(
     SOAPTrajectory: ndarray,
     window: int = 1,
     stride: int = None,
     backward: bool = False,
+    returnDiff: bool = True,
     distanceFunction: callable = simpleSOAPdistance,
 ) -> "tuple[ndarray, ndarray]":
-    """performs the 'tempoSOAP' analysis on the given SOAP trajectory
+    """performs the 'timeSOAP' analysis on the given SOAP trajectory
 
         * Original author: Cristina Caruso
         * Mantainer: Daniele Rapetti
@@ -27,14 +31,18 @@ def tempoSOAP(
         stride (int):
             the stride in frames between each state confrontation. **NOT IN USE**.
             Defaults to None.
-        deltaT (int): number of frames to skip
+        backward (bool):
+            If true the soap distance is referred to the previous frame.
+             **NOT IN USE**. Defaulst to True.
+        returnDiff (bool):
+            If true returns also the first derivative of timeSOAP. Defaults to True.
         distanceFunction (callable, optional):
             the function that define the distance. Defaults to :func:`SOAPify.distances.simpleSOAPdistance`.
 
     Returns:
         tuple[numpy.ndarray,numpy.ndarray]:
-            - **timedSOAP** the tempoSOAP values, shape(frames-1,natoms)
-            - **deltaTimedSOAP** the derivatives of tempoSOAP, shape(natoms, frames-2)
+            - **timedSOAP** the timeSOAP values, shape(frames-1,natoms)
+            - **deltaTimedSOAP** the derivatives of timeSOAP, shape(natoms, frames-2)
     """
     if stride is None:
         stride = window
@@ -55,18 +63,20 @@ def tempoSOAP(
     # )
     # print(SOAPTrajectory.shape)
 
-    deltaTimedSOAP = numpy.diff(timedSOAP.T, axis=-1)
+    if returnDiff:
+        deltaTimedSOAP = numpy.diff(timedSOAP.T, axis=-1)
+        return timedSOAP, deltaTimedSOAP
+    return timedSOAP
 
-    return timedSOAP, deltaTimedSOAP
 
-
-def tempoSOAPsimple(
+def timeSOAPsimple(
     SOAPTrajectory: ndarray,
     window: int = 1,
     stride: int = None,
     backward: bool = False,
+    returnDiff: bool = True,
 ) -> "tuple[ndarray, ndarray]":
-    r"""performs the 'tempoSOAP' analysis on the given **normalized** SOAP trajectory
+    r"""performs the 'timeSOAP' analysis on the given **normalized** SOAP trajectory
 
         this is optimized to use :func:`SOAPify.distances.simpleSOAPdistance`,
         without calling it.
@@ -100,12 +110,16 @@ def tempoSOAPsimple(
         stride (int):
             the stride in frames between each state confrontation. **NOT IN USE**.
             Defaults to None.
-        deltaT (int): number of frames to skip
+        backward (bool):
+            If true the soap distance is referred to the previous frame.
+             **NOT IN USE**. Defaulst to True.
+        returnDiff (bool):
+            If true returns also the first derivative of timeSOAP. Defaults to True.
 
     Returns:
         tuple[numpy.ndarray,numpy.ndarray]:
-            - **timedSOAP** the tempoSOAP values, shape(frames-1,natoms)
-            - **deltaTimedSOAP** the derivatives of tempoSOAP, shape(natoms, frames-2)
+            - **timedSOAP** the timeSOAP values, shape(frames-1,natoms)
+            - **deltaTimedSOAP** the derivatives of timeSOAP, shape(natoms, frames-2)
     """
     if stride is None:
         stride = window
@@ -122,9 +136,71 @@ def tempoSOAPsimple(
         timedSOAP[frame - window] = numpy.linalg.norm(actual - prev, axis=1)
         prev = actual
 
-    deltaTimedSOAP = numpy.diff(timedSOAP.T, axis=-1)
+    if returnDiff:
+        deltaTimedSOAP = numpy.diff(timedSOAP.T, axis=-1)
+        return timedSOAP, deltaTimedSOAP
+    return timedSOAP
+
+
+def getTimeSOAPSimple(
+    soapDataset: h5py.Dataset,
+    window: int = 1,
+    stride: int = None,
+    backward: bool = False,
+):
+    """Shortcut to extract the timeSOAP from large datasets.
+
+        This function is the equivalent to:
+
+        - loading a chunk of the trajectory from a h5py.Dataset with a SOAP fingerprints trajectory
+        - filling the vector with :func:`SOAPify.utils.fillSOAPVectorFromdscribe`
+        - normalizing it with :func:`SOAPify.utils.normalizeArray`
+        - calculating the timeSOAP with  :func:`timeSOAPsimple`
+        and then returning timeSOAP and the derivative
+
+
+    Args:
+        soapDataset (h5py.Dataset):
+            the dataset with the SOAP fingerprints
+        window (int):
+            the dimension of the windows between each state confrontations.
+            See :func:`timeSOAPsimple`
+            Defaults to 1.
+        stride (int):
+            the stride in frames between each state confrontation.
+            See :func:`timeSOAPsimple`
+            Defaults to None.
+        backward (bool):
+            If true the soap distance is referred to the previous frame.
+            See :func:`timeSOAPsimple` . Defaulst to True.
+
+    Returns:
+        tuple[numpy.ndarray,numpy.ndarray]:
+            - **timedSOAP** the timeSOAP values, shape(frames-1,natoms)
+            - **deltaTimedSOAP** the derivatives of timeSOAP, shape(natoms, frames-2)
+    """
+    fillSettings = getSOAPSettings(soapDataset)
+    timedSOAP = numpy.zeros((soapDataset.shape[0] - window, soapDataset.shape[1]))
+    # TODO: add a check to the window
+
+    slide = 0
+    # this looks a lot convoluted, but it is way faster than working one atom
+    # at a time
+    for c in soapDataset.iter_chunks():
+        theSlice = slice(c[0].start - slide, c[0].stop, c[0].step)
+        outSlice = slice(c[0].start - slide, c[0].stop - 1, c[0].step)
+        timedSOAP[outSlice] = timeSOAPsimple(
+            normalizeArray(
+                fillSOAPVectorFromdscribe(soapDataset[theSlice], **fillSettings)
+            ),
+            window=window,
+            stride=stride,
+            backward=backward,
+            returnDiff=False,
+        )
+        slide = 1
 
-    return timedSOAP, deltaTimedSOAP
+    return timedSOAP, numpy.diff(timedSOAP.T, axis=-1)
 
 
 def listNeighboursAlongTrajectory(

tests/test_analysis.py

@@ -8,9 +8,13 @@
 import MDAnalysis
 from .testSupport import is_sorted, fewFrameUniverse
 
+# NB: the trueFalse fixture for the backward settings is here to anticipate the
+# implementation of that feature
 
-def test_tempoSOAP(referencesTrajectorySOAP, inputWindows):
-    window = inputWindows
+
+@pytest.mark.parametrize("window", [1, 2, 5, 7, 10])
+@pytest.mark.parametrize("backward", [True, False])
+def test_timeSOAP(referencesTrajectorySOAP, window, backward):
     stride = window
     confFile, groupName = referencesTrajectorySOAP
 
@@ -32,9 +36,7 @@ def isInvalidCombination(dataLen, stride, window):
 
     if isInvalidCombination(fillArgs["soapFromdscribe"].shape[0], stride, window):
         with pytest.raises(ValueError) as excinfo:
-            analysis.tempoSOAP(
-                fillArgs["soapFromdscribe"], stride=stride, window=window
-            )
+            analysis.timeSOAP(fillArgs["soapFromdscribe"], stride=stride, window=window)
         if stride is not None and window < stride:
             assert "window must be bigger" in str(excinfo.value)
             pytest.skip("Exception thrown correctly")
@@ -58,6 +60,9 @@ def isInvalidCombination(dataLen, stride, window):
             x = SOAPTraj[frame, molecule, :]
             y = SOAPTraj[frame - window, molecule, :]
             distance = SOAPify.simpleSOAPdistance(x, y)
+            # TODO:
+            # if backward:
+            # else:
             expectedTimedSOAP[
                 frame - window, molecule
             ] = distance  # fill the matrix (each molecule for each frame)
@@ -67,8 +72,8 @@ def isInvalidCombination(dataLen, stride, window):
         derivative = numpy.diff(expectedTimedSOAP[:, molecule])
         expectedDeltaTimedSOAP.append(derivative)
 
-    timedSOAP, deltaTimedSOAP = analysis.tempoSOAP(
-        SOAPTraj, stride=stride, window=window
+    timedSOAP, deltaTimedSOAP = analysis.timeSOAP(
+        SOAPTraj, stride=stride, window=window, backward=backward
     )
     # print(timedSOAP, expectedTimedSOAP)
     print(deltaTimedSOAP.shape, timedSOAP.shape)
@@ -81,8 +86,9 @@ def isInvalidCombination(dataLen, stride, window):
     assert_array_almost_equal(deltaTimedSOAP, expectedDeltaTimedSOAP)
 
 
-def test_tempoSOAPsimple(referencesTrajectorySOAP, inputWindows):
-    window = inputWindows
+@pytest.mark.parametrize("window", [1, 2, 5, 7, 10])
+@pytest.mark.parametrize("backward", [True, False])
+def test_timeSOAPsimple(referencesTrajectorySOAP, window, backward):
     stride = window
     confFile, groupName = referencesTrajectorySOAP
 
@@ -104,9 +110,7 @@ def isInvalidCombination(dataLen, stride, window):
 
     if isInvalidCombination(fillArgs["soapFromdscribe"].shape[0], stride, window):
         with pytest.raises(ValueError) as excinfo:
-            analysis.tempoSOAP(
-                fillArgs["soapFromdscribe"], stride=stride, window=window
-            )
+            analysis.timeSOAP(fillArgs["soapFromdscribe"], stride=stride, window=window)
         if stride is not None and window < stride:
             assert "window must be bigger" in str(excinfo.value)
             pytest.skip("Exception thrown correctly")
@@ -120,12 +124,63 @@ def isInvalidCombination(dataLen, stride, window):
 
     SOAPTraj = SOAPify.normalizeArray(SOAPTraj)
 
-    expectedTimedSOAP, expectedDeltaTimedSOAP = analysis.tempoSOAP(
-        SOAPTraj, stride=stride, window=window
+    expectedTimedSOAP, expectedDeltaTimedSOAP = analysis.timeSOAP(
+        SOAPTraj, stride=stride, window=window, backward=backward
     )
-    timedSOAP, deltaTimedSOAP = analysis.tempoSOAPsimple(
-        SOAPTraj, stride=stride, window=window
+    timedSOAP, deltaTimedSOAP = analysis.timeSOAPsimple(
+        SOAPTraj, stride=stride, window=window, backward=backward
+    )
+    print(timedSOAP, expectedTimedSOAP)
+    assert_array_almost_equal(timedSOAP, expectedTimedSOAP)
+
+    assert_array_almost_equal(deltaTimedSOAP, expectedDeltaTimedSOAP)
+
+
+@pytest.mark.parametrize("window", [1, 2, 5, 7, 10])
+@pytest.mark.parametrize("backward", [True, False])
+def test_getTimeSOAPsimple(referencesTrajectorySOAP, window, backward):
+    stride = window
+    confFile, groupName = referencesTrajectorySOAP
+
+    with h5py.File(confFile, "r") as f:
+        t = f[f"/SOAP/{groupName}"]
+        fillArgs = {
+            "soapFromdscribe": t[:],
+            "lMax": t.attrs["l_max"],
+            "nMax": t.attrs["n_max"],
+        }
+        fillArgs["atomTypes"], fillArgs["atomicSlices"] = SOAPify.getSlicesFromAttrs(
+            t.attrs
+        )
+
+    def isInvalidCombination(dataLen, stride, window):
+        return (stride is not None and window < stride) or (
+            (stride is not None and stride >= dataLen) or window >= dataLen
+        )
+
+    if isInvalidCombination(fillArgs["soapFromdscribe"].shape[0], stride, window):
+        with pytest.raises(ValueError) as excinfo:
+            analysis.timeSOAP(fillArgs["soapFromdscribe"], stride=stride, window=window)
+        if stride is not None and window < stride:
+            assert "window must be bigger" in str(excinfo.value)
+            pytest.skip("Exception thrown correctly")
+        if (
+            stride is not None and stride >= fillArgs["soapFromdscribe"].shape[0]
+        ) or window >= fillArgs["soapFromdscribe"].shape[0]:
+            assert "window must be smaller" in str(excinfo.value)
+            pytest.skip("Exception thrown correctly")
+
+    SOAPTraj = SOAPify.fillSOAPVectorFromdscribe(**fillArgs)
+
+    SOAPTraj = SOAPify.normalizeArray(SOAPTraj)
+
+    expectedTimedSOAP, expectedDeltaTimedSOAP = analysis.timeSOAPsimple(
+        SOAPTraj, stride=stride, window=window, backward=backward
     )
+    with h5py.File(confFile, "r") as f:
+        timedSOAP, deltaTimedSOAP = analysis.getTimeSOAPSimple(
+            f[f"/SOAP/{groupName}"], stride=stride, window=window, backward=backward
+        )
     print(timedSOAP, expectedTimedSOAP)
     assert_array_almost_equal(timedSOAP, expectedTimedSOAP)