Merge pull request #48 from DARPA-ASKEM/misc-updates

Misc updates

docs/config-and-intervention/configure-model.md

@@ -135,6 +135,11 @@ When you edit or create a model configuration, you can set a start date for its
     You can edit the initial values of model state variables either as numeric values or as expressions involving other states or parameters. Initials written as expressions must follow [SymPy](https://docs.sympy.org/latest/tutorials/intro-tutorial/basic_operations.html) :octicons-link-external-24:{ alt="External link" title="External link" } syntax.
 
     1. If your state variable is stratified, click <span class="sr-only" id="expand-icon-label">Expand</span> :fontawesome-solid-greater-than:{ title="Expand" aria-labelledby="expand-icon-label" } to show the stratified states.
+
+        ???+ tip
+
+            To set all the stratified variables at once, copy a range of values from a spreadsheet, click **Open matrix**, and then click **Paste**.
+
     2. Do one of the following actions:
 
         - Enter a numeric value or a [SymPy](https://docs.sympy.org/latest/tutorials/intro-tutorial/basic_operations.html) :octicons-link-external-24:{ alt="External link" title="External link" } expression in the **Expression** field.
@@ -145,6 +150,11 @@ When you edit or create a model configuration, you can set a start date for its
 ??? list "Edit the value of a parameter"
 
     1. If your parameter is stratified, click <span class="sr-only" id="expand-icon-label">Expand</span> :fontawesome-solid-greater-than:{ title="Expand" aria-labelledby="expand-icon-label" } to show the stratified parameters.
+
+        ???+ tip
+
+            To set all the stratified parameters at once, copy a range of values from a spreadsheet, click **Open matrix**, and then click **Paste**.
+
     2. Choose the type of value to enter:
 
         - To enter a single unchanging value, select **Constant** and enter the value.

docs/config-and-intervention/create-intervention-policy.md

@@ -24,6 +24,7 @@ Once you've created the intervention policy, the thumbnail preview shows brief d
 
     - Model
     - Document (optional)
+    - Dataset (optional)
 
 -   :material-arrow-expand-right:{ .lg .middle aria-hidden="true" } __Outputs__
 
@@ -44,21 +45,21 @@ Once you've created the intervention policy, the thumbnail preview shows brief d
 
 Use the Create intervention policy operator to: 
 
-- [Extract an intervention policy from a document](#extract-an-intervention-policy-from-a-document).
+- [Extract an intervention policy from a project resource](#extract-an-intervention-policy-from-a-project-resource).
 - [Select from previously saved interventions](#choose-an-existing-intervention).
 - [Manually edit or create an intervention](#edit-or-create-an-intervention).
 
 ??? list "Open the Create intervention policy operator"
 
     - Make sure you've connected a model to the Create intervention policy operator and then click **Open**.
 
-### Extract an intervention policy from a document
+### Extract an intervention policy from a project resource
 
-You can automatically attempt to extract intervention policies from any attached documents.
+You can automatically attempt to extract intervention policies from any attached documents or datasets.
 
 ![](../img/config-and-intervention/intervention/extract.png)
 
-??? list "Extract an intervention policy from a document"
+??? list "Extract an intervention policy from a document or dataset"
 
     1. Click **Extract from inputs**.
     2. Review and edit any of the extracted intervention policy settings as needed.
@@ -95,8 +96,9 @@ You can create:
 
 ??? list "Add a new intervention"
 
-    1. Click :octicons-plus-24:{ aria-hidden="true" } **Add intervention**.
-    2. Click <span class="sr-only" id="edit-icon-label">Edit</span> :octicons-pencil-24:{ title="Edit" aria-labelledby="edit-icon-label"}, enter a unique name, and then click <span class="sr-only" id="apply-icon-label">Apply</span> :octicons-check-24:{ title="Apply" aria-hidden="true" aria-labelledby="apply-icon-label"}.
+    1. Click :octicons-plus-24:{ aria-hidden="true" } **Create new**.
+    2. Click :octicons-plus-24:{ aria-hidden="true" } **Add intervention**.
+    3. Click <span class="sr-only" id="edit-icon-label">Edit</span> :octicons-pencil-24:{ title="Edit" aria-labelledby="edit-icon-label"}, enter a unique name, and then click <span class="sr-only" id="apply-icon-label">Apply</span> :octicons-check-24:{ title="Apply" aria-hidden="true" aria-labelledby="apply-icon-label"}.
 
 ??? list "Set up a static intervention"
 

docs/config-and-intervention/simulate-intervention-policy.md

@@ -6,6 +6,8 @@ title: Simulate an intervention policy
 
 You can simulate an intervention policy to assess the impact of your intervention on a variable of interest. For example, you can see how increasing vaccination rate affects hospitalizations.
 
+<iframe class="video" src="https://drive.google.com/file/d/169Nkc2h6ArjYkhsm0D-Se7JENrzzfI7Q/preview" width="640" height="360"></iframe>
+
 ## Build an intervention policy simulation workflow
 
 You can build a workflow to simulate an intervention policy manually. 

docs/config-and-intervention/validate-model-configuration.md

@@ -202,25 +202,29 @@ The validated configuration is displayed as a series of plots showing the satisf
 
     - Click **Only show furthest results**.
 
-### States time-series
+### States variables and observables
 
-State variable plots provide a time-series view of how model variables evolve over time. They offer a visual representation of how well the model satisfies constraints and checks under different parameter combinations. There is one trajectory per sampled point in the parameter space:
+State variable and observables plots provide a time-series view of how model variables evolve over time. They offer a visual representation of how well the model satisfies constraints and checks under different parameter combinations. There is one trajectory per sampled point in the parameter space:
 
 - Dark green lines satisfy all model checks.
 - Yellow lines do not satisfy all model checks.
 - Light green lines are ambiguous.
 - Light blue boxes show the constraints you set up.
 
-![](../img/config-and-intervention/validate/state-variables.png)
+<div class="grid cards" markdown>
+
+- ![](../img/config-and-intervention/validate/state-variables.png)
+- ![](../img/config-and-intervention/validate/observables.png)
 
+</div>
 
-??? list "Show or hide state variable plots"
+??? list "Show or hide state variable or observable plots"
 
     1. Click <span class="sr-only" id="expand-icon-label">Expand</span> :fontawesome-solid-angles-left:{ title="Expand" aria-labelledby="expand-icon-label" } to expand the Output settings.
     2. Do one of the following actions:
 
-         - Use the dropdown to search, select, or clear different state variables.
-         - Click **X** to remove a state variable plot.
+         - Use the dropdown to search, select, or clear different variables.
+         - Click **X** to remove a variable plot.
 
 ??? list "Focus on model checks"
 

docs/datasets/compare-datasets.md

@@ -83,6 +83,67 @@ You can tailor the resulting comparison plots to highlight the most relevant asp
         - **Default** (mean)
         - **Quantiles** (specify upper and lower bounds). 
 
+### Annotate charts
+
+Adding annotations to charts helps highlight key insights and guide interpretation of data. You can create annotations manually or using AI assistance.
+
+??? list "Add annotations that call out key values and timesteps"
+
+    To highlight notable findings, you can manually add annotations that label plotted values at key timesteps.
+
+    1. Click anywhere on the chart to add a callout.
+    2. To add more callouts without clearing the first one, hold down ++shift++ and click a new area of the chart.
+
+??? list "Prompt an AI assistant to add chart annotations"
+
+    You can prompt an AI assistant to automatically create annotations on the variables over time and comparison charts. Annotations are labelled or unlabelled lines that mark specific timestamps or peak values. Examples of AI-assisted annotations are listed below.
+
+    1. Click <span class="sr-only" id="options-icon-label">Options</span> :octicons-gear-24:{ title="Options" aria-labelledby="options-icon-label" }.
+    2. Describe the annotations you want to add and press ++enter++.
+
+        ```{ .text .wrap }
+        Draw a vertical line at day 100
+        ```
+        ```{ .text .wrap }
+        Draw a line at the peak S after calibration
+        ```
+        ```{ .text .wrap }
+        Draw a horizontal line at the peak of default configuration Susceptible after calibration. Label it as "important"
+        ```
+        ```{ .text .wrap }
+        Draw a vertical line at x is 10. Don't add the label
+        ```
+        ```{ .text .wrap }
+        Draw a line at x = 40 only for ensemble after calibration
+
+#### Display options
+
+You can customize the appearance of your charts to enhance readability and organization of the results.
+
+??? list "Access additional chart settings"
+
+    To access additional options for each chart: 
+
+    - Click <span class="sr-only" id="options-icon-label">Options</span> :octicons-gear-24:{ title="Options" aria-labelledby="options-icon-label" }.
+
+??? list "Change the chart scale"
+
+    By default, charts are shown in linear scale. You can switch to log scale to view large ranges, exponential trends, and improve visibility of small variations.
+
+    - Select or clear **Use log scale**.
+
+??? list "Hide in node"
+
+    The variables you choose to plot appear in the results panel and as thumbnails on the Compare datasets operator in the workflow. You can hide the thumbnail preview to minimize the space the Compare datasets node takes up.
+
+    - Select **Hide in node**.
+
+??? list "Change parameter colors"
+
+    You can change the color of any variable to make your charts easier to read.
+
+    - Click the color picker and choose a new color from the palette or use the eye dropper to select a color shown on your screen.
+
 ## Rank interventions
 
 More info coming soon.

docs/datasets/index.md

@@ -13,6 +13,8 @@ You can use uploaded datasets or simulation results to [configure](../config-and
 
 The Transform data operator can also serve as a place to visually plot and compare multiple datasets or simulation results.
 
+<iframe class="video" src="https://drive.google.com/file/d/12uk_RpRaVlMygP2B8qHZ1LOv_CEK53Zv/preview" width="640" height="360"></iframe>
+
 !!! note
 
     For information about uploading datasets, see [Gather modeling resources](../gather-resources/index.md).

docs/get-started/video.md

@@ -0,0 +1,47 @@
+---
+title: Instructional videos
+---
+
+# Instructional videos
+
+The following videos show how to use Terarium to, for example:
+
+- Create models.
+- Edit models.
+- Work with data.
+- Run what-if scenarios.
+- Calibrate models.
+- Create, simulate, and optimize intervention policies.
+- Stratify models.
+
+## Introduction
+
+<iframe class="video" src="https://drive.google.com/file/d/1DrbkI_6b8MBjJtUrz3SPVopUK7F4T_c9/preview" width="640" height="360"></iframe>
+
+## Working with data
+
+<iframe class="video" src="https://drive.google.com/file/d/12uk_RpRaVlMygP2B8qHZ1LOv_CEK53Zv/preview" width="640" height="360"></iframe>
+
+## Creating a model from equations
+
+<iframe class="video" src="https://drive.google.com/file/d/15y1c4esX-xjnLfAmP2igzkifzSpWuIm8/preview" width="640" height="360"></iframe>
+
+## Editing a model
+
+<iframe class="video" src="https://drive.google.com/file/d/1k2T9cpCCPpGdgnhMx_DRrE1jpdoruM1o/preview" width="640" height="360"></iframe>
+
+## Calibration
+
+<iframe class="video" src="https://drive.google.com/file/d/1by_OGfVBbx2ExmdAMR8lKYFym000-B1x/preview" width="640" height="360"></iframe>
+
+## Simulating intervention policies
+
+<iframe class="video" src="https://drive.google.com/file/d/169Nkc2h6ArjYkhsm0D-Se7JENrzzfI7Q/preview" width="640" height="360"></iframe>
+
+## Optimizing intervention policies
+
+<iframe class="video" src="https://drive.google.com/file/d/1FlovnXRv9NUIRSuW1J7Xc3Ci53pwpydv/preview" width="640" height="360"></iframe>
+
+## Stratification
+
+<iframe class="video" src="https://drive.google.com/file/d/1S8_4vD5ZSEv--WGPiOlFEfJMD9bZ4ZHt/preview" width="640" height="360"></iframe>

docs/index.md

@@ -9,6 +9,7 @@ Terarium is a modeling and simulation workbench designed to help you assess and
 <div class="gridcards" markdown>
 [Using Terarium](get-started/using-terarium.md){ .md-button }
 [Get started](get-started/example-workflow.md){ .md-button }
+[Instructional videos](get-started/video.md){ .md-button }
 </div>
 
 Regardless of your level of programming experience, Terarium allows you to:
@@ -20,7 +21,7 @@ Regardless of your level of programming experience, Terarium allows you to:
 - :fontawesome-solid-chart-line:{ .lg .middle } **Analyze the results**
 </div>
 
-![The Terarium home screen with a list of projects and related papers](img/terarium-home.jpg)
+<iframe class="video" src="https://drive.google.com/file/d/1DrbkI_6b8MBjJtUrz3SPVopUK7F4T_c9/preview" width="640" height="360"></iframe>
 
 Need more help? Check out these topics:
 

docs/modeling/create-model-from-equations.md

@@ -9,7 +9,7 @@ The Create model from equations operator helps you to recreate a model from lite
 1. [Choose or enter the equations](#choose-the-equations) you want to include in the model.
 2. [Create the model](#create-the-model) as an output or resource for use in other modeling and configuration processes. 
 
-![SIR model created from equations extracted from a COVID-19 research paper](../img/models/model-create-from-equations.png)
+<iframe class="video" src="https://drive.google.com/file/d/15y1c4esX-xjnLfAmP2igzkifzSpWuIm8/preview" width="640" height="360"></iframe>
 
 !!! note
 
@@ -59,6 +59,8 @@ You can create a model from a set of ordinary differential equations by:
 - [Uploading and extracting equations from an image](#extract-equations-from-an-image). 
 - [Manually entering equations as LaTeX code](#enter-your-own-equations).
 
+![SIR model created from equations extracted from a COVID-19 research paper](../img/models/model-create-from-equations.png)
+
 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.  
 
 ### Select equations from a document
@@ -149,23 +151,18 @@ The Create model from equations operator works with LaTeX equations. Before it c
 
     - Rewrite expressions with negative exponents as explicit fractions.
 
-        *Recommended*: `"\\frac{{1}}{{N}}`
+        *Recommended*: `"\frac{{1}}{{N}}`
         *Not recommended*: `N^{{-1}}`
 
 -   #### Parentheses
 
     ---
 
     - When grouping algebraic expressions, don't use square brackets `[ ]`, curly braces `{ }`, or angle brackets `< >`. Use parentheses `( )` if needed.
-    - Expand time-dependent algebraic expressions grouped by parentheses according to the distributivity property of multiplication. 
+    - Always expand expressions surrounded by parentheses using the order of mathematical operations. 
 
-        *Recommended*: `a * S(t) * I(t) + b * S(t) * D(t) + c * A(t) * S(t)`
-        *Not recommended*: `S(t) * (a * I(t) + b * D(t) + c * A(t))`
-
-    - Don't expand constant algebraic expressions grouped by parentheses. 
-
-        *Recommended*: `a * b * (1 - c)`
-        *Not recommended*: `a ∗ b ∗ 1 − a ∗ b ∗c`
+        *Recommended*: `\alpha * x(t) * y(t) + \beta * x(t) * z(t)`
+        *Not recommended*: `x(t) (\alpha y(t) + \beta z(t))`
 
 -   #### Variable and symbol usage
 

docs/modeling/edit-model.md

@@ -14,6 +14,8 @@ Model editing lets you build on existing models. Supported edits include:
 
 The Edit model operator is a code notebook with an interactive AI assistant. You describe in plain language the changes you want to make, and the large language model (LLM)-powered assistant automatically generates the code for you.
 
+<iframe class="video" src="https://drive.google.com/file/d/1k2T9cpCCPpGdgnhMx_DRrE1jpdoruM1o/preview" width="640" height="360"></iframe>
+
 !!! note
 
     The Edit model operator adapts to your coding experience. You can: 

docs/modeling/review-and-enrich-model.md

@@ -52,6 +52,10 @@ If your model lacks descriptive details about its variables and parameters, you
 - **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.
 
+???+ note
+
+    Enrichment can also provide geolocation information if, for example, your model is stratified by geographic areas such as states or territories.
+
 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.

docs/modeling/stratify-model.md

@@ -6,6 +6,8 @@ title: "Stratify a model"
 
 You can make a simple model more complex by stratifying its state variables and parameters. Stratification builds many different versions of a model and its parameters—by location, demographics, or other contextual data—into one large model. You can then configure, calibrate, or simulate the combined models all at once.
 
+<iframe class="video" src="https://drive.google.com/file/d/1S8_4vD5ZSEv--WGPiOlFEfJMD9bZ4ZHt/preview" width="640" height="360"></iframe>
+
 ## Stratify model operator
 
 In a workflow, the Stratify model operator takes a model as an input and outputs a stratified version of the model.