docs: Add example notebooks. (#759)

Author: hameerabbasi

.gitignore

@@ -82,3 +82,6 @@ sparse/_version.py
 
 # Benchmark Results
 results/
+
+# Notebooks converted to scripts.
+docs/examples_ipynb/

docs/css/mkdocstrings.css

@@ -1,15 +1,15 @@
-  :root {
-    --md-primary-fg-color:        #c96c08;
-    --md-primary-fg-color--light: #94f2f7;
-    --md-primary-fg-color--dark:  #335365;
-  }
+:root {
+  --md-primary-fg-color: #c96c08;
+  --md-primary-fg-color--light: #94f2f7;
+  --md-primary-fg-color--dark: #335365;
+}
 
-  .md-tabs__item {
-    font-weight: bolder;
-  }
+.md-tabs__item {
+  font-weight: bolder;
+}
 
-  .grid {
-    font-weight: bolder;
-    font-size: 160%;
-    font-family: Georgia, serif;
-  }
+.grid {
+  font-weight: bolder;
+  font-size: 160%;
+  font-family: Georgia, serif;
+}

docs/examples/dask_example.py

@@ -0,0 +1,49 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.16.4
+#   kernelspec:
+#     display_name: sparse
+#     language: python
+#     name: python3
+# ---
+
+# # Using with Dask
+# ## Import
+
+# +
+import sparse
+
+import dask.array as da
+
+import numpy as np
+
+# -
+
+# ## Create Arrays
+#
+# Here, we create two random sparse arrays and move them to Dask.
+
+# +
+rng = np.random.default_rng(42)
+M, N = 10_000, 10_000
+DENSITY = 0.0001
+a = sparse.random((M, N), density=DENSITY)
+b = sparse.random((M, N), density=DENSITY)
+
+a_dask = da.from_array(a, chunks=1000)
+b_dask = da.from_array(b, chunks=1000)
+# -
+
+# As we can see in the "data type" section, each chunk of the Dask array is still sparse.
+
+a_dask  # noqa: B018
+
+# # Compute and check results
+# As we can see, what we get out of Dask matches what we get out of `sparse`.
+
+assert sparse.all(a + b == (a_dask + b_dask).compute())

docs/examples/formats_example.py

@@ -0,0 +1,48 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.16.4
+#   kernelspec:
+#     display_name: sparse
+#     language: python
+#     name: python3
+# ---
+
+# # Multiple Formats
+# ## Import
+# Let's set the backend and import `sparse`.
+
+# +
+import sparse
+
+import numpy as np
+
+# -
+
+
+# ## Perform Operations
+# Let's create two arrays.
+
+rng = np.random.default_rng(42)  # Seed for reproducibility
+a = sparse.random((3, 3), density=1 / 6, random_state=rng)
+b = sparse.random((3, 3), density=1 / 6, random_state=rng)
+
+# Now let's matrix multiply them.
+
+c = a @ b
+
+# And view the result as a (dense) NumPy array.
+
+c_dense = c.todense()
+
+# Now let's do the same for other formats, and compare the results.
+
+for format in ["coo", "csr", "csc"]:
+    af = sparse.asarray(a, format=format)
+    bf = sparse.asarray(b, format=format)
+    cf = af @ bf
+    np.testing.assert_array_equal(c_dense, cf.todense())

docs/examples/finch_example.py docs/examples/formats_example_finch.py

@@ -5,13 +5,14 @@
 #       extension: .py
 #       format_name: light
 #       format_version: '1.5'
-#       jupytext_version: 1.16.3
+#       jupytext_version: 1.16.4
 #   kernelspec:
 #     display_name: sparse
 #     language: python
 #     name: python3
 # ---
 
+# # Multiple Formats with Finch
 # ## Import
 # Let's set the backend and import `sparse`.
 
@@ -26,6 +27,7 @@
 
 # -
 
+
 # ## Perform Operations
 # Let's create two arrays.
 
@@ -39,4 +41,12 @@
 
 # And view the result as a (dense) NumPy array.
 
-c.todense()
+c_dense = c.todense()
+
+# Now let's do the same for other formats, and compare the results.
+
+for format in ["coo", "csr", "csc", "dense"]:
+    af = sparse.asarray(a, format=format)
+    bf = sparse.asarray(b, format=format)
+    cf = af @ bf
+    np.testing.assert_array_equal(c_dense, cf.todense())

docs/examples/scipy_example.py

@@ -0,0 +1,43 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.16.4
+#   kernelspec:
+#     display_name: sparse
+#     language: python
+#     name: python3
+# ---
+
+# # Using with SciPy
+# ## Import
+
+# +
+import sparse
+
+import numpy as np
+import scipy.sparse as sps
+
+# -
+
+# ## Create Arrays
+
+rng = np.random.default_rng(42)
+M = 1_000
+DENSITY = 0.01
+a = sparse.random((M, M), density=DENSITY, format="csc")
+identity = sparse.eye(M, format="csc")
+
+# ## Invert and verify matrix
+# This showcases the `scipy.sparse.linalg` integration.
+
+a_inv = sps.linalg.spsolve(a, identity)
+np.testing.assert_array_almost_equal((a_inv @ a).todense(), identity.todense())
+
+# ## Calculate the graph distances
+# This showcases the `scipy.sparse.csgraph` integration.
+
+sps.csgraph.bellman_ford(sparse.eye(5, k=1) + sparse.eye(5, k=-1), return_predecessors=False)

docs/javascripts/katex.js

@@ -0,0 +1,10 @@
+document$.subscribe(({ body }) => {
+  renderMathInElement(body, {
+    delimiters: [
+      { left: "$$", right: "$$", display: true },
+      { left: "$", right: "$", display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true },
+    ],
+  });
+});

docs/js/katex.js

@@ -37,7 +37,7 @@ markdown_extensions:
   - md_in_html # Used for grids
 
 extra_javascript:
-  - javascripts/katex.js
+  - js/katex.js
   - https://unpkg.com/katex@0/dist/katex.min.js
   - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
 

mkdocs.yml

@@ -35,17 +35,20 @@ docs = [
         "mkdocs-literate-nav",
         "mkdocs-section-index",
         "mkdocs-jupyter",
-        "scipy",
-        "sparse[finch]",
+        "sparse[extras]",
 ]
-tests = [
+extras = [
     "dask[array]",
+    "sparse[finch]",
+    "scipy",
+    "scikit-learn",
+]
+tests = [
+    "sparse[extras]",
     "pytest>=3.5",
     "pytest-cov",
     "pytest-xdist",
     "pre-commit",
-    "scipy",
-    "sparse[finch]",
     "pytest-codspeed",
 ]
 tox = ["sparse[tests]", "tox"]
@@ -93,3 +96,7 @@ section-order = [
     "numpy",
     "local-folder",
 ]
+
+[tool.jupytext.formats]
+"docs/examples_ipynb/" = "ipynb"
+"docs/examples/" = "py:light"