Add data API tutorial

docs/explanation/customizing_checks.md

@@ -16,14 +16,40 @@ STRIDE supports the following dataset validation checks:
 
 The simplest way to customize checks is through environment variables:
 
-```bash
-# Disable time consistency checks (faster project creation)
-export STRIDE_CHECK_TIME_CONSISTENCY=false
-stride project create my_config.json5
+```{eval-rst}
+
+    .. tabs::
+
+      .. code-tab:: bash Mac/Linux
+
+         # Disable time consistency checks (faster project creation)
+         export STRIDE_CHECK_TIME_CONSISTENCY=false
+         stride project create my_config.json5
+
+         # Enable dimension association checks (more thorough validation)
+         export STRIDE_CHECK_DIMENSION_ASSOCIATIONS=true
+         stride project create my_config.json5
+
+      .. code-tab:: bash Windows Command Prompt
+
+         # Disable time consistency checks (faster project creation)
+         set STRIDE_CHECK_TIME_CONSISTENCY=false
+         stride project create my_config.json5
+
+         # Enable dimension association checks (more thorough validation)
+         set STRIDE_CHECK_DIMENSION_ASSOCIATIONS=true
+         stride project create my_config.json5
+
+      .. code-tab:: powershell Windows PowerShell
+
+         # Disable time consistency checks (faster project creation)
+         $Env:STRIDE_CHECK_TIME_CONSISTENCY = "false"
+         stride project create my_config.json5
+
+         # Enable dimension association checks (more thorough validation)
+         $Env:STRIDE_CHECK_DIMENSION_ASSOCIATIONS = "true"
+         stride project create my_config.json5
 
-# Enable dimension association checks (more thorough validation)
-export STRIDE_CHECK_DIMENSION_ASSOCIATIONS=true
-stride project create my_config.json5
 ```
 
 Valid values for boolean environment variables:
@@ -115,4 +141,4 @@ For development workflows, consider disabling checks to speed up iteration, then
 ## Related Topics
 
 - {ref}`data-validation` - Overview of the validation process
-- {ref}`data-download` - How to download datasets
+- {ref}`create-project-tutorial` - Tutorial on creating a stride project

docs/explanation/data_download.md

@@ -81,10 +81,27 @@ Downloaded datasets are stored in the data directory, which is determined by (in
 
 To use a custom data directory persistently, set the `STRIDE_DATA_DIR` environment variable:
 
-```bash
-export STRIDE_DATA_DIR=/path/to/my/data
-stride datasets download global
-stride projects create my_config.json5
+```{eval-rst}
+
+    .. tabs::
+
+      .. code-tab:: bash Mac/Linux
+
+         export STRIDE_DATA_DIR=/path/to/my/data
+         stride datasets download global
+         stride projects create my_config.json5
+
+      .. code-tab:: bash Windows Command Prompt
+
+         set STRIDE_DATA_DIR=/path/to/my/data
+         stride datasets download global
+         stride projects create my_config.json5
+
+      .. code-tab:: powershell Windows PowerShell
+
+         $env:STRIDE_DATA_DIR = "/path/to/my/data"
+         stride datasets download global
+         stride projects create my_config.json5
 ```
 
 Or specify it per-command with the `--data-dir` option:

docs/explanation/dbt_computation.md

@@ -176,3 +176,4 @@ For advanced customization, you can edit the SQL models directly:
 
 - {ref}`data-validation` - How input data is validated before dbt runs
 - {ref}`customizing-checks` - Configuring validation behavior
+- {ref}`dbt-projet` - Tutorial on browsing the dbt portion of a stride project

docs/explanation/weather_year_modeling.md

@@ -1,5 +1,5 @@
 (weather-year-modeling)=
-# Weather year modeling
+# Weather Year Modeling
 
 STRIDE uses detailed weather data to adjust electricity load shapes for temperature variations throughout the year. This page explains how weather data are processed and applied to create realistic hourly load profiles.
 
@@ -282,3 +282,6 @@ INFO: Temperature multiplier ranges for scenario=baseline:
 ## Related Topics
 
 - {ref}`dbt-computation` - Overall dbt transformation pipeline
+- {ref}`create-project-tutorial` - Tutorial on creating a stride project
+- {ref}`dbt-projet` - Tutorial on browsing the dbt portion of a stride project
+- {ref}`data-api-tutorial` - Tutorial on accessing and processing result data using Python

docs/how_tos/compare_scenarios.md

