diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3b00037..4b51228 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,13 +11,14 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: "v6.0.0" hooks: - #- id: check-added-large-files + - id: check-added-large-files - id: check-ast - id: check-case-conflict - id: check-json - id: check-merge-conflict - id: check-symlinks - id: check-yaml + exclude: ^mkdocs\.yml$ # otherwise !!python/name:mermaid2.fence_mermaid in .mkdocs.yaml make it fail - id: debug-statements - id: detect-private-key - id: end-of-file-fixer diff --git a/docs/NAVIGATION.md b/docs/NAVIGATION.md index 0dc65ec..cb4b00a 100644 --- a/docs/NAVIGATION.md +++ b/docs/NAVIGATION.md @@ -9,6 +9,7 @@ See https://oprypin.github.io/mkdocs-literate-nav/ - [Tutorials](tutorials/index.md) - [Further background](further-background/index.md) - [Dependency pinning and testing](further-background/dependency-pinning-and-testing.md) + - [Model architecture](further-background/model-architecture.md) - [Development](development.md) - [API reference](api/pymc_elicito/) - [Changelog](changelog.md) diff --git a/docs/further-background/index.md b/docs/further-background/index.md index 3a766ee..3517142 100644 --- a/docs/further-background/index.md +++ b/docs/further-background/index.md @@ -11,5 +11,4 @@ Points we will aim to cover: - Why it was created - Help the reader make connections -We will aim to avoid writing instructions or technical descriptions here, -they belong elsewhere. +We will aim to avoid writing instructions or technical descriptions here, they belong elsewhere. diff --git a/docs/further-background/model-architecture.md b/docs/further-background/model-architecture.md new file mode 100644 index 0000000..965ed09 --- /dev/null +++ b/docs/further-background/model-architecture.md @@ -0,0 +1,66 @@ +```mermaid +flowchart TB + subgraph eliobj["Elicit class (user input)"] + input["Model, Parameters, Targets, \n Network, Initializer, Optimizer, \n Meta-Setting"] + expert_dat["expert elicited summaries"] + end + subgraph initialization["initialization"] + initializer["initializer"] + hyper_parametric("prior parameters") + hyper_deep("weights/biases of DNNs") + end + + subgraph subGraph3["priors"] + transformation["transform to constrained space"] + prior["sample from prior in \n unconstrained space"] + end + subgraph model["model"] + generative_model["run generative model \n in forward mode"] + end + subgraph summaries["summaries"] + elicits["elicited summaries"] + summary["target quantities"] + end + subgraph loss["loss"] + total_loss["total loss"] + indiv_loss["individual losses"] + end + subgraph optimization["optimization"] + gradients["gradients"] + end + subgraph training["training"] + subGraph3 + prior_samples[/"prior samples"/] + model + model_output[/"model simulations"/] + summaries + simulated_summaries[/"simulated summaries"/] + loss + optimization + check{"convergence \n criterion"} + train_vars[/"trainable variables \n (=hyperparameters)"/] + end + input --> initializer + initializer -- if parametric prior --> hyper_parametric + initializer -- if deep prior --> hyper_deep + hyper_parametric --> train_vars + hyper_deep --> train_vars + train_vars --> prior + expert_dat --> indiv_loss & input + prior --> transformation + transformation --> prior_samples + prior_samples --> generative_model + generative_model --> model_output + model_output --> summary + summary --> elicits + elicits --> simulated_summaries + simulated_summaries --> indiv_loss + indiv_loss --> total_loss + total_loss --> gradients + gradients --> check + check -- not reached:
update --> train_vars + check -- reached --> stop((("stop"))) + + classDef data shape: lean-r + class prior_samples data +``` diff --git a/mkdocs.yml b/mkdocs.yml index 106fd4c..57180d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,7 @@ theme: name: Switch to light mode plugins: + - mermaid2 # https://mkdocstrings.github.io/autorefs/ - autorefs # Required for auto-generating our documentation stubs @@ -121,6 +122,11 @@ plugins: - section-index markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:mermaid2.fence_mermaid # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#attribute-lists - attr_list - footnotes diff --git a/pyproject.toml b/pyproject.toml index afb7437..205dbb9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -96,6 +96,7 @@ dev = [ docs = [ # Key dependencies # ---------------- + "mkdocs-mermaid2-plugin>=1.2.3", "attrs==25.3.0", "mkdocs-autorefs==1.4.2", "mkdocs-gen-files==0.5.0", diff --git a/requirements-docs-locked.txt b/requirements-docs-locked.txt index fc60762..45c6abd 100644 --- a/requirements-docs-locked.txt +++ b/requirements-docs-locked.txt @@ -25,6 +25,7 @@ cycler==0.12.1 debugpy==1.8.11 decorator==5.1.1 defusedxml==0.7.1 +editorconfig==0.17.1 exceptiongroup==1.3.0 ; python_full_version < '3.11' executing==2.1.0 fastjsonschema==2.21.1 @@ -46,6 +47,7 @@ ipython-pygments-lexers==1.1.1 ; python_full_version >= '3.11' isoduration==20.11.0 jedi==0.19.2 jinja2==3.1.5 +jsbeautifier==1.15.4 json5==0.10.0 jsonpointer==3.0.0 jsonschema==4.23.0 @@ -80,6 +82,7 @@ mkdocs-jupyter==0.25.1 mkdocs-literate-nav==0.6.2 mkdocs-material==9.6.16 mkdocs-material-extensions==1.3.1 +mkdocs-mermaid2-plugin==1.2.3 mkdocs-section-index==0.3.10 mkdocstrings==0.30.0 mkdocstrings-python==1.16.12 diff --git a/uv.lock b/uv.lock index 99c4e92..9c8ef5f 100644 --- a/uv.lock +++ b/uv.lock @@ -730,6 +730,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/91/a1/cf2472db20f7ce4a6be1253a81cfdf85ad9c7885ffbed7047fb72c24cf87/distlib-0.3.9-py2.py3-none-any.whl", hash = "sha256:47f8c22fd27c27e25a65601af709b38e4f0a45ea4fc2e710f65755fa8caaaf87", size = 468973, upload-time = "2024-10-09T18:35:44.272Z" }, ] +[[package]] +name = "editorconfig" +version = "0.17.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/88/3a/a61d9a1f319a186b05d14df17daea42fcddea63c213bcd61a929fb3a6796/editorconfig-0.17.1.tar.gz", hash = "sha256:23c08b00e8e08cc3adcddb825251c497478df1dada6aefeb01e626ad37303745", size = 14695, upload-time = "2025-06-09T08:21:37.097Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/96/fd/a40c621ff207f3ce8e484aa0fc8ba4eb6e3ecf52e15b42ba764b457a9550/editorconfig-0.17.1-py3-none-any.whl", hash = "sha256:1eda9c2c0db8c16dbd50111b710572a5e6de934e39772de1959d41f64fc17c82", size = 16360, upload-time = "2025-06-09T08:21:35.654Z" }, +] + [[package]] name = "exceptiongroup" version = "1.3.0" @@ -1109,6 +1118,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/bd/0f/2ba5fbcd631e3e88689309dbe978c5769e883e4b84ebfe7da30b43275c5a/jinja2-3.1.5-py3-none-any.whl", hash = "sha256:aba0f4dc9ed8013c424088f68a5c226f7d6097ed89b246d7749c2ec4175c6adb", size = 134596, upload-time = "2024-12-21T18:30:19.133Z" }, ] +[[package]] +name = "jsbeautifier" +version = "1.15.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "editorconfig" }, + { name = "six" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ea/98/d6cadf4d5a1c03b2136837a435682418c29fdeb66be137128544cecc5b7a/jsbeautifier-1.15.4.tar.gz", hash = "sha256:5bb18d9efb9331d825735fbc5360ee8f1aac5e52780042803943aa7f854f7592", size = 75257, upload-time = "2025-02-27T17:53:53.252Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2d/14/1c65fccf8413d5f5c6e8425f84675169654395098000d8bddc4e9d3390e1/jsbeautifier-1.15.4-py3-none-any.whl", hash = "sha256:72f65de312a3f10900d7685557f84cb61a9733c50dcc27271a39f5b0051bf528", size = 94707, upload-time = "2025-02-27T17:53:46.152Z" }, +] + [[package]] name = "json5" version = "0.10.0" @@ -1991,6 +2013,23 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" }, ] +[[package]] +name = "mkdocs-mermaid2-plugin" +version = "1.2.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "beautifulsoup4" }, + { name = "jsbeautifier" }, + { name = "mkdocs" }, + { name = "pymdown-extensions" }, + { name = "requests" }, + { name = "setuptools" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/2a/6d/308f443a558b6a97ce55782658174c0d07c414405cfc0a44d36ad37e36f9/mkdocs_mermaid2_plugin-1.2.3.tar.gz", hash = "sha256:fb6f901d53e5191e93db78f93f219cad926ccc4d51e176271ca5161b6cc5368c", size = 16220, upload-time = "2025-10-17T19:38:53.047Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1a/4b/6fd6dd632019b7f522f1b1f794ab6115cd79890330986614be56fd18f0eb/mkdocs_mermaid2_plugin-1.2.3-py3-none-any.whl", hash = "sha256:33f60c582be623ed53829a96e19284fc7f1b74a1dbae78d4d2e47fe00c3e190d", size = 17299, upload-time = "2025-10-17T19:38:51.874Z" }, +] + [[package]] name = "mkdocs-section-index" version = "0.3.10" @@ -2958,6 +2997,7 @@ all-dev = [ { name = "mkdocs-literate-nav" }, { name = "mkdocs-material" }, { name = "mkdocs-material-extensions" }, + { name = "mkdocs-mermaid2-plugin" }, { name = "mkdocs-section-index" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, @@ -3128,6 +3168,7 @@ docs = [ { name = "mkdocs-literate-nav" }, { name = "mkdocs-material" }, { name = "mkdocs-material-extensions" }, + { name = "mkdocs-mermaid2-plugin" }, { name = "mkdocs-section-index" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, @@ -3291,6 +3332,7 @@ all-dev = [ { name = "mkdocs-literate-nav", specifier = "==0.6.2" }, { name = "mkdocs-material", specifier = "==9.6.16" }, { name = "mkdocs-material-extensions", specifier = "==1.3.1" }, + { name = "mkdocs-mermaid2-plugin", specifier = ">=1.2.3" }, { name = "mkdocs-section-index", specifier = "==0.3.10" }, { name = "mkdocstrings", specifier = "==0.30.0" }, { name = "mkdocstrings-python", specifier = "==1.16.12" }, @@ -3461,6 +3503,7 @@ docs = [ { name = "mkdocs-literate-nav", specifier = "==0.6.2" }, { name = "mkdocs-material", specifier = "==9.6.16" }, { name = "mkdocs-material-extensions", specifier = "==1.3.1" }, + { name = "mkdocs-mermaid2-plugin", specifier = ">=1.2.3" }, { name = "mkdocs-section-index", specifier = "==0.3.10" }, { name = "mkdocstrings", specifier = "==0.30.0" }, { name = "mkdocstrings-python", specifier = "==1.16.12" },