+ - Perform one of the following actions:
+
+ - Hover over the output of a Document and click
Link :octicons-plus-24:{ title="Link" aria-labelledby="link-icon-label" } > **Create model from equations**.
+ - Right-click the workflow graph and select **Modeling** > **Create models from equations**.
-- __Derivatives__
+ If needed, connect the output of a Document to the Create model from equations input.
- ---
+## Choose the equations
- - Derivatives must be written in Leibniz notation (`\frac{d X}{d t}`). Convert any equations using Newton or Lagrange notation.
- - Place first-order derivatives to the left of the equal sign.
+You can create a model from a set of ordinary differential equations by:
-- __Mathematical notations__
+- [Selecting equations from a document in your project](#select-equations-from-a-document).
+- [Uploading and extracting equations from an image](#extract-equations-from-an-image).
+- [Manually entering equations as LaTeX code](#enter-your-own-equations).
- ---
+To ensure the best results, Terarium uses a set of [LaTeX formatting guidelines](#recommended-latex-format) when converting extracted equations. It is recommended that you follow these guidelines for any LaTeX you add or edit as well.
- Avoid using:
+### Select equations from a document
- - `(t)` to denote time.
- - Superscripts and LaTeX superscripts `^`, particularly to denote sub-variables.
- - Parentheses.
- - Capital sigma (Σ) and pi (Π) notations for summation and product.
- - Homoglyphs (characters that look similar but have different meanings).
+To recreate a model from literature, you can select any ordinary differential equations extracted from an input document. Terarium represents each equation as LaTeX.
-- __Subscripts__
+In some cases you may want to change the LaTeX either to correct or and new details. As you edit the LaTeX, the equation is automatically updated.
- ---
+??? list "Select equations from a document"
+
+ 1. In the workflow, make sure the document is connected to the operator input and then click **Edit**.
+ 2. In the Input panel, review and select the equations you want to include in the model.
+
+??? list "Edit equations extracted from a document"
+
+ ???+ note
+
+ When you modify equations extracted from a document, your changes are only saved to the current Create model from equations operator. If you reuse the document in another Create model from equations operator, you need to make the edits again.
+
+ 1. Click an equation to jump to where it's found in the document and reveal the converted LaTeX code.
+ 2. Edit the code as necessary and verify that the updated equation matches your edits.
+ 3. Select the check box next to the equation to include it in the model.
+
+### Extract equations from an image
+
+In some cases, Terarium may not extract all the equations you want from a document. Or you may have equations from other sources that you want to bring into your project. In these cases, you can capture a screenshot of the equations and load them into Terarium for automatic extraction.
+
+??? list "Extract equations from an image"
+
+ 1. Take a screenshot of the equations you want to use or copy a saved image of the equations.
+ 2. Click inside the text box and paste your image. For example, right click and select **Paste** or press ++ctrl+v++.
+ 3. Click :octicons-plus-24:{ aria-hidden="true" } **Add**.
+ 4. Review the new equations. Click to reveal the LaTeX code and edit it if necessary.
+
+### Enter your own equations
+
+In addition to selecting extracted equations, you can also paste or enter LaTeX code from elsewhere.
- Subscripts using LaTeX `_` are permitted, but ensure that all characters in the subscript are enclosed by curly brackets `{...}`.
+??? list "Manually enter equations"
-- __Variable names__
+ 1. Use the text box to add LaTeX equations to enter a new equation and click :octicons-plus-24:{ aria-hidden="true" } **Add**.
+ 2. Repeat step 3 for each equation you want to add.
+ 3. Enter a name for the new model and click **Run**.
+
+??? list "Manually copy an equation from a document"
+
+ If the automatic extraction missed an equation from your document, you can still copy it and add it separately.
+
+ 1. Select the text in the document viewer and then click :octicons-copy-24:{ aria-hidden="true"} **Copy text**.
+ 2. Paste the equation into the Input text box and edit as necessary.
+ 3. Click :octicons-plus-24:{ aria-hidden="true" } **Add**.
+
+### Recommended LaTeX format
+
+The Create model from equations operator works with LaTeX equations. When adding or editing LaTeX equations, use the following guidelines.
+
+
+
+- __Derivatives__
---
- Avoid words or multi-character names for variables. Instead, use camel case to represent multi-word or multi-character names.
+ - Write derivatives in **Leibniz notation**, not Newton or Lagrange notation.
+
+ *Recommended*: `\frac{d X}{d t}`
+ *Not recommended*: `\dot{X}`
+ *Not recommended*: `X^\prime` or `X'`
+
+ - Represent partial derivatives of one-variable functions as **ordinary derivatives**.
+
+ *Recommended*: `\frac{d X}{d t}`
+ *Not recommended*: `\partial_t X`
+ *Not recommended*: `\frac{\partial X}{\partial t}`
-- __ASCII characters__
+ - Place **first-order derivatives** to the left of the equal sign.
+
+- __Mathematical notations__
---
- Avoid using non-ASCII characters when possible.
+ - Avoid the use of:
+ - `(t)` to denote time.
+ - Parentheses.
+ - Capital sigma (`Σ`) and pi (`Π`) notations for summation and product.
+ - Non-ASCII characters.
+ - Homoglyphs (characters that look similar but have different meanings).
+ - To indicate multiplication, use whitespace between variables instead of `\cdot` or `*`.
-- __Symbolic notation for multiplication__
+- __Superscripts and subscripts__
---
- Do not use `\cdot` or `*` to indicate multiplication. Instead, use whitespace between variables.
+ - To denote **indices**, use LaTeX subscripts `_` instead of superscripts and LaTeX superscripts `^`.
+ - Use **LaTeX subscripts** `_` instead of Unicode subscripts. Wrap all characters in the subscript in curly brackets `{...}`.
-- __Symbolic notation for multiplication__
+- __Variable and symbol usage__
---
- Avoid using symbolic notation for constants like `e` and `pi`. Instead, use their actual values (up to 3 decimal places).
+ - For **variables and names**, avoid the use of words or multiple character.
+ - If needed, use camel case (`susceptiblePopulationSize`) to **combine multi-word or multi-character names**.
+ - To represent a **parameter or variable**, use `\varepsilon` instead of `\epsilon`.
+ - Don't separate equations by commas.
+ - Replace **constants** like `e` and `pi` with their actual values (up to 3 decimal places).
-## Create a model from equations extracted from a document
+## Create the model
+
+Once you have selected the equations you want to use, you can create a new model as:
+
+- An output you can connect to other operators in the same workflow.
+- A project resource that you can use in any of your workflows.
+- A downloadable JSON file you can use in external tools.
+
+???+ note
+
+ Before it creates a model, Terarium uses an AI assistant to "clean" the selected equations according to the [LaTeX formatting guidelines](#recommended-latex-format). When the model is ready, the Input panel shows the equations "Edited by AI" that appear in the model.
+
+
+??? list "Create a new model from the selected equations"
+
+ When you run the Create model from equations operator, the newly created model becomes an output you can connect to other operations in the same workflow.
+
+ 1. Click **Run**.
+ 2. If needed, use the Output panel to [enrich the model metadata](review-and-enrich-model-metadata.md) and then click **Save**.
-???+ list "To extract model equations from a document"
+??? list "Save the new model as a resource for use in other workflows"
- 1. Add the Document to a workflow graph.
- 3. Hover over the output of the Document resource and click :octicons-plus-24:{ title="Link" aria-label="Link" } > **Create model from equations**.
- 4. Click **Edit** on the Create model from equations operator.
- 5. To customize the extracted equations:
- - Edit the LaTeX expressions.
- - Clear a checkbox to remove an equation.
- - Use the text box to add LaTeX equations to enter a new equation and click **Add**.
- 6. Choose the **framework** for the new model.
- 7. Click **Run**.
- 8. Review the model preview and click **Save as new model**.
+ By default, your new model only appears as an output of the Create new model. You can enable it for use in other workflows by saving it as a project resource.
-## Create a model by uploading or entering equations
+ - In the Output panel, click **Save for re-use** and choose a name for the new model.
-???+ list "To create a model from manually entered equations"
+??? list "Download the new model"
- 1. Right-click anywhere on the workflow graph and select **Modeling** > **Create model from equations**.
- 2. Click **Edit** on the Create model from equations operator.
- 3. Use the text box to add LaTeX equations to enter a new equation and click **Add**.
- 5. Repeat step 3 for each equation you want to add.
- 6. Enter a name for the new model and click **Run**.
\ No newline at end of file
+ - Next to the model name, click :fontawesome-solid-ellipsis-vertical:{ title="Menu" aria-labelledBy="Menu" } > :octicons-download-24:{ aria-hidden="true"} **Download**.
\ No newline at end of file
diff --git a/docs/modeling/enrich-descriptions.md b/docs/modeling/enrich-descriptions.md
deleted file mode 100644
index 8525841..0000000
--- a/docs/modeling/enrich-descriptions.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: "Enrich model metadata"
----
-
-# Enrich model metadata
-
-Terarium uses an enrichment service to automatically populate model metadata based on related publications in your project. When you enrich a model, the service looks at your related publications to find and apply definitions for concepts in the model.
-
-???+ list "To enrich a model description"
-
- 1. In the Resources panel, click the model open it.
- 2. Click **Enrich metadata**.
- 3. Select the resource you want to use or select **Generate information without context** and click **Enrich**.
\ No newline at end of file
diff --git a/docs/modeling/index.md b/docs/modeling/index.md
index 5325c7d..6a6e557 100644
--- a/docs/modeling/index.md
+++ b/docs/modeling/index.md
@@ -1,16 +1,30 @@
---
-title: "Work with a model"
+title: "Working with a model"
---
-# Work with a model
+# Working with a model
-In Terarium, a model is an abstract representation that approximates the behavior of a system. You can build a chain of complex operations to edit, configure, stratify, calibrate, and simulate models.
+A model is an abstract representation that approximates the behavior of a system. In Terarium, you can build a chain of complex operations to recreate, edit, configure, stratify, calibrate, and simulate models.
-
+
+
+!!! note
+
+ For information about:
+
+ - Uploading models, see [Upload modeling resources](../upload-resources/index.md).
+ - Creating models, see [Edit model](edit-model.md).
## Model resource
-A model resource represents a model you've uploaded or created in Terarium. In the workflow graph, you can display its diagram or equations. It takes no inputs and outputs the model for use in modeling, configuration, and intervention operators.
+A model resource represents a model you've uploaded to or created in Terarium.
+
+In a workflow graph, a model resource shows its underlying diagram or equations. You can use the resource to:
+
+- Open, review, and enrich the model variables, parameters, observables, and transitions.
+- Edit or stratify the model.
+- Compare it to other models.
+- Create model configurations or intervention policies.
@@ -20,86 +34,39 @@ A model resource represents a model you've uploaded or created in Terarium. In t
---
- None
+ - None
- :material-arrow-expand-right:{ .lg .middle aria-hidden="true" } __Outputs__
---
- Model
+ - Model
-You can create, copy, and edit models for use in your workflows.
+- __Modeling__
-??? list "To create a new model"
+ ---
- 1. In the Resources panel, click :octicons-plus-24:{ aria-hidden="true" } **New** in the Model section.
- 2. Enter a unique name for the model and click **Save**.
- 3. From the Resources panel, drag the new model into a workflow.
- 4. Hover over the Model output and click :octicons-plus-24:{ title="Link" aria-label="Link" } > **Edit model**.
- 5. Click **Edit** on the Edit model operator.
- 6. Use the AI assistant or code editor to construct a set of equations that describe the model.
+ - [Edit model](edit-model.md): Add, remove, or change state variables, transitions, parameters, rate laws, and observables.
+ - [Stratify model](stratify-model.md): Divide populations into subsets along demographic characteristics such as age and location.
+ - [Compare models](compare-models.md): Compare side-by-side with other models to understand their similarities and differences.
-??? list "To rename a model"
+- __Configuration and intervention__
- * Click :fontawesome-solid-ellipsis-vertical:{ title="Menu" } > :octicons-pencil-24:{ aria-hidden="true"} **Rename**, type a unique name for the model, and press ++enter++.
+ ---
-??? list "To copy a model"
+ - [Configure model](../config-and-intervention/configure-model.md): Set the initial values and parameters for the condition you want to test
+ - [Create intervention policy](../config-and-intervention/create-intervention-policy.md): Create static and dynamic interventions for "what-if" scenarios.
- 1. Add the Model operator to a workflow graph and connect it to an Edit model operator.
- 2. Click **Edit** on the Edit model operator.
- 3. Click **Save for re-use**, enter a name for the copy, and click **Save**.
+
\ No newline at end of file
diff --git a/docs/modeling/review-and-enrich-model.md b/docs/modeling/review-and-enrich-model.md
new file mode 100644
index 0000000..ac8c630
--- /dev/null
+++ b/docs/modeling/review-and-enrich-model.md
@@ -0,0 +1,75 @@
+---
+title: "Review and enrich a model"
+---
+
+# Review and enrich a model
+
+Once you have uploaded or created a model in your project, you can open it to:
+
+- Explore its diagram, equations, state variables, parameters, observables, and transitions.
+- Manually add metadata that explains the model components.
+- Automatically enrich metadata using documents in your dataset or without additional context.
+
+## Review a model
+
+To get an understanding of a model, you can open a detailed view that summarizes the following extracted details:
+
+- Description
+- Diagram
+- Model equations
+- State variables
+- Parameters
+- Observables
+- Transitions
+- Time
+
+
+
+??? list "Open a model"
+
+ - Click the model name in the Resources panel.
+
+??? list "Download a model"
+
+ - Next to the model name, click :fontawesome-solid-ellipsis-vertical:{ title="Menu" aria-labelledBy="Menu" } > :octicons-download-24:{ aria-hidden="true"} **Download**.
+
+??? list "Rename a model"
+
+ * Click :fontawesome-solid-ellipsis-vertical:{ title="Menu" aria-labelledBy="Menu" } > :octicons-pencil-24:{ aria-hidden="true"} **Rename**, type a unique name for the model, and press ++enter++.
+
+
+# Enrich model metadata
+
+If your model lacks descriptive details about its variables and parameters, you can use Terarium's model enrichment capability to complete the:
+
+- **Names**: A meaningful label that describes what the variable or parameter stands for.
+- **Units**: What the variable or parameter measures (people, cases).
+
+ ???+ note
+
+ Transitions don't have units.
+
+- **Descriptions**: A short plain language explanation of the variable or parameter's contents.
+- **Concepts**: Epidemiological concepts related to the variable or parameter. Useful for comparing models and mapping variables and parameters to data columns.
+
+Terarium's enrichment service uses an AI language model to automatically populate model metadata based on either:
+
+- Contextual clues in the contents of a document in your project.
+- The variable or parameter names in the model. In this case, the language model attempts to define the metadata as if they relate to a general epidemiological context.
+
+??? list "Enrich model metadata"
+
+ 1. Click **Enrich metadata**.
+ 2. Perform one of the following actions:
+
+ - To enrich metadata without selecting a document, click **Generate information without context**.
+ - To use a document, select the document title.
+
+ 3. Click **Enrich**.
+ 4. Review the updated metadata.
+ 5. Click **Save**.
+
+??? list "Add or edit model metadata"
+
+ 1. Edit the **Name**, **Unit**, **Description**, or **Concept**.
+ 2. Click **Save**.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index e12876e..91f828e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -94,8 +94,8 @@ nav:
- Transform dataset: datasets/transform-dataset.md
- Modeling:
- modeling/index.md
+ - Review and enrich a model: modeling/review-and-enrich-model.md
- Create a model from equations: modeling/create-model-from-equations.md
- - Enrich model metadata: modeling/enrich-descriptions.md
- Edit a model: modeling/edit-model.md
- Stratify a model: modeling/stratify-model.md
- Compare models: modeling/compare-models.md