drbergman-lab · drbergman · Jun 13, 2026 · Jun 13, 2026
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "PhysiCellModelManager"
 uuid = "7582d1aa-5e58-4d65-a123-4418a61a2644"
-version = "0.3.0"
+version = "0.3.1"
 authors = ["Daniel Bergman <danielrbergman@gmail.com> and contributors"]
 
 [deps]
@@ -55,12 +55,12 @@ LinearAlgebra = "1.10"
 MAT = "0.11, 0.12"
 MacroTools = "0.5.16"
 MetaGraphsNext = "0.7.2, 0.8"
-ModelManager = "0.7.0"
+ModelManager = "0.7"
 PairCorrelationFunction = "0.0.11"
-Parameters = "0.12"
+Parameters = "0.12, 0.13"
 PhysiCellCellCreator = "0.0.9"
 PhysiCellECMCreator = "0.0.9"
-PhysiCellXMLRules = "0.0.9"
+PhysiCellXMLRules = "0.0.9 - 0.3"
 Pkg = "1.10.0"
 QuasiMonteCarlo = "0.3"
 RecipesBase = "1.3.4"

diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+<p align="center"><img src="docs/src/assets/logo-hero.svg" width="200" alt="PhysiCellModelManager.jl"></p>
+
 # PhysiCellModelManager.jl
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://drbergman-lab.github.io/PhysiCellModelManager.jl/stable/)

