Merge pull request #17 from DARPA-ASKEM/phase-1-eval

Additional edits for phase 1 eval updates

docs/datasets/index.md

@@ -56,15 +56,22 @@ Terarium relies on large language models (LLMs) to make sense of datasets and en
 
 Terarium also has an enrichment service that can automatically populate dataset descriptions based on related publications you've identified. When you enrich a dataset, the service looks at your related publications to find and apply definitions for concepts.
 
+???+ tip
+
+    Curating concepts improves structural comparison and alignment of models and data.
+
 <p class="procedure">To enrich a dataset description</p>
 
 1. Open the dataset in a new tab.
-1. Click **Enrich description**.
-2. Select a publication and click **Use document to generate descriptions**. 
+2. Click **Enrich description**.
+3. Perform one of the following actions:
+
+    - To enrich descriptions without selecting a document, click **Generate descriptions**.
+    - To use a document, select a publication and click **Use document to generate descriptions**. 
 
 ## Transform a dataset
 
-Terarium has an operator with a large language model interface, TGPT, to help you transform data to suit your modeling and simulation processes. With TGPT, you can use plain language to explain the changes you want to make and save the transformed data as a new resource within your project. 
+Terarium has an operator with a large language model interface, TGPT, to help you clean and transform data to suit your modeling and simulation processes. With TGPT, you can use plain language to explain the changes you want to make and save the transformed data as a new resource within your project. 
 
 <figure markdown>![Transform dataset that takes a UK compartments dataset as an input and outputs a filtered version](../img/data/transform-operator.png)<figcaption markdown>How it works: [pandas](https://pandas.pydata.org/docs/user_guide/index.html#user-guide) :octicons-link-external-24:{ alt="External link" title="External link" }</figcaption></figure>
 

docs/datasets/subset-dataset.md

@@ -2,6 +2,44 @@
 title: Subset dataset
 ---
 
-More info coming soon.
+# Subset dataset
 
-How it works: [climate-data](https://github.com/DARPA-ASKEM/climate-data/blob/main/api/processing/filters.py#L48) :octicons-link-external-24:{ alt="External link" title="External link" }
+The Subset dataset operator allows you to generate a subset of an Earth System Grid Federation (ESGF) dataset. You can generate subsets by specifying geo-boundaries or temporal slices.
+
+<figure markdown>![](../img/data/dataset-subset-operator.png)<figcaption markdown>How it works: [climate-data](https://github.com/DARPA-ASKEM/climate-data/blob/main/api/processing/filters.py#L48) :octicons-link-external-24:{ alt="External link" title="External link" }</figcaption></figure>
+
+<div class="grid cards" markdown>
+
+-   :material-arrow-collapse-right:{ .lg .middle aria-hidden="true" } __Inputs__
+
+    ---
+
+    Dataset
+
+-   :material-arrow-expand-right:{ .lg .middle aria-hidden="true" } __Outputs__
+
+    ---
+
+    Dataset subset
+
+</div>
+
+<p class="procedure">To generate a subset of an ESGF dataset</p>
+
+1. From the Resources panel, drag the Dataset resource into the workflow graph.
+
+    ???+ note "To find ESGF datasets"
+
+        On the Datasets tab of the :fontawesome-regular-compass:{ aria-hidden="true" } [Explorer](../modeling-resources/index.md#find-papers-models-and-datasets), change the **Source** to ESGF.
+
+2. Right-click anywhere on the workflow graph and select **Work with dataset** > **Transform dataset**.
+3. Connect the output of the Dataset resource to the input of the Subset dataset operator.
+4. Click **Open**.
+5. Choose the subset of data you want to include:
+    - **Geo-boundaries**: Specify a pair of **Latitude** and **Longitude** coordinates that define a bounding box around an area of interest. 
+    - **Temporal slide**: Specify the earliest (**From**) and latest (**To**) dates to include.
+6. To sample the data from the subset: 
+    1. Select **Spatial** or **Time Skipping**. 
+    2. Enter the number of datapoints or time slices you want to include. For example, enter *5* to keep every fifth entry.
+6. Click :material-play-outline:{ aria-hidden="true" } **Run**.
+7. Click **Save as new dataset** to add the subset to your project resources.  

docs/datasets/transform-gridded-dataset.md

@@ -2,6 +2,8 @@
 title: Transform gridded dataset
 ---
 
+# Transform gridded dataset
+
 More info coming soon.
 
 How it works: [climate_data_utility](https://github.com/DARPA-ASKEM/climate-data/blob/main/api/processing/filters.py#L48) :octicons-link-external-24:{ alt="External link" title="External link" }

docs/models/calibrate-model.md

@@ -37,10 +37,20 @@ Deterministic calibrations (SciML) take a model configuration and a dataset as a
 
 1. Add the model and reference dataset to a workflow graph.
 2. Connect the Model operator output to a Configure model operator. See [Configure a model](configure-model.md) for information on selecting a model configuration. 
-2. Right-click anywhere on the workflow graph and select **Run model** > **Calibrate with SciML**.
-3. Connect the outputs of the Configure model operator and Dataset resource to the inputs on the Calibrate with SciML operator.
-4. Click **Edit** on the Calibrate with SciML operator.
+
+    ??? tip
+
+        At least one parameter in the configuration needs to be defined as a distribution, and there needs to be a timestamp column.
+
+3. Right-click anywhere on the workflow graph and select **Run model** > **Calibrate with SciML**.
+4. Connect the outputs of the Configure model operator and Dataset resource to the inputs on the Calibrate with SciML operator.
+5. Click **Edit** on the Calibrate with SciML operator.
 6. In the Mapping section, map the model variables to the columns in the dataset.
+
+    ??? tip
+
+        If the model concepts are assigned to variables, click :octicons-plus-24:{ aria-hidden="true" } **Auto map** to speed the alignment process. 
+
 7. Configure the calibration options as needed:
     - **Chains**: Number of parallel chains to run during the calibration.
     - **Iterations**: Number of steps each chain should take.

docs/models/configure-model.md

@@ -8,7 +8,7 @@ Before you can simulate a model, you need to configure it to set the initial val
 
 ![Model configurations table showing the initial conditions and parameters for a default configuration](../img/models/configurations.png)
 
-The Configure model operator takes a model as an input and outputs a model configuration. You can manually enter the variable and parameter values for the output configuration or automatically extract them from an optional document or dataset input.
+The Configure model operator takes a model as an input and outputs a model configuration. You can manually enter the variable and parameter values for the output configuration or automatically extract them from an optional document or dataset (such as a contact matrix or initial populations) input.
 
 ![](../img/models/model-configure-operator.png)
 
@@ -30,37 +30,47 @@ The Configure model operator takes a model as an input and outputs a model confi
 
 </div>
 
-<span class="procedure">To add configure a model</span>
+??? list "To configure a model"
 
-1. Add the model to a workflow graph.
-2. (Optional) Add a document or dataset from which you want to extract configuration values.
-2. Right-click anywhere on the workflow graph and select **Work with model** > **Configure model**.
-3. Connect the Model, Document, and Dataset operator outputs to the corresponding inputs on the Configure model operator. 
-4. On the Configure model operator, click **Open**.
-5. Choose or edit the model configuration:
-
-    === "Choose an existing model configuration"
+    1. Add the model to a workflow graph.
+    2. (Optional) Add a document or dataset from which you want to extract configuration values.
+    2. Right-click anywhere on the workflow graph and select **Work with model** > **Configure model**.
+    3. Connect the Model, Document, and Dataset operator outputs to the corresponding inputs on the Configure model operator. 
+    4. On the Configure model operator, click **Open**.
+    5. Choose or edit the model configuration:
+
+        === "Edit or create a model configuration"
+        
+            1. In the Context section, enter a name for the new configuration.
+            2. Scroll down to the Initial variable values and Parameters sections.
+            3. Edit any of the variable or parameter values and, if needed, describe the source that informed your changes.
+                + To change the type, use the dropdown list to select one of the following options: 
+                    - **Constant**: Enter a single value and (optionally) increase/decrease it by a certain percent.
+                    - **Distribution**: Enter a minimum and maximum value.
+                    - **Time varying**: Enter a comma-separated list of values at different time steps in the format *timestep:value* (e.g., *0:25, 1:26, 2:27*).
+                + To edit matrix values, click :fontawesome-solid-table-cells-large:{ aria-hidden="true" } **Matrix** or click :fontawesome-solid-greater-than:{ alt="Expand" title="Expand" } at the beginning of the row.    
+            4. Repeat step c for each initial condition or parameter you want to change.
+
+        === "Extract configurations from inputs"
+
+            ???+ tip
 
-        1. Review the Suggested configurations section. Click a configuration name to review its values.
-        2. Click **Apply configuration values** to choose an existing configuration as the output for this operator.
+                Extractions work best when the parameters in the inputs have descriptions and concepts.
 
-    === "Edit or create a model configuration"
+            1. Click :fontawesome-solid-arrow-right-from-bracket:{ aria-hidden="true"} **Extract configurations from inputs** to attempt to extract variable and parameter values from any attached documents or datasets.
+            2. Edit any of the variable or parameter values as needed.
 
-        1. In the Context section, enter a name for the new configuration.
-        2. Scroll down to the Initial variable values and Parameters sections.
-        3. Edit any of the variable or parameter values and, if needed, describe the source that informed your changes.
-            + To change the type, use the dropdown list to select one of the following options: 
-                - **Constant**: Enter a single value and (optionally) increase/decrease it by a certain percent.
-                - **Distribution**: Enter a minimum and maximum value.
-                - **Time varying**: Enter a comma-separated list of values at different time steps in the format *timestep:value* (e.g., *0:25, 1:26, 2:27*).
-            + To edit matrix values, click :fontawesome-solid-table-cells-large:{ aria-hidden="true" } **Matrix** or click :fontawesome-solid-greater-than:{ alt="Expand" title="Expand" } at the beginning of the row.    
-        4. Repeat step c for each initial condition or parameter you want to change.
-
-6. Click :material-play-outline:{ aria-hidden="true" } **Run**.
+        === "Choose an existing model configuration"
+        
+            1. Review the Suggested configurations section. Click a configuration name to review its values.
+            2. Click **Apply configuration values** to choose an existing configuration as the output for this operator.
+
+
+    6. Click :material-play-outline:{ aria-hidden="true" } **Run**.
 
 ## Validate a model configuration
 
-More info coming soon.
+You can use the Validate a model configuration operator to check if a population remains constant and identify non-negativity. You can also add more constraints to check additional conditions.
 
 <figure markdown>
 ![](../img/models/model-configuration-validate-operator.png)
@@ -83,20 +93,32 @@ More info coming soon.
 
 </div>
 
-<span class="procedure">To validate a model configuration</span>
-
-1. [Configure the model](#configure-a-model).
-2. Right-click anywhere on the workflow graph and select **Work with model** > **Validate configuration**.
-3. Connect the Configure model output to the Validate configuration input.
-4. Click **Review checks**.
-5. Edit the validation parameters:
-    - **Start** and **End time** 
-    - **Number of steps**
-    - **Tolerance**
-6. Click **Add another constraint** to specify a new constraint against which to test model configurations. Edit the constraint parameters.
-    - **Name of constant**
-    - **Constraint type**
-    - **Target**
-    - **Start** and **End time**
-    - **Lower** and **Upper bound**:
-7. Click :material-play-outline:{ aria-hidden="true" } **Run**.
+??? list "To validate a model configuration"
+
+    1. [Configure the model](#configure-a-model).
+
+        ??? tip
+
+            The input configuration should include some distribution on the parameters to allow for an exploration of the parameter space.
+
+    2. Right-click anywhere on the workflow graph and select **Work with model** > **Validate configuration**.
+    3. Connect the Configure model output to the Validate configuration input.
+    4. Click **Review checks**.
+    5. Edit the validation parameters:
+
+        - **Start** and **End time** 
+        - **Number of steps**
+        - **Tolerance**: the lower the value, the more potential boxes will be split from each variable's range, introducing more sampling and more dynamics.
+        - **Parameters of interest**: stricter checks are performed on selected parameters.
+
+        ??? tip
+
+            Lowering the tolerance and checking parameters of interest can significantly increase the time it takes to run the Validate configuration operator.
+
+    6. Click **Add another constraint** to specify a new constraint against which to test model configurations. Edit the constraint parameters.
+        - **Name of constant**
+        - **Constraint type**
+        - **Target**
+        - **Start** and **End time**
+        - **Lower** and **Upper bound**:
+    7. Click :material-play-outline:{ aria-hidden="true" } **Run**.