Fixed #966 Add Named Attributes to Matrix Profile

docs/Tutorial_AB_Joins.ipynb

@@ -289,6 +289,25 @@
     "print(f'The motif is located at index {vanilla_ice_motif_index} of \"Ice Ice Baby\"')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 0]`, `mp[:, 1]`), the matrix profile distances can be accessed directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute:\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.P_, mp.I_)  # print the matrix profile and the matric profile indices \n",
+    "```\n",
+    "\n",
+    "Additionally, the left and right matrix profile indices can also be accessed through the `left_I_` and `right_I_` attributes, respectively.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -366,7 +385,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/Tutorial_Fast_Approximate_Matrix_Profiles.ipynb

@@ -257,6 +257,23 @@
     "    plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 0]`, `mp[:, 1]`), the matrix profile distances can be accessed directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute:\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.P_, mp.I_)  # print the matrix profile and the matric profile indices \n",
+    "```\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -486,7 +503,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/Tutorial_Matrix_Profiles_For_Streaming_Data.ipynb

@@ -191,6 +191,25 @@
     "I_full = mp[:, 1]"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 0]`, `mp[:, 1]`), the matrix profile distances can be accessed directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute:\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.P_, mp.I_)  # print the matrix profile and the matric profile indices \n",
+    "```\n",
+    "\n",
+    "Additionally, the left and right matrix profile indices can also be accessed through the `left_I_` and `right_I_` attributes, respectively.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -166458,7 +166477,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/Tutorial_STUMPY_Basics.ipynb

@@ -392,6 +392,25 @@
     "mp[motif_idx, 0]"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 0]`, `mp[:, 1]`), the matrix profile distances can be accessed directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute:\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.P_, mp.I_)  # print the matrix profile and the matric profile indices \n",
+    "```\n",
+    "\n",
+    "Additionally, the left and right matrix profile indices can also be accessed through the `left_I_` and `right_I_` attributes, respectively.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -985,7 +1004,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/Tutorial_Semantic_Segmentation.ipynb

@@ -320,6 +320,25 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 0]`, `mp[:, 1]`), the matrix profile distances can be accessed directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute:\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.P_, mp.I_)  # print the matrix profile and the matric profile indices \n",
+    "```\n",
+    "\n",
+    "Additionally, the left and right matrix profile indices can also be accessed through the `left_I_` and `right_I_` attributes, respectively.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -373,6 +392,21 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-block alert-info\">\n",
+    "Starting <u>after</u> STUMPY version 1.12.0, in place of `mp[:, 2]` and `mp[:, 3]`, you can access the left and right matrix profile indices through the `left_I_` and `right_I_` attributes, respectively:\n",
+    "<br/><br/>\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.left_I_, mp.right_I_)  # print the left and right matrix profile indices  \n",
+    "```\n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -56949,7 +56983,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/Tutorial_Time_Series_Chains.ipynb

@@ -467,6 +467,25 @@
     "all_chain_set, unanchored_chain = stumpy.allc(mp[:, 2], mp[:, 3])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[comment]: <> (Myst)\n",
+    ":::{admonition} **Added after STUMPY version 1.12.0**\n",
+    ":class: note\n",
+    "\n",
+    "In place of array slicing (i.e., `mp[:, 2]`, `mp[:, 3]`), the left and right matrix profile indices can also be accessed through the `left_I_` and `right_I_` attributes, respectively.\n",
+    "\n",
+    "```\n",
+    "mp = stumpy.stump(T, m)\n",
+    "print(mp.left_I_, mp.right_I_)  # print the left and right matrix profile indices \n",
+    "```\n",
+    "\n",
+    "Additionally, you can also access the matrix profile distances directly through the `P_` attribute and the matrix profile indices can be accessed through the `I_` attribute.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -586,7 +605,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/conf.py

@@ -52,8 +52,8 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
-    "nbsphinx",
     "numpydoc",
+    "myst_nb",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -63,7 +63,11 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [
+    ".rst",
+    ".md",
+    ".ipynb",
+]
 
 # The master toctree document.
 master_doc = "index"
@@ -214,7 +218,11 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 # Napoleon settings (see https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration)  # noqa: E501
 napoleon_numpy_docstring = True
+
+myst_enable_extensions = [
+    "colon_fence",
+]

docs/requirements.txt

@@ -1,5 +1,5 @@
 sphinx>=3.5.3
-nbsphinx
 pydata-sphinx-theme
 ipython
 numpydoc
+myst-nb

docs/setup.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
 
 make html
+#sphinx-build -nW --keep-going -b html . ./_build/html
 python -m http.server

