book updates

vlc · Feb 2, 2022 · 246a406 · 246a406
1 parent 13d643c
commit 246a406
Show file tree

Hide file tree

Showing 13 changed files with 223 additions and 42 deletions.
diff --git a/book/_build.sh b/book/_build.sh
@@ -1,3 +1,4 @@
-#!/bin/zsh
+#!/bin/bash
+conda info
 python _scripts/hide_test_cells.py
 jb build .
diff --git a/book/_config.yml b/book/_config.yml
@@ -47,6 +47,7 @@ sphinx:
     - 'sphinx.ext.intersphinx'
     - 'sphinx.ext.doctest'
     - 'sphinx.ext.graphviz'
+    - 'sphinx.ext.viewcode'
   mathjax_config:
     TeX:
       Macros:
@@ -73,5 +74,31 @@ sphinx:
     conda:
       - "https://docs.conda.io/projects/conda/en/latest/"
       - null
+    xarray:
+      - "https://xarray.pydata.org/en/stable/"
+      - null
   config:
     bibtex_reference_style: author_year
+    autosummary_generate: True
+    autodoc_default_options:
+      show-inheritance: True
+    add_module_names: False
+    html_theme_options:
+      home_page_in_toc: false
+      search_bar_text: Search these docs...
+      repository_url: https://github.com/jpn--/larch
+      use_repository_button: true
+      use_issues_button: true
+      repository_branch: master
+      path_to_docs: docs
+      extra_navbar:
+      favicons:
+      - rel: icon
+        sizes: 32x32
+        href: img/larch_favicon.png
+      switcher:
+        json_url: "https://larch.newman.me/_static/switcher.json"
+        url_template: "https://larch.newman.me/v{version}/"
+        version_match: "5.5.10"
+      navbar_end:
+      - version-switcher
diff --git a/book/_toc.yml b/book/_toc.yml
@@ -17,6 +17,8 @@ parts:
     chapters:
     - file: api/~data
       sections:
+        - file: api/dataset
+        - file: api/datatree
         - file: api/dataframes
     - file: api/linear
     - file: api/~models

diff --git a/book/api/dataframes.rst b/book/api/dataframes.rst
@@ -2,8 +2,10 @@
 DataFrames
 ==========
 
+The :ref:`DataFrames` interface for larch remains available for use, but future
+development on this package will be on the :ref:`Dataset`/:ref:`DataTree` interface.
+
 .. autosummary::
     :toctree: generated/
 
     larch.DataFrames
-
diff --git a/book/api/dataset.rst b/book/api/dataset.rst
@@ -0,0 +1,50 @@
+.. currentmodule:: larch
+
+=======
+Dataset
+=======
+
+Constructors
+------------
+
+.. autosummary::
+    :toctree: generated/
+
+    Dataset
+    Dataset.from_idca
+    Dataset.from_idco
+    Dataset.construct
+
+Attributes
+----------
+
+.. autosummary::
+    :toctree: generated/
+
+    Dataset.n_cases
+    Dataset.n_alts
+    Dataset.CASEID
+    Dataset.ALTID
+    Dataset.dims
+    Dataset.sizes
+    Dataset.data_vars
+    Dataset.coords
+    Dataset.attrs
+    Dataset.encoding
+    Dataset.indexes
+    Dataset.chunks
+    Dataset.chunksizes
+    Dataset.nbytes
+
+Methods
+-------
+
+.. autosummary::
+    :toctree: generated/
+
+    Dataset.caseids
+    Dataset.dissolve_zero_variance
+    Dataset.query_cases
+    Dataset.set_altnames
+    Dataset.set_dtypes
+    Dataset.setup_flow
diff --git a/book/api/datatree.rst b/book/api/datatree.rst
@@ -0,0 +1,8 @@
+=============
+DataTree Home
+=============
+
+.. autosummary::
+    :toctree: generated/
+
+    larch.DataTree
diff --git a/book/example/101_swissmetro_mnl.ipynb b/book/example/101_swissmetro_mnl.ipynb
@@ -12,7 +12,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "09dd4536",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -292,7 +296,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "fda7d9c1",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",

diff --git a/book/example/102-swissmetro-weighted.ipynb b/book/example/102-swissmetro-weighted.ipynb
@@ -12,7 +12,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "faf59f97",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -190,7 +194,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "64f60ffb",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -221,7 +229,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "baf04617",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",

diff --git a/book/example/109-swissmetro-nl.ipynb b/book/example/109-swissmetro-nl.ipynb
@@ -12,7 +12,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "2c734ca6",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -191,7 +195,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "7e8649b5",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -222,7 +230,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "025ba5f9",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",
@@ -272,7 +284,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "7133fda4",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "remove_cell"
+    ]
+   },
    "outputs": [],
    "source": [
     "# TEST\n",

diff --git a/book/example/examples.rst b/book/example/examples.rst
diff --git a/book/example/legacy.md b/book/example/legacy.md
@@ -1,3 +1,4 @@
+(deprecated-examples)=
 # Deprecated Example Models
 
 Future development of Larch will be on version that sits on numba, xarray, and sharrow,

diff --git a/book/intro.md b/book/intro.md
@@ -4,21 +4,26 @@
 [![conda-forge](https://img.shields.io/conda/dn/conda-forge/larch)](https://anaconda.org/conda-forge/larch)
 [![conda-forge](https://img.shields.io/azure-devops/build/wire-paladin/larch/jpn--.larch/master)](https://dev.azure.com/wire-paladin/larch/_build?definitionId=1&_a=summary&repositoryFilter=1&branchFilter=5%2C5%2C5%2C5%2C5%2C5)
 
-🏆︁ Winner of the [AGIFORS 56th Annual Symposium Best Innovation award](http://agifors.org/Symposium>).
+🏆︁ Winner of the [AGIFORS 56th Annual Symposium Best Innovation award](http://agifors.org/Symposium).
 
 This documentation is for the Python interface for Larch. If this is your first go
 with Larch, or the first go on a new computer, you might want to start with [installation](installation).
 
 Larch is undergoing a transformation, with a new computational architecture
 that can significantly improve performance when working with large datasets.
-The new code relies on [numba](https://numba.pydata.org/),
+The old version of Larch used a carefully customized `DataFrames` object to
+organize several different aspects of discrete choice data.
+The new code uses a more standardized (although still enhanced) `xarray.Dataset`
+interface for data, and relies on [numba](https://numba.pydata.org/),
 [xarray](https://xarray.pydata.org/en/stable/), and
 [sharrow](https://activitysim.github.io/sharrow) to enable super-fast estimation
 of choice models.  Many (but not yet all) of the core features of Larch have been moved
 over to this new platform.
 
-You can still use the old version of Larch as normal, but to try out the new version
-just import `larch.numba` instead of larch itself.
+*You can still use the old version of Larch as normal.* If you want to try out the new version,
+just import `larch.numba` instead of larch itself.  All of the compatible examples in this
+documentation are being migrated over to the new platform, but the old examples remain
+available for now under the [Deprecated Examples](deprecated-examples) section.
 
 :::{note}
 This project is very much under development.  There are plenty of undocumented functions