docs update

.zenodo.json

@@ -7,6 +7,11 @@
             "affiliation": "KTH Royal Institute of Technology",
             "orcid": "0000-0001-9367-1791"
         },
+        {
+            "name": "Trevor Barnes",
+            "affiliation": "Simon Fraser University",
+            "orcid": "0000-0003-2458-2968"
+        },
         {
             "name": "Hauke Henke",
             "affiliation": "KTH Royal Institute of Technology",

AUTHORS.rst

@@ -2,4 +2,7 @@
 Contributors
 ============
 
-* Will Usher <[email protected]>
+* Will Usher <https://github.com/willu47>
+* Hauke Henke <https://github.com/HauHe>
+* Christoph Muschner <https://github.com/chrwm>
+* Trevor Barnes <https://github.com/trevorb1>

CHANGELOG.rst

@@ -4,9 +4,11 @@ Changelog
 Version 1.0
 ===========
 - Requires explicit provision of a user-defined configuration file for otoole to workbook
-- Reads in a model configuration from a datapackage
-- Fixed issue #114 so that conversion to Excel workbooks is now operating
+- Deprecates datapackage fuctionality
+- Adds setup command to generate template config.yaml and csv files
+- Documentation update
 - Bumped pyscaffold to 4.2
+- Otoole now requires Python 3.8 or later
 
 Version 0.9
 ===========

README.rst

@@ -24,12 +24,11 @@ Description
 for users of OSeMOSYS.The aim of the package is to provide commonly used pre-
 and post-processing steps for OSeMOSYS.
 
-.. image:: img/osemosys_dataflow.png
+.. image:: docs/_static/workflow.png
 
 **otoole** aims to support different ways of storing input data and results,
-including csv files, databases, datapackages and Excel workbooks,
-as well as different implementations of the OSeMOSYS model.
-This improves interoperability of analyses and
+including csv files, databases and Excel workbooks,as well as different implementations
+of the OSeMOSYS model. This improves interoperability of analyses and
 generally makes life a little bit easier.
 
 Installation
@@ -51,22 +50,9 @@ https://otoole.readthedocs.io/en/stable/index.html
 Contributing
 ============
 
-New ideas and bugs `should be submitted: <https://github.com/OSeMOSYS/otoole/issues/new>`_
+New ideas and bugs `should be submitted <https://github.com/OSeMOSYS/otoole/issues/new>`_
 to the repository Issue Tracker. Please do contribute by discussing and developing these
 ideas further, or by developing the codebase.
 
-To contribute directly to the documentation of code development, you
-first need to install the package in *develop mode*::
-
-    git clone http://github.com/OSeMOSYS/otoole
-    cd otoole
-    git checkout <branch you wish to use>
-    python setup.py develop
-
-Alternatively, use pip to install otoole from git in editable mode
-
-    pip install -e git+http://github.com/OSeMOSYS/otoole@master#egg=otoole
-
-Now, all changes made in the codebase will automatically be reflected
-in the installed Python version accessible on the command line or from
-importing otoole modules into other Python packages.
+To contribute directly to the documentation of code development, please see
+the contribution guidelines document.

citation.cff

@@ -4,13 +4,16 @@ authors:
   - family-names: Usher
     given-names: Will
     orcid: https://orcid.org/0000-0001-9367-1791
+  - family-names: Barnes
+    given-names: Trevor
+    orcid: https://orcid.org/0000-0003-2458-2968
   - family-names: Henke
     given-names: Hauke
     orcid: https://orcid.org/0000-0003-0098-8701
   - family-names: Muschner
     given-names: Christoph
     orcid: https://orcid.org/0000-0001-8144-5260
 title: "otoole: OSeMOSYS tools for energy work"
-version: 0.10.0
+version: 1.0.0
 doi: 10.5281/zenodo.4730003
 date-released: 2021-04-30

docs/contributing.rst

@@ -2,7 +2,7 @@
 Contributing
 ============
 
-Welcome to ``otoole`` contributor's guide.
+Welcome to ``otoole`` contributor's guide!
 
 This document focuses on getting any potential contributor familiarized
 with the development processes, but `other kinds of contributions`_ are also
@@ -78,15 +78,14 @@ Code Contributions
 ==================
 
 ``otoole`` is built around a command line tool which is written
-using the Python argparse library. The otoole.cli module is a useful
+using the Python argparse library. The ``otoole.cli`` module is a useful
 place to start when trying to understand how each command works.
 
 The ``otoole convert`` and ``otoole results`` commands both
-use classes which inherit the otoole.Strategy class.
-An ``otoole.ReadStrategy`` implements functionality which returns a
-dictionary of pandas.DataFrame objects.
-An ``otoole.WriteStrategy`` takes a dictionary of pandas.DataFrames
-as an argument and writes out the target file format.
+use classes which inherit the ``otoole.Strategy`` class.
+An ``otoole.ReadStrategy`` implements functionality to read in data, while an
+``otoole.WriteStrategy`` writes out the target file format. The internal datastore
+format in ``otool`` is a dictionary of ``pandas.DataFrames``.
 
 Comprehensive unit tests in the ``tests`` folder provide another way to
 understand what each of the components does.
@@ -224,7 +223,7 @@ package:
     tox -r -e docs
 
 #. Make sure to have a reliable |tox|_ installation that uses the correct
-   Python version (e.g., 3.7+). When in doubt you can run::
+   Python version (e.g., 3.8+). When in doubt you can run::
 
     tox --version
     # OR

docs/data.rst

@@ -7,22 +7,24 @@ Data Formats
 User Configuration File
 -----------------------
 
+.. versionadded:: v1.0.0
+    The user configuration file
+
 Overview
 ~~~~~~~~
 
-All commands in ``otoole`` require the user to specify a configuration file that describes
+Most commands in ``otoole`` require the user to specify a configuration file that describes
 the ``parameters``, ``sets``, and ``results`` in the model. This configuration file is
-written in ``yaml`` and is typically saved as ``config.yaml``. How to define the
-``parameters``, ``sets``, and ``results`` in this file are highlighted below. If the user
-incorrectly enters data, validation checks in ``otoole`` should catch this.
-
-This section will cover how to formate the user configuration file.
+written in ``yaml`` and is typically saved as ``config.yaml``. This section will cover how to
+format the user configuration file. If the user incorrectly enters data, validation checks in
+``otoole`` should catch this.
 
 Information Required
 ~~~~~~~~~~~~~~~~~~~~
 
-The table below highlights what information is required for each value type.
-Required values are given by ``X``, optional values are given by ``(X)``.
+The table below highlights what information is required for each ``Set``,
+``Parameter`` and ``Result`` definition in the configuration file. Required values are
+given by **X**, while optional values are given by **(X)**.
 
 +-------------+------+------------+---------+
 |             | Set  | Parameter  | Result  |
@@ -41,12 +43,12 @@ Required values are given by ``X``, optional values are given by ``(X)``.
 +-------------+------+------------+---------+
 
 .. WARNING::
-   Names that are longer than 31 characters require a ``short_name`` field. This is due
+   Names longer than 31 characters require a ``short_name`` field. This is due
    to character limits on excel sheet names. ``otoole`` will raise an error if a
    ``short_name`` is not provided in these instances.
 
-Sets
-~~~~
+Sets Format
+~~~~~~~~~~~
 
 Sets are defined as follows::
 
@@ -56,12 +58,12 @@ Sets are defined as follows::
         type: set
 
 .. NOTE::
-   It's convention in OSeMOSYS to give sets uppercase names
+   It's convention in OSeMOSYS to capitalize set names
 
-Parmaters
-~~~~~~~~~
+Parmaters Foramt
+~~~~~~~~~~~~~~~~
 
-Parameters are defined as follows. When referencing set indices, use the full
+Parameters are defined as follows. When referencing set indices use the full
 name, **not** the ``short_name``::
 
     ParameterName:
@@ -72,12 +74,12 @@ name, **not** the ``short_name``::
         default: 0
 
 .. NOTE::
-   It's convention in OSeMOSYS to use Pascal case for parameters
+   It's convention in OSeMOSYS to use Pascal case for parameter names
 
-Results
-~~~~~~~
+Results Format
+~~~~~~~~~~~~~~
 
-Results are defined as follows. When referencing set indices, use the full
+Results are defined as follows. When referencing set indices use the full
 name, **not** the ``short_name``::
 
     AnnualEmissions:
@@ -89,13 +91,12 @@ name, **not** the ``short_name``::
         calculated: "True" or "False"
 
 .. NOTE::
-   It's convention in OSeMOSYS to use Pascal case for results
-
+   It's convention in OSeMOSYS to use Pascal case for result names
 
 Examples
 ~~~~~~~~
 
-Below are examples of correctly formatted configuration file values. See the Simplicity
+Below are examples of correctly formatted configuration file values. See the Simplicity_
 repository for a complete example.
 
 1. Set definition of ``TECHNOLOGY``::
@@ -131,8 +132,11 @@ Overview
 This section will describe how to format data for ``excel``, ``csv``, and ``datafile``
 formats.
 
-.. NOTE::
-   See the Simplicity_ repository for a full example of all these formats.
+.. deprecated:: v1.0.0
+    The ``datapackage`` format is no longer supported
+
+.. SEEALSO::
+   See the Simplicity_ repository for a full example of these formats
 
 Excel
 ~~~~~
@@ -325,7 +329,7 @@ And in the same ``data.txt`` file, the set ``TECHNOLOGY`` will be defined as fol
         HYD2
         ...
 
-.. TIP::
+.. SEEALSO::
    For reading and writing between Python and AMPL_, see the amply_ Python package.
 
 .. _MathProg: https://en.wikibooks.org/wiki/GLPK/GMPL_(MathProg)

docs/examples.rst

@@ -4,9 +4,18 @@
 Examples
 --------
 
-This page will present examples to show the full functionality of ``otoole``.
-To follow these examples, clone the Simplicity_ repository and run all commands
-from the ``simplicity/`` directory.
+This page will present examples to show the full functionality of ``otoole``. It will
+walk through the ``convert``, ``results``, ``setup``, ``viz`` and ``validate``
+functionality in seperate simple use cases.
+
+.. NOTE::
+    To follow these examples, clone the Simplicity_ repository and run all commands
+    from the ``simplicity/`` directory.
+
+.. CAUTION::
+    While ``otoole`` does not require any solver, these examples will use the
+    free and open-source tools GLPK_ and CBC_ to build and solve example
+    models.
 
 Data Conversion
 ---------------
@@ -55,7 +64,7 @@ Result Processing
 Objective
 ~~~~~~~~~
 
-Use an excel worksheet to build and solve an OSeMOSYS model with CPLEX. Only
+Use an excel worksheet to build and solve an OSeMOSYS model with CBC. Only
 generate the results for ``TotalDiscountedCost`` and ``TotalCapacityAnnual``.
 
 1. ``otoole`` Convert
@@ -73,9 +82,9 @@ Use GLPK_ to build the model and save it as ``simplicity.lp``::
 
 3. Solve the Model
 ~~~~~~~~~~~~~~~~~~
-Use CPLEX_ to solve the model and save the solution file as ``simplicity.sol``::
+Use CBC_ to solve the model and save the solution file as ``simplicity.sol``::
 
-    $ cplex -c "read simplicity.sol" "optimize" "write simplicity.sol"
+    $ cbc simplicity.sol solve -solu simplicity.sol
 
 4. Modify the Configuration File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -95,16 +104,12 @@ Create a folder to hold the results::
 
     $ mkdir results
 
-Sort the solution file (only needed for CPLEX solution files)::
-
-    $ simplicity.sol sort > simplicity_sorted.sol
-
 Use ``otoole``'s ``result`` package to generate the result CSVs::
 
-    $ otoole results cplex csv simplicity_sorted.sol results config.yaml
+    $ otoole results cbc csv simplicity.sol results config.yaml
 
-Input Data Template Setup
--------------------------
+Template Setup
+--------------
 
 Objective
 ~~~~~~~~~
@@ -114,7 +119,7 @@ Generate a template configuration file and excel input file to use with
 
 1. Create the Configuration File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Run the following command, wto create a template configuration file
+Run the following command, to create a template configuration file
 called ``config.yaml``::
 
     $ otoole setup config config.yaml
@@ -123,7 +128,7 @@ called ``config.yaml``::
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ``otoole`` will only generate template CSV data, however, we want to input
 data in Excel format. Therefore, we will first generate CSV data and convert
-it to Excel format.::
+it to Excel format::
 
     $ otoole setup csv data
 
@@ -133,25 +138,24 @@ Open up the the file ``data/YEARS.csv`` and add all the years over the model
 horizon. For example, if the model horizon is from 2020 to 2050, the
 ``data/YEARS.csv`` file should be formatted as follows:
 
-+-------+
-| VALUE |
-+=======+
-| 2020  |
-|-------|
-| 2021  |
-|-------|
-| 2022  |
-|-------|
-| ...   |
-|-------|
-| 2050  |
-+-------+
++---------+
+| VALUE   |
++=========+
+| 2020    |
++---------+
+| 2021    |
++---------+
+| 2022    |
++---------+
+| ...     |
++---------+
+| 2050    |
++---------+
 
 .. NOTE::
    While this step in not technically required, by filling out the years in
    CSV format, ``otoole`` will pivot all the Excel sheets on the years
-   you input during the conversion process. This will save significant
-   formatting time!
+   during the conversion process. This will save significant formatting time!
 
 4. Convert the CSV Template Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -193,11 +197,15 @@ displayed
 Model Validation
 ----------------
 
+.. NOTE::
+    In this example, we will use a very simple model instead of the
+    Simplicity_ demonstration model. This way the user does not need to be
+    familar with the naming convenations of the model.
+
 Objective
 ~~~~~~~~~
 
-Use ``otoole`` to validate an input data file. In this example, we will use a
-very simple model instead of the Simplicity_ demonstration model. The model
+Use ``otoole`` to validate an input data file. The model
 we are going to validate is shown below, where the fuel and technology
 codes are shown in bold face.