diff --git a/docs/make.jl b/docs/make.jl
@@ -11,32 +11,69 @@ makedocs(;
         canonical="https://drbergman-lab.github.io/PhysiCellModelManager.jl",
         edit_link="main",
         assets=String[],
+        collapselevel=1, # collapse all top-level sidebar sections by default; the current page's section auto-expands
     ),
     pages=[
         "Home" => "index.md",
-        "Manual" => Any[
-            "Best practices" => "man/best_practices.md",
-            "Getting started" => "man/getting_started.md",
-            "Varying parameters" => "man/varying_parameters.md",
-            "Querying parameters" => "man/querying_parameters.md",
+        "Getting Started" => Any[
+            "Installation" => "man/installation.md",
+            "Julia environments" => "man/julia_environments.md",
+            "Your first project" => "man/getting_started.md",
+            "Importing a project" => "man/importing_projects.md",
+        ],
+        "Building & Varying Models" => Any[
             "XML path helpers" => "man/xml_path_helpers.md",
+            "Varying parameters" => "man/varying_parameters.md",
             "CoVariations" => "man/covariations.md",
             "LatentVariations" => "man/latent_variations.md",
-            "Data directory" => "man/data_directory.md",
             "Intracellular inputs" => "man/intracellular_inputs.md",
-            "Known limitations" => "man/known_limitations.md",
-            "PhysiCell Studio" => "man/physicell_studio.md",
+        ],
+        "Experiments" => Any[
             "Sensitivity analysis" => "man/sensitivity_analysis.md",
             "Calibration" => "man/calibration.md",
+        ],
+        "Analyzing Results" => Any[
             "Analyzing output" => "man/analyzing_output.md",
-            "Developer guide" => "man/developer_guide.md",
+            "Querying parameters" => "man/querying_parameters.md",
+        ],
+        "Examples" => "man/examples.md",
+        "Tools & Integrations" => Any[
+            "PhysiCell Studio" => "man/physicell_studio.md",
+        ],
+        "Reference" => Any[
+            "Best practices" => "man/best_practices.md",
+            "Data directory" => "man/data_directory.md",
             "Project configuration" => "man/project_configuration.md",
-            "Index" => "man/index.md",
+            "Known limitations" => "man/known_limitations.md",
+        ],
+        "Contributing" => Any[
+            "Developer guide" => "man/developer_guide.md",
+        ],
+        # Index: the exhaustive home for exported docstrings, grouped by code
+        # family (not mirroring the Manual). NOTE: this list is maintained by
+        # hand — when adding a new docs/src/lib/*.md page, add it to a group below.
+        "Index" => Any[
+            "Core" => map(s -> "lib/$(s)", [
+                "PhysiCellModelManager.md", "user_api.md", "globals.md", "utilities.md", "classes.md",
+            ]),
+            "Project & inputs" => map(s -> "lib/$(s)", [
+                "creation.md", "configuration.md", "components.md", "import.md",
+                "variations.md", "ic_cell.md", "ic_ecm.md",
+            ]),
+            "Running simulations" => map(s -> "lib/$(s)", [
+                "runner.md", "physicell_simulator.md", "abstract_simulator.md",
+                "compilation.md", "recorder.md", "hpc.md",
+            ]),
+            "Analysis & output" => map(s -> "lib/$(s)", [
+                "analysis.md", "loader.md", "export.md", "movie.md",
+                "sensitivity.md", "calibration.md",
+            ]),
+            "Management & maintenance" => map(s -> "lib/$(s)", [
+                "database.md", "deletion.md", "pruner.md", "up.md", "deprecate_keywords.md",
+                "pcmm_version.md", "physicell_version.md", "physicell_studio.md",
+            ]),
+            "Alphabetical index" => "man/index.md",
         ],
-        "Documentation" => map(
-            s -> "lib/$(s)",
-            sort(readdir(joinpath(@__DIR__, "src/lib")))
-        ),
         "Miscellaneous" => Any[
             "Database upgrades" => "misc/database_upgrades.md",
         ],

diff --git a/docs/src/assets/logo-hero.svg b/docs/src/assets/logo-hero.svg
diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg
diff --git a/docs/src/assets/retired-logo-pcmm-center.svg b/docs/src/assets/retired-logo-pcmm-center.svg
diff --git a/docs/src/assets/retired-logo-pcmm-top.svg b/docs/src/assets/retired-logo-pcmm-top.svg
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -2,8 +2,31 @@
 CurrentModule = PhysiCellModelManager
 ```
 
+```@raw html
+<p align="center"><img src="assets/logo-hero.svg" width="200" alt="PhysiCellModelManager.jl"></p>
+```
+
 # PhysiCellModelManager.jl
-[PhysiCellModelManager.jl](https://github.com/drbergman-lab/PhysiCellModelManager.jl) (PCMM) is a Julia package that provides a framework for running large [PhysiCell](https://github.com/MathCancer/PhysiCell) simulation campaigns. See [Getting started](@ref) for getting PhysiCellModelManager.jl set up and running.
+
+[PhysiCellModelManager.jl](https://github.com/drbergman-lab/PhysiCellModelManager.jl) (PCMM) is a Julia package for running large [PhysiCell](https://github.com/MathCancer/PhysiCell) simulation campaigns. It manages the inputs, variations, and databases so you can define a parameter sweep, sensitivity analysis, or calibration once and let PCMM organize, deduplicate, and reproduce the runs.
+
+New here? Start with [Installation](@ref), then [Your first project](@ref).
+
+## Where do I look?
+
+| I want to… | Go to |
+| --- | --- |
+| Install the package and run my first simulations | [Installation](@ref), [Your first project](@ref) |
+| Set up a reproducible Julia environment | [Julia environments](@ref) |
+| Bring in an existing PhysiCell project | [Importing a project](@ref) |
+| Change parameter values across runs | [Varying parameters](@ref), [XML path helpers](@ref) |
+| Vary parameters together or under constraints | [CoVariations](@ref), [LatentVariations](@ref) |
+| Run a sensitivity analysis or calibrate to data | [Sensitivity analysis](@ref), [Calibration](@ref calibration_section_man) |
+| Plot or query results | [Analyzing output](@ref), [Querying parameters](@ref) |
+| Copy-paste a recipe | [Examples](@ref examples_cookbook) |
+| Look up a function's signature | the [Index](@ref) (all exported symbols) |
+| Troubleshoot something | [Known limitations](@ref), [Best practices](@ref) |
 
 ## Issues
-Have an issue? First check the [Known limitations](@ref) and [Best practices](@ref) sections. If you still have an issue, please submit it [here](https://github.com/drbergman-lab/PhysiCellModelManager.jl/issues).
+
+Have a problem? First check [Known limitations](@ref) and [Best practices](@ref). If it persists, please open an issue [here](https://github.com/drbergman-lab/PhysiCellModelManager.jl/issues).
diff --git a/docs/src/man/analyzing_output.md b/docs/src/man/analyzing_output.md
@@ -1,27 +1,21 @@
 # Analyzing output
 
 ## Install dependencies
-Julia has several packages for plotting.
-Here, we will use `Plots.jl` which you can install with
+The examples use `Plots.jl`; install it with
 ```julia-repl
 pkg> add Plots
 ```
 
 ## Loading output
 
 ### `PhysiCellSnapshot`
-The base unit of PhysiCell output is the `PhysiCellSnapshot`.
-Each snapshot records the path to the PhysiCell output folder, its index in the sequence of outputs, the time of the snapshot in the simulation, and optionally the cell, substrate, and mesh data at that snapshot.
+The base unit of PhysiCell output is the `PhysiCellSnapshot`. Each records the output-folder path, its index in the output sequence, the simulation time, and optionally the cell, substrate, and mesh data at that snapshot.
 
 ### `PhysiCellSequence`
-A `PhysiCellSequence` is the full sequence of snapshots corresponding to a single PhysiCell simulation.
-In addition to the path to the PhysiCell output folder and the vector of `PhysiCellSnapshot`'s, it holds metadata for the simulation.
+A `PhysiCellSequence` is the full sequence of snapshots for a single simulation, plus the output-folder path and simulation metadata.
 
 ### `cellDataSequence`
-The main function to get sequences of cell data is `cellDataSequence`.
-It accepts any of a simulation ID (`<:Integer`), a simulation (`::Simulation`), or a sequence (`::PhysiCellSequence`) and either a single label (`::String`) or a vector of labels (`::Vector{String}`).
-For each cell in the simulation (as determined by the cell ID), the output creates a dictionary entry (the key is the integer cell ID) whose value is a named tuple with the input labels as keys as well as `:time`.
-This means that if one sets
+`cellDataSequence` returns sequences of cell data. It accepts a simulation ID (`<:Integer`), a `::Simulation`, or a `::PhysiCellSequence`, together with one label (`::String`) or several (`::Vector{String}`). It returns a dictionary keyed by integer cell ID, each value a named tuple with the requested labels plus `:time`. For example, setting
 
 ```julia
 data = cellDataSequence(1, "position")
@@ -44,13 +38,10 @@ Plan your analyses accordingly as loading simulation data is not fast.
 ## Population plots
 
 ### Group by Monad
-Plotting population plots is one the most basic analysis tasks and PhysiCellModelManager.jl makes it super easy!
-If you call `plot` on a `Simulation`, `Monad`, `Sampling`, or the return value of a call to `run` (though not for a sensitivity analysis),
-then a sequence of panels will be generated in a single figure.
-Each panel will correspond to a `Monad` (replicates using the same parameter values) and will plot mean +/- SD for each cell type.
+Population plots are easy: call `plot` on a `Simulation`, `Monad`, `Sampling`, or a `run` result (but not a sensitivity analysis) to generate a figure of panels. Each panel is one `Monad` (replicates with the same parameters) and plots mean ± SD per cell type.
 
-Finer-grained control of the output is possible, too!
-- to include dead cells in your counts: `plot(...; ..., include_dead=true, ...)`
+Finer control is available:
+- include dead cells in counts: `plot(...; ..., include_dead=true, ...)`
 - select a subset of cell types to include: `plot(...; ..., include_cell_type_names="cancer", ...)`
 - select a subset of cell types to exclude: `plot(...; ..., exclude_cell_type_names="cancer", ...)`
 - choose time units for the x-axis: `plot(...; ..., time_unit=:h, ...)`

diff --git a/docs/src/man/best_practices.md b/docs/src/man/best_practices.md
@@ -18,12 +18,12 @@ createProject("MyNewProject"; template_as_default=false)
 ```
 
 ## Be slow to delete simulations and scripts.
-PhysiCellModelManager.jl tracks simulations in a database so that it does not have to re-run simulations that have already been run.
-This means that adding new simulations to a script and re-running the entire script, including on an HPC, will not run extraneous simulations.
-Thus, the script can serve as a record of the simulations that have been run, and can be used to reproduce the results at a later date.
+PhysiCellModelManager.jl tracks simulations in a database and skips re-running ones that already exist — so adding simulations to a script and re-running it (including on an HPC) runs only the new ones. A script thus doubles as a record you can use to reproduce results later.
 
-If you do need to manually delete simulations--for example, because of an error that prevented the simulation entry in the database updating its record--use the [`deleteSimulations`](@ref) function to ensure that the database is updated appropriately.
+If you must delete simulations manually — e.g. after an error left a stale database record — use [`deleteSimulations`](@ref) so the database stays consistent.
+
+## Use a dedicated Julia environment.
+Keep each project's dependencies in its own environment and commit `Project.toml` and `Manifest.toml`. See [Julia environments](@ref).
 
 ## Use version control on `inputs` and `scripts` directories.
-Alone, these two directories along with the version of PhysiCell can be used to reproduce the results of a project.
-The `createProject` function will create a `.gitignore` file in the data directory to make sure the appropriate files are tracked.
+These two directories plus the PhysiCell version are enough to reproduce a project. `createProject` adds a `.gitignore` in the data directory so the right files are tracked.
diff --git a/docs/src/man/calibration.md b/docs/src/man/calibration.md
@@ -168,12 +168,11 @@ end
 problem = CalibrationProblem(inputs, params, observed, my_stat, mseDistance)
 ```
 
-The distance function is called as `distance(simulated, observed_data) → Float64`, where `simulated` is the direct return value of `summary_statistic` and `observed_data` is whatever you passed into `CalibrationProblem`. Both can be any type — your distance function just needs to handle them. `mseDistance` accepts dicts, vectors, and scalars; when using it with dicts, the keys of `observed_data` must be a subset of the keys returned by `summary_statistic`.
+When using `mseDistance` with dicts, the keys of `observed_data` must be a subset of the keys returned by `summary_statistic`.
 
 ### Distance functions
 
-A distance function is any `(simulated, observed) → Float64` — the types of both arguments are whatever your `summary_statistic` returns and whatever you set `observed_data` to.
-[`mseDistance`](@ref) is the built-in option and handles dicts, vectors, and scalars. A custom function can work with any types:
+A distance function is any `(simulated, observed) → Float64`, where the argument types are whatever your `summary_statistic` returns and whatever you set `observed_data` to. [`mseDistance`](@ref) is the built-in option (dicts, vectors, scalars); a custom function can use any types:
 
 ```julia
 # Dict-based: weighted MSE on two cell populations