Merge pull request #162 from OSeMOSYS/develop

General Development Updates

.github/workflows/build.yaml

@@ -0,0 +1,37 @@
+name: Python build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        # os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+
+    steps:
+
+      - name: checkout repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install cartopy dependencies
+        run: sudo apt-get -y install libgeos-dev
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install -e .
+
+      - name: Test with pytest
+        run: |
+          tox

.gitmodules

@@ -1,6 +1,3 @@
 [submodule "OSeMOSYS_GNU_MathProg"]
 	path = resources/OSeMOSYS_GNU_MathProg
 	url = https://github.com/OSeMOSYS/OSeMOSYS_GNU_MathProg
-[submodule "simplicity"]
-	path = resources/simplicity
-	url = https://github.com/OSeMOSYS/simplicity

dashboard.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env python 
+python workflow/scripts/osemosys_global/dashboard/app.py

docs/advanced-functionality.md

@@ -135,4 +135,90 @@ Then run the workflow as normal from the root directory
 
 ```bash
 snakemake -c
-```
+```
+
+## Interactive Dashboard
+
+If a user wishes to explore input and output data, OSeMOSYS Global includes 
+an interactive dashboard to do this. This dashboard can only be run 
+after a successful model run. 
+
+### 1. Ensure the OSeMOSYS Global scenario has been run 
+
+The dashboard is **not** integreated with the snakemake workflow, therefore, 
+it will not automatically look for missing input files. Ensure that the 
+workflow has been run and that input data CSVs (`results/<scenario>/data/`)
+and result file CSVs (`results/<scenario>/results/`) exist. Moreover, 
+ensure the scenario name in the configuration file matches the paths to the
+result data. 
+
+### 2. Run the dashboard 
+
+Run the file `dashboard.sh` to start the dashboard in a local host with the 
+following command. Either open the hyperlink from the command line or 
+copy/paste it into a web browser. 
+
+```bash 
+bash dashboard.sh
+```
+
+### 3. Explore the dashboard 
+
+The dashboard is to visualize the input and result data from an OSeMOSYS Global 
+model run. The dashboard consists of 5 tabs; tab 1 is a options tab, and the 
+remaining tabs are different visualization options (described below).
+
+:::{warning}
+For large models, the dashboard my be slow to respond. Especially for 
+parameters/varibales plotted over timeslices, rather than years; for example
+the `ProductionByTechnologyAnnual` plot will respond much quicker than the 
+``ProductionByTechnology` plot. 
+:::
+
+#### 3.1 Options Tab 
+
+Global plotting options for the dashboard. Of note is the Geographic Scope 
+radio buttons. If the option is set to System, the legend axis in graphs will 
+be by technology. If the option is set to Country or Region, the legend axis 
+will be country or region respectively.
+
+#### 3.2 Geographic Overview Tab
+
+Allows the user to visualize what nodes and transmission lines are (and are 
+not) included in the model. The user can hover over each node/line to get the 
+corresponding node and line name. 
+
+:::{warning}
+Any custom nodes added are not included in this map, as latitudes and longitudes 
+are not added with custom nodes. All other tabs will correctly incorporate 
+custom node data. 
+:::
+
+#### 3.3 Input Data Tab
+
+Plots input data. The plot will take on the values described in the options tab. 
+The technology fuel dropdown is dynamic, based on the user parameter selection. This
+means if a technology or fuel is not listed in the dropdown, there is no 
+associated data with it. The plotting options include Area, Line, Stacked Bar 
+and Grouped Bar.
+
+#### 3.4 Result Data Tab
+
+Plots result data. The plot will take on the values described in the options tab. 
+The technology fuel dropdown is dynamic, based on the user variable selection. This
+means if a technology or fuel is not listed in the dropdown, there is no 
+associated data with it. The plotting options include Area, Line, Stacked Bar 
+and Grouped Bar.
+
+#### 3.5 The Options Tab 
+
+Plots transmission line result data. The user can select between plotting 
+at a system level, or for individual lines. Moreover, the variables include 
+poltting options for either directional flow (inports vs. exports) over the 
+line, or total magnitdue of flow. The plotting options include Area, Line, 
+Stacked Bar and Grouped Bar.
+
+### 4. Quit the dashboard 
+
+To exit the dashboard, close the tab/browser that has the dashboard open, and
+press `ctrl+c` or `cmd+c` from the command line. This will stop the local host. 

docs/api/osemosys_global.dashboard.components.rst

@@ -0,0 +1,69 @@
+osemosys\_global.dashboard.components package
+=============================================
+
+Submodules
+----------
+
+osemosys\_global.dashboard.components.ids module
+------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.ids
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.input\_data\_tab module
+-------------------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.input_data_tab
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.map\_tab module
+-----------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.map_tab
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.options\_tab module
+---------------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.options_tab
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.result\_data\_tab module
+--------------------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.result_data_tab
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.shared module
+---------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.shared
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.components.transmission\_tab module
+--------------------------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.components.transmission_tab
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: osemosys_global.dashboard.components
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/osemosys_global.dashboard.rst

@@ -0,0 +1,45 @@
+osemosys\_global.dashboard package
+==================================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   osemosys_global.dashboard.components
+
+Submodules
+----------
+
+osemosys\_global.dashboard.app module
+-------------------------------------
+
+.. automodule:: osemosys_global.dashboard.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.constants module
+-------------------------------------------
+
+.. automodule:: osemosys_global.dashboard.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+osemosys\_global.dashboard.utils module
+---------------------------------------
+
+.. automodule:: osemosys_global.dashboard.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: osemosys_global.dashboard
+   :members:
+   :undoc-members:
+   :show-inheritance: