Compile docs from inlined comments.

- Add _toc.yml - Add _config.yml - Add references.bib, references.md - Switch to pure pyproject.toml - Switch to a src layout (avoids conflicts with other folders in root, like `figures`) - Add GitHub action to build book (untested, from cookicutter)
alcrene · Dec 29, 2023 · a9199a2 · a9199a2
1 parent eed1e58
commit a9199a2
Show file tree

Hide file tree

Showing 25 changed files with 4,288 additions and 209 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,54 @@
+name: deploy-book
+
+on:
+  # Trigger the workflow on push to main branch
+  push:
+    branches:
+      - main
+  # Also allow manual trigger
+  workflow_dispatch:
+
+env:
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+
+      # Install dependencies
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          pip install .
+
+      # Build the book
+      - name: Build the book
+        run: |
+          jupyter-book build emd-paper_notebooks
+
+      # Upload the book's HTML as an artifact
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "_build/html"
+
+      # Deploy the book's HTML to GitHub Pages
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,8 @@
 build
 *.joblib-cache
 *.pytest_cache
+*.jupyter
+*.jupyter_cache
 
 purgatory
 emd_falsify/*.md

diff --git a/README.md b/README.md
@@ -67,4 +67,4 @@ This will print messages to your console reporting how much time each computatio
 
 The current implementation of the hierarchical beta process (used for sampling quantile paths) has seen quite a lot of testing for numerical stability, but little optimization effort. In particular it makes a lot of calls to functions in `scipy.optimize`, which makes the whole function quite slow: even with a relatively complicated data model like the [pyloric circuit](https://alcrene.github.io/pyloric-network-simulator/pyloric_simulator/prinz2004.html), drawing quantile paths can still take 10x longer than generating the data.
 
-Substantial performance improvements to the sampling algorithm are almost certainly possible with dedicated computer science effort. Since that is the current bottleneck, that would also proportionately reduce compute time for the whole EMD procedure.
+Substantial performance improvements to the sampling algorithm are almost certainly possible with dedicated computer science effort. Since that is the current bottleneck, that would also proportionately reduce compute time for the whole EMD procedure.
diff --git a/_config.yml b/_config.yml
@@ -0,0 +1,108 @@
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# See the documentation for help and more options: 
+# https://jupyterbook.org/customize/config.html
+
+#######################################################################################
+# Book settings
+title                       : EMD-falsify  # The title of the book. Will be placed in the left navbar.
+author                      : Alexandre René  # The author of the book
+copyright                   : "2023"  # Copyright year to be placed in the footer
+logo                        : ""  # A path to the book logo
+exclude_patterns            : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints", ".*", "**.egg-info", "*.mypy_cache", "**__pycache__", "**/.pytest_cache",
+                               ".jupyter", ".jupyter_cache",
+                               "**purgatory", "**.smt"]
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+  cache            : ".jupyter_cache"
+  exclude_patterns : ["**purgatory",
+                      "tasks.md",  # Not executable as a notebook (Task is split over multiple cells)
+                    ]
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: emd-falsify.tex
+
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    - amsmath
+    - colon_fence
+    - deflist
+    - dollarmath
+    # - html_admonition
+    - html_image
+    - linkify
+    - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
+  myst_linkify_fuzzy_links: false
+  myst_dmath_allow_labels: true
+  myst_heading_anchors: 2
+  myst_substitutions:
+    prolog: |
+      ```{role} raw-latex(raw)
+          :format: latex
+      ```
+      ```{role} raw-html(raw)
+          :format: html
+      ```
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/alcrene/emd-falsify  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+# Sphinx options
+
+sphinx:
+  config:
+    mathjax_config:
+      # The `mtext` font is used for non-math symbols, like the content of `\text` commands.
+      # By inheriting this font, we ensure that textual elements in equations use the same font
+      # as the main text of our book. Otherwise text is rendered in the TeX Serif font, which looks out of place on a web page with sans serif.
+      # NB: Not just the font family, but the actual font is matched.
+      chtml:
+        mtextInheritFont: true
+      svg:
+        mtextInheritFont: true
+      tex:
+        macros:
+          "nN"    : "\\mathcal{N}"
+          "RR"    : "\\mathbb{R}"
+          "EE"   : "{\\mathbb{E}}"
+          "VV"   : "{\\mathbb{V}}"
+          "Unif"  : "\\mathop{\\mathrm{Unif}}"
+          "Beta" : "{\\mathop{\\mathrm{Beta}}}"
+          # emd.md
+          "D"     : "\\mathcal{D}"
+          "l"     : "l"
+          "Me"    : "\\mathcal{M}^ε"
+          "Philt" : ["\\widetilde{Φ}_{|#1}", 1]
+          "Bemd"  : ["B_{#1}^{\\mathrm{EMD}}", 1]
+          # path_sampling.md
+          "lnLtt": "{\\tilde{l}}"
+          "Mvar" : "{\\mathop{\\mathrm{Mvar}}}"
+          "pathP": "{\\mathop{\\mathcal{P}}}"
+          "lnLh" : "{\\hat{l}}"
+          "emdstd": "{\\tilde{σ}}"
+          "EMD"  : "{\\mathrm{EMD}}"
+
diff --git a/_toc.yml b/_toc.yml
@@ -0,0 +1,12 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: README
+chapters:
+- file: src/emd_falsify/emd
+- file: src/emd_falsify/path_sampling
+- file: src/emd_falsify/tasks
+- file: src/emd_falsify/viz
+- file: src/emd_falsify/config/__init__.md
+- file: references
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,89 @@
 [build-system]