@@ -0,0 +1,59 @@
+(compare-scenarios)=
+# Compare Scenarios
+
+Programmatically query and compare results across scenarios.
+
+## Load the Project
+
+```python
+from stride import Project
+from stride.api import APIClient
+
+project = Project.load("my_project")
+client = APIClient(project)
+```
+
+## Query Multiple Scenarios
+
+```python
+baseline = client.get_total_consumption(scenario="baseline")
+high_growth = client.get_total_consumption(scenario="high_growth")
+```
+
+## Calculate Differences
+
+```python
+import pandas as pd
+
+comparison = pd.merge(
+    baseline, high_growth,
+    on=["geography", "model_year"],
+    suffixes=("_baseline", "_high_growth")
+)
+comparison["difference"] = (
+    comparison["value_high_growth"] - comparison["value_baseline"]
+)
+comparison["pct_difference"] = (
+    comparison["difference"] / comparison["value_baseline"] * 100
+)
+```
+
+## Visualize the Comparison
+
+```python
+import plotly.express as px
+
+fig = px.scatter(
+    comparison,
+    x="model_year",
+    y="pct_change",
+    color="geography",
+    title="Consumption Change: High Growth vs Baseline"
+)
+fig.show()
+```
+
+## See also
+
+- {ref}`data-api-tutorial` for more examples.
+- {ref}`launch-dashboard` for the visualization UI.

docs/how_tos/customize_palette.md

@@ -0,0 +1,53 @@
+(customize-palette)=
+# Customize the Color Palette
+
+Create consistent colors for visualizations.
+
+## View Available Palettes
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride palette list
+```
+
+## Preview a Palette
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride palette view my_project
+```
+
+## Create a Custom Palette
+
+Initialize a palette configuration file:
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride palette init my_project
+```
+
+This creates a JSON file you can edit to assign colors to scenarios, geographies, or other dimensions.
+
+## Set the Default Palette
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride palette set-default my_project custom_palette
+```
+
+## Reset to Default
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride palette get-default my_project
+```

docs/how_tos/download_datasets.md

@@ -0,0 +1,147 @@
+(download-datasets)=
+# Download Datasets
+
+## Prerequisites
+
+- STRIDE installed and available in your environment
+- For private repositories: GitHub CLI (`gh`) installed and authenticated
+
+## List available datasets
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride datasets list-remote
+```
+
+## Download a known dataset
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride datasets download global
+```
+
+This downloads to ``~/.stride/data`` (or ``STRIDE_DATA_DIR`` if set). Both the full dataset
+and its test subset are downloaded automatically.
+
+## Specify a version
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride datasets download global -v v0.2.0
+```
+
+## Specify a data directory
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride datasets download global -d /path/to/data
+```
+
+Or set the environment variable:
+
+```{eval-rst}
+
+  .. tabs::
+
+    .. code-tab:: bash Mac/Linux
+
+       $ export STRIDE_DATA_DIR=/path/to/data
+
+    .. code-tab:: bash Windows Command Prompt
+
+       $ set STRIDE_DATA_DIR=/path/to/data
+
+    .. code-tab:: powershell Windows PowerShell
+
+       $ $Env:STRIDE_DATA_DIR = "/path/to/data"
+```
+
+## Download from a custom repository
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ stride datasets download --url https://github.com/owner/repo --subdirectory data
+```
+
+```{eval-rst}
+.. note::
+   The ``--subdirectory`` option is required when using ``--url``.
+```
+
+## Private repositories
+
+Authenticate with GitHub CLI first:
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ gh auth login
+```
+
+## Alternative: Clone directly
+
+If ``gh`` is not available:
+
+```{eval-rst}
+
+  .. tabs::
+
+    .. code-tab:: bash Mac/Linux
+
+       $ git clone https://github.com/dsgrid/stride-data.git
+       $ export STRIDE_DATA_DIR=/path/to/stride-data
+
+    .. code-tab:: bash Windows Command Prompt
+
+       $ git clone https://github.com/dsgrid/stride-data.git
+       $ set STRIDE_DATA_DIR=/path/to/stride-data
+
+    .. code-tab:: powershell Windows PowerShell
+
+       $ git clone https://github.com/dsgrid/stride-data.git
+       $ $Env:STRIDE_DATA_DIR = "/path/to/stride-data"
+```
+
+Or copy to the default location:
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ git clone https://github.com/dsgrid/stride-data.git
+   $ mkdir -p ~/.stride/data
+   $ cp -r stride-data/global ~/.stride/data/
+   $ cp -r stride-data/global-test ~/.stride/data/
+```
+
+## Background
+
+Known datasets are hosted in the public [stride-data](https://github.com/dsgrid/stride-data)
+repository. The ``list-remote`` command displays each dataset's name, repository, subdirectory,
+description, and available versions. Datasets may have an associated test subset (shown as
+``test_subdirectory``) which is downloaded automatically alongside the main dataset.
+
+For private repositories, STRIDE uses GitHub CLI authentication. Check your authentication
+status with:
+
+```{eval-rst}
+
+.. code-block:: console
+
+   $ gh auth status
+```
+
+## Learn more
+
+- {ref}`cli-reference`