From 91bdd5d097f0748e30cb6e02924fa15ffa8c1621 Mon Sep 17 00:00:00 2001
From: Matthew Wardrop <mpwardrop@gmail.com>
Date: Wed, 27 Sep 2023 22:03:18 -0700
Subject: [PATCH] Update the quickstart docs to mention model specs.

---
 docsite/docs/guides/quickstart.ipynb | 83 ++++++++++++++++++++++++----
 1 file changed, 72 insertions(+), 11 deletions(-)

diff --git a/docsite/docs/guides/quickstart.ipynb b/docsite/docs/guides/quickstart.ipynb
index 3b68d51e..ed1abd2c 100644
--- a/docsite/docs/guides/quickstart.ipynb
+++ b/docsite/docs/guides/quickstart.ipynb
@@ -22,7 +22,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -42,7 +42,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
@@ -93,7 +93,7 @@
        "2  2"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -104,7 +104,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [
     {
@@ -175,7 +175,7 @@
        "2        1.0       0       1  0.2       0.0       0.2"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 3,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -199,7 +199,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -278,7 +278,7 @@
        "2        1.0       0       0       1  0.2       0.0       0.0       0.2"
       ]
      },
-     "execution_count": 9,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -294,7 +294,38 @@
    "metadata": {},
    "source": [
     "\n",
-    "Note that the dropped level in `a` has been restored.\n"
+    "Note that the dropped level in `a` has been restored.\n",
+    "\n",
+    "There is a rich trove of information about the columns and structure of the the \n",
+    "model matrix stored in the `ModelSpec` instance attached to the model matrix,\n",
+    "for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ModelSpec(formula=1 + a + b + a:b, materializer='pandas', materializer_params={}, ensure_full_rank=False, na_action=<NAAction.DROP: 'drop'>, output='pandas', cluster_by=<ClusterBy.NONE: 'none'>, structure=[EncodedTermStructure(term=1, scoped_terms=[1], columns=['Intercept']), EncodedTermStructure(term=a, scoped_terms=[a], columns=['a[T.A]', 'a[T.B]', 'a[T.C]']), EncodedTermStructure(term=b, scoped_terms=[b], columns=['b']), EncodedTermStructure(term=a:b, scoped_terms=[a:b], columns=['a[T.A]:b', 'a[T.B]:b', 'a[T.C]:b'])], transform_state={}, encoder_state={'a': (<Kind.CATEGORICAL: 'categorical'>, {'categories': ['A', 'B', 'C']}), 'b': (<Kind.NUMERICAL: 'numerical'>, {})})"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "X.model_spec"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can read more about the model specs in the [Model Specs](../model_specs/) documentation."
    ]
   },
   {
@@ -311,7 +342,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -321,7 +352,7 @@
        "\twith 10 stored elements in Compressed Sparse Column format>"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -337,6 +368,36 @@
    "source": [
     "In this example, `X` is a \\\\( 6 \\times 3 \\\\) `scipy.sparse.csc_matrix` instance.\n",
     "\n",
+    "Since sparse matrices do not have labels for columns, you can look these up from\n",
+    "the model spec described above; for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('Intercept', 'a[T.B]', 'a[T.C]', 'b', 'a[T.B]:b', 'a[T.C]:b')"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "X.model_spec.column_names"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "\n",
     "[^1]: `X` must be full-rank in order for the regression algorithm to invert a matrix derived from `X`.\n"
    ]
   }
@@ -357,7 +418,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.15"
+   "version": "3.10.13"
   },
   "orig_nbformat": 4,
   "vscode": {