-requires = ["setuptools>=42", "wheel", "Cython", "setuptools_scm[toml]>=6.2"]
-build-backend = "setuptools.build_meta:__legacy__"
+requires = ["setuptools>=61.0.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
 
-# setuptools_scm allows to automatically include git-tracked files in package 
-[tool.setuptools_scm]
+[tool.setuptools_scm]
+write_to = "src/emd_falsify/_version.py"
+
+[project.urls]
+#"Documentation" =
+"Bug Tracker" = "https://github.com/alcrene/emd-falsify/issues"
+"Source" = "https://github.com/alcrene/emd-falsify"
+
+[project]
+name        = "emd-falsify"
+authors = [
+    {name = "Alexandre René", email="arene010@uottawa.ca"},
+]
+description = "Original implementation of the EMD (empirical model discrepancy) model comparison criterion"
+readme      = "README.md"
+requires-python = ">=3.7"
+
+license = {text = "MPL 2.0"}
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Statistics",
+]
+keywords = [
+    "empirical model discrepancy",
+    "bayes factor",
+    "inference",
+    "model comparison",
+    "bayesian",
+]
+
+dependencies = [
+    "more-itertools",
+    "numpy",
+    "scipy>=1.7",  # integrate.simpson changed name (used to be 'simps')
+    "pydantic>=1.8.2",
+    "tqdm",
+    "joblib",
+        # joblib is used for on-disk caching of calculations used in calibration plots    
+    "scityping",
+    "valconfig>=0.1.2-rc3",
+]
+
+dynamic = ["version"]
+
+[project.optional-dependencies]
+
+## Development dependencies
+dev = ["pytest"]
+
+## Dependencies of the `viz` utilities module ##
+viz = ["pandas", "matplotlib", "seaborn", "holoviews", "addict"]
+    # 'addict' used by valconfig.contrib.holoviews
+
+
+## Executing notebooks and building “code browser” pages ##
+doc = [
+    "jupyter-book>=0.14",
+    "sphinx-proof",
+    "jupytext",
+    "ipykernel",
+    "holoviews",
+    "bokeh",
+    "jupyter_bokeh",
+
+    # For bokeh export to png (also used by holoviews)
+    "selenium",
+    "phantomjs",
+    "pillow",
+
+    ## Needed only for `tasks` notebook (which is not executable as a notebook)
+    #"smttask>=0.2.0-rc3",
+
+    # For pushing Jupyter book to Github Pages
+    "ghp-import",
+]
diff --git a/references.bib b/references.bib
@@ -0,0 +1,39 @@
+@article{gillespieMathematicsBrownianMotion1996,
+  title = {The Mathematics of {{Brownian}} Motion and {{Johnson}} Noise},
+  author = {Gillespie, Daniel T.},
+  year = {1996},
+  month = mar,
+  journal = {American Journal of Physics},
+  volume = {64},
+  number = {3},
+  pages = {225--240},
+  issn = {0002-9505, 1943-2909},
+  doi = {10.1119/1.18210},
+  urldate = {2014-04-23},
+  abstract = {One reason why Brownian motion and Johnson noise are difficult subjects to teach is that their mathematical requirements transcend the capabilities of ordinary differential calculus. Presented here is an exposition of the needed generalization of calculus, namely continuous Markov process theory, in a form that should be accessible to advanced physics undergraduates. It is shown how this mathematical framework enables one to give clear, concise derivations of all the principal results of Brownian motion and Johnson noise, including fluctuation{\textendash}dissipation formulas, auto-covariance transport formulas, spectral density formulas, Nyquist's formula, the notions of white and 1/f 2noise, and an accurate numerical simulation algorithm. An added benefit of this exposition is a clearer view of the mathematical connection between the two very different approaches to Brownian motion taken by Einstein and Langevin in their pioneering papers of 1905 and 1908.},
+  keywords = {1/f noise,Brownian motion,Calculus,dynamical system,Fokker-Planck equation,Markov processes,primer,stochastic,Thermal noise},
+  file = {/home/rene/var/Zotero/storage/PPKWD7XS/Gillespie - 1996 - The mathematics of Brownian motion and Johnson noi.pdf;/home/rene/var/Zotero/storage/TQB5NDW7/1.html}
+}
+
+@incollection{mateu-figuerasDistributionsSimplexRevisited2021,
+  title = {Distributions on the {{Simplex Revisited}}},
+  booktitle = {Advances in {{Compositional Data Analysis}}: {{Festschrift}} in {{Honour}} of {{Vera Pawlowsky-Glahn}}},
+  author = {{Mateu-Figueras}, Gloria and Monti, Gianna S. and Egozcue, J. J.},
+  editor = {Filzmoser, Peter and Hron, Karel and {Mart{\'i}n-Fern{\'a}ndez}, Josep Antoni and {Palarea-Albaladejo}, Javier},
+  year = {2021},
+  pages = {61--82},
+  publisher = {{Springer International Publishing}},
+  address = {{Cham}},
+  doi = {10.1007/978-3-030-71175-7_4},
+  urldate = {2022-12-26},
+  abstract = {A large number of families of distributions are available to model multivariate real vectors. On the contrary, for the simplex sample space, we have only a limited number of families arising through the generalization of the Dirichlet family or the logratio normal family. This chapter tries to summarize those models and some generalizations with a special emphasis on the algebraic-geometric structure of the simplex and on the measure which is considered compatible. In particular, the shifted-scaled Dirichlet distribution is studied and the logratio t distribution is rewritten and studied with respect to the Aitchison measure.},
+  isbn = {978-3-030-71175-7},
+  langid = {english},
+  file = {/home/rene/var/Zotero/storage/A6H585YL/Mateu-Figueras et al_2021_Distributions on the Simplex Revisited.pdf}
+}
+
+@unpublished{reneFalsifyingModels2024,
+  title = {Falsifying models using empirical loss discrepancy},
+  author = {René, Alexandre and Longtin, André},
+  note = {In preparation}
+}
diff --git a/references.md b/references.md
@@ -0,0 +1,5 @@
+# References
+
+```{bibliography}
+:style: unsrt
+```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -67,4 +67,4 @@ This will print messages to your console reporting how much time each computatio

		The current implementation of the hierarchical beta process (used for sampling quantile paths) has seen quite a lot of testing for numerical stability, but little optimization effort. In particular it makes a lot of calls to functions in `scipy.optimize`, which makes the whole function quite slow: even with a relatively complicated data model like the [pyloric circuit](https://alcrene.github.io/pyloric-network-simulator/pyloric_simulator/prinz2004.html), drawing quantile paths can still take 10x longer than generating the data.

		Substantial performance improvements to the sampling algorithm are almost certainly possible with dedicated computer science effort. Since that is the current bottleneck, that would also proportionately reduce compute time for the whole EMD procedure.
		Substantial performance improvements to the sampling algorithm are almost certainly possible with dedicated computer science effort. Since that is the current bottleneck, that would also proportionately reduce compute time for the whole EMD procedure.