environment.yml

@@ -17,10 +17,11 @@ dependencies:
   - lxml>=4.5.2
   - twine>=3.2.0
   - sphinx>=3.5.3
-  - nbsphinx>=0.8.1
   - pydata-sphinx-theme>=0.5.2
   - scikit-learn>=0.21.3
   - numpydoc>=1.1.0
   - build>=0.7.0
   - pytest-check-links>=0.7.1
   - isort>=5.11.0
+  - jupyterlab-myst>=2.0.0
+  - myst-nb>=1.0.0

stumpy/aamp.py

@@ -7,6 +7,7 @@
 from numba import njit, prange
 
 from . import config, core
+from .mparray import mparray
 
 
 @njit(
@@ -378,6 +379,12 @@ def aamp(T_A, m, T_B=None, ignore_trivial=True, p=2.0, k=1):
         equivalently, out[:, -2] and out[:, -1]) correspond to the top-1 left
         matrix profile indices and the top-1 right matrix profile indices, respectively.
 
+        For convenience, the matrix profile (distances) and matrix profile indices can
+        also be accessed via their corresponding named array attributes, `.P_` and
+        `.I_`,respectively. Similarly, the corresponding left matrix profile indices
+        and right matrix profile indices may also be accessed via the `.left_I_` and
+        `.right_I_` array attributes.
+
     Notes
     -----
     `arXiv:1901.05708 \
@@ -431,4 +438,4 @@ def aamp(T_A, m, T_B=None, ignore_trivial=True, p=2.0, k=1):
 
     core._check_P(out[:, 0])
 
-    return out
+    return mparray(out, m, k, config.STUMPY_EXCL_ZONE_DENOM)

stumpy/aamped.py

@@ -7,6 +7,7 @@
 
 from . import config, core
 from .aamp import _aamp
+from .mparray import mparray
 
 
 def _dask_aamped(
@@ -212,6 +213,12 @@ def aamped(client, T_A, m, T_B=None, ignore_trivial=True, p=2.0, k=1):
         equivalently, out[:, -2] and out[:, -1]) correspond to the top-1 left
         matrix profile indices and the top-1 right matrix profile indices, respectively.
 
+        For convenience, the matrix profile (distances) and matrix profile indices can
+        also be accessed via their corresponding named array attributes, `.P_` and
+        `.I_`,respectively. Similarly, the corresponding left matrix profile indices
+        and right matrix profile indices may also be accessed via the `.left_I_` and
+        `.right_I_` array attributes.
+
     Notes
     -----
     `arXiv:1901.05708 \
@@ -264,4 +271,4 @@ def aamped(client, T_A, m, T_B=None, ignore_trivial=True, p=2.0, k=1):
 
     core._check_P(out[:, 0])
 
-    return out
+    return mparray(out, m, k, config.STUMPY_EXCL_ZONE_DENOM)

stumpy/chains.py

@@ -52,6 +52,11 @@ def atsc(IL, IR, j):
     >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
     >>> stumpy.atsc(mp[:, 2], mp[:, 3], 1)
     array([1, 3])
+
+    # Alternative example using named attributes
+    >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
+    >>> stumpy.atsc(mp.left_I_, mp.right_I_, 1)
+    array([1, 3])
     """
     C = deque([j])
     for i in range(IL.size):
@@ -118,6 +123,11 @@ def allc(IL, IR):
     >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
     >>> stumpy.allc(mp[:, 2], mp[:, 3])
     ([array([1, 3]), array([2]), array([0, 4])], array([0, 4]))
+
+    # Alternative example using named attributes
+    >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
+    >>> stumpy.allc(mp.left_I_, mp.right_I_)
+    ([array([1, 3]), array([2]), array([0, 4])], array([0, 4]))
     """
     L = np.ones(IL.size, dtype=np.int64)
     S = set()  # type: ignore

stumpy/floss.py

@@ -290,6 +290,11 @@ def fluss(I, L, n_regimes, excl_factor=5, custom_iac=None):
     >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
     >>> stumpy.fluss(mp[:, 0], 3, 2)
     (array([1., 1., 1., 1., 1.]), array([0]))
+
+    # Alternative example using named attributes
+    >>> mp = stumpy.stump(np.array([584., -11., 23., 79., 1001., 0., -19.]), m=3)
+    >>> stumpy.fluss(mp.P_, 3, 2)
+    (array([1., 1., 1., 1., 1.]), array([0]))
     """
     cac = _cac(I, L, bidirectional=True, excl_factor=excl_factor, custom_iac=custom_iac)
     regime_locs = _rea(cac, n_regimes, L, excl_factor=excl_factor)