Repository navigation
Initial docs - #8
Merged
Merged
Conversation
Expanded the docs landing page to better explain the separation between AlgebraicEpiMech and ConfigurableEpi. The narrative now highlights algebraic composition, observation structure, and the handoff from mechanistic Petri-net construction to stochastic inference and forecasting, with a clearer flowchart and updated package descriptions.
This commit revises the getting-started guide to explain the typed Petri net setup for the SIR model more clearly. It adds context for using `create_model`, `dom`, and `vectorfield_flat`, clarifies the expected input-vector naming convention, and expands the follow-on guidance with a new "Next steps" section linking to more advanced model examples.
Add a new getting-started section explaining how typed Petri nets compose via pullbacks over a shared type system and pushouts for observation attachments. It clarifies the role of typing morphisms, how compatible model structure is matched through a common codomain, and how `typed_product` and `attach_observation` fit into the workflow.
This commit improves the getting-started and package docs to better explain typed Petri nets, their pullback construction, and the relationship between AlgebraicEpiMech and ConfigurableEpi. It clarifies how species and transition typing structure epidemic models, explains the role of vector fields and model composition, and fixes LaTeX-style subscripts in the getting started guide.
Enable `mdstrings=true` in `julia-docs/examples.jl` and convert narrative `#` comments in Julia examples to `md"""..."""` blocks (with `using Markdown #hide`) so Literate emits structured markdown content reliably. This updates multiple example files while preserving code behavior, with only minor formatting cleanups and a small numeric literal normalization.
Improve the compartmental models example in both the rendered markdown and Julia source by clarifying typed Petri net terminology, diagram interpretation, ODE solving with `Tsit5`, and the distinction between prevalence and incidence observation chains. The section headings are also reorganized to make the progression through model variants easier to follow.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Documented CI guarantees are not implemented, and generated API references currently contain broken escaped links.
Review effort: Balanced
Findings: 3
Open (8)
What changed in this PR
Introduces the project’s documentation site, generation tooling, deployment workflow, API references, and executable Julia examples.
Changes:
- Adds Zensical/uv configuration and GitHub Pages deployment.
- Adds Documenter/Literate generation for API and example pages.
- Adds package guides and cleans up a redundant test block.
| File | Description |
|---|---|
zensical.toml |
Configures site navigation and rendering. |
pyproject.toml |
Defines Python documentation dependencies. |
justfile |
Adds documentation and test recipes. |
julia-docs/src/configurableepi.md |
Defines ConfigurableEpi API generation. |
julia-docs/src/algebraicepimech.md |
Defines AlgebraicEpiMech API generation. |
julia-docs/Project.toml |
Defines the Julia docs environment. |
julia-docs/make.jl |
Generates API Markdown. |
julia-docs/examples/stratified_models.jl |
Adds the stratification example. |
julia-docs/examples/multistrain_immune_history.jl |
Adds the multistrain example. |
julia-docs/examples/low_level_filtering.jl |
Adds low-level filtering examples. |
julia-docs/examples/inference_engines.jl |
Demonstrates inference engines. |
julia-docs/examples/compartmental_models.jl |
Demonstrates compartmental models. |
julia-docs/examples/arrival_process.jl |
Demonstrates arrival processes. |
julia-docs/examples.jl |
Generates executed example pages. |
docs/packages/configurableepi.md |
Documents ConfigurableEpi concepts. |
docs/packages/algebraicepimech.md |
Documents AlgebraicEpiMech concepts. |
docs/javascripts/mathjax.js |
Enables dynamic MathJax rendering. |
docs/index.md |
Adds the documentation homepage. |
docs/getting-started.md |
Adds installation and introductory guidance. |
docs/examples/stratified_models.md |
Adds generated stratification documentation. |
docs/examples/stratified_models-7.svg |
Adds a stratification diagram. |
docs/examples/multistrain_immune_history.md |
Adds generated multistrain documentation. |
docs/examples/multistrain_immune_history-6.svg |
Adds an independent-strain diagram. |
docs/examples/multistrain_immune_history-10.svg |
Adds a competing-strain diagram. |
docs/examples/low_level_filtering.md |
Adds generated filtering documentation. |
docs/examples/inference_engines.md |
Adds generated inference documentation. |
docs/examples/compartmental_models.md |
Adds generated compartmental documentation. |
docs/examples/compartmental_models-8.svg |
Adds an SIR diagram. |
docs/examples/compartmental_models-5.svg |
Adds a typed SIR diagram. |
docs/examples/compartmental_models-21.svg |
Adds an observation-chain diagram. |
docs/examples/compartmental_models-12.svg |
Adds a typed SEIR diagram. |
docs/examples/arrival_process.md |
Adds generated arrival-process documentation. |
docs/development/docs.md |
Documents maintenance procedures. |
AlgebraicEpiMech/test/test_vectorfield_flat.jl |
Consolidates nested flattening tests. |
.python-version |
Selects Python 3.12. |
.gitignore |
Ignores generated site output. |
.github/workflows/docs.yaml |
Builds and deploys the site. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+14
to
+16
| concurrency: | ||
| group: pages | ||
| cancel-in-progress: false |
| [sources] | ||
| AlgebraicEpiMech = {path = "../AlgebraicEpiMech"} | ||
| ConfigurableEpi = {path = "../ConfigurableEpi"} | ||
| DocumenterMarkdown = {rev = "master", url = "https://github.com/SamuelBrand1/DocumenterMarkdown.jl"} |
| # Short-form `(@ref)` links to symbols outside the reference cannot be resolved by the site. | ||
| for file in readdir(API_DIR; join = true) | ||
| endswith(file, ".md") || continue | ||
| text = replace(read(file, String), r"\[`([^`]+)`\]\(@ref\)" => s"`\1`") |
| | `docs/api/` | docstrings, selected by `julia-docs/src/*.md` | `julia-docs/make.jl` (Documenter with the [DocumenterMarkdown fork](https://github.com/SamuelBrand1/DocumenterMarkdown.jl)) | | ||
| | `docs/examples/` | Literate scripts in `julia-docs/examples/` | `julia-docs/examples.jl` ([Literate](https://github.com/fredrikekre/Literate.jl), executed) | | ||
|
|
||
| Do not edit the generated files by hand; pre-commit hooks skip them. |
Comment on lines
+123
to
+125
| The net that represents the SIR model is the domain the typed Petri net, which is accessible using `dom`. | ||
| That net defines a vectorfield which is constructed using `vectorfield_flat`. | ||
| This vector field comes with an expectation that input vectors will follow an naming scheme. |
|
|
||
| | Package | What it does | | ||
| | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | [AlgebraicEpiMech](packages/algebraicepimech.md) | Builds compartmental models as typed Petri nets (*nets*) by algebraic compostions: 1) **Algebraic pullback** combines template models, such as SIR and SEIRS, with stratification models, and models of multistrain and immune-history structure. 2) **Algebraic pushout** which combine core composed models with observation delay chains. Any composed net becomes an ODE vector field. | |
| - `OnePopulationTyping()`: every compartment has one population type, so every compartment is stratified the same way. | ||
| - `UninfectedInfectedTyping()`: uninfected and infected compartments have different types and can be stratified differently. | ||
|
|
||
| Competing strains and immune history need the more complex typing structure; a rule of thumb could be that if you were writing the dynamics of the epidemilogical model mathematically and different *variables_ need different _indices_ then in this representation they need different species types. |
Comment on lines
+164
to
+165
| - `AtEvent(:transition)` records a transition's flow instead. This is an **incidence**-type signals such as | ||
| emergency-department arrivals. |
Tightens the docs pipeline by isolating build/deploy concurrency for Pages, pinning DocumenterMarkdown to a known revision, and post-processing generated API Markdown so escaped method links render correctly. It also excludes generated docs from pre-commit formatting and refreshes the README, docs guidance, and regenerated API/example pages to match the current generators and documentation workflow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces documentation infrastructure and new example content for the project. The main changes are the addition of a GitHub Actions workflow to build and deploy documentation, the specification of the required Python version, detailed documentation on maintaining and building the docs, and two new example pages illustrating model features.
Documentation infrastructure and instructions:
.github/workflows/docs.yamlto automate building and deploying documentation to GitHub Pages on pushes tomain, and to strictly build docs on every pull request.docs/development/docs.mdwith detailed instructions for maintaining, building, and regenerating documentation, including commands, workflows, and guidelines for adding examples..python-versionfor consistent local and CI builds.New documentation content:
docs/examples/compartmental_models.md, a comprehensive example demonstrating how to build and solve compartmental models usingAlgebraicEpiMech, including SIR, SEIR, multi-stage compartments, and observation delay chains.docs/examples/arrival_process.md, an example showing how to model arrival processes (jump drivers) and learn arrival rates online using particle filtering.Other: