From 9409d2f44ff6e806b4594696ffdd3f8a01a5865a Mon Sep 17 00:00:00 2001 From: Sam Maurer Date: Tue, 19 Feb 2019 19:09:19 -0800 Subject: [PATCH] Changelog and documentation --- CHANGELOG.md | 5 ++++ docs/build/.gitignore | 1 + docs/source/data-io.rst | 17 +++++++++++++ docs/source/getting-started.rst | 2 +- docs/source/index.rst | 3 ++- docs/source/model-steps.rst | 5 ++-- urbansim_templates/io/tables.py | 44 +++++++++------------------------ 7 files changed, 39 insertions(+), 38 deletions(-) create mode 100644 docs/build/.gitignore create mode 100644 docs/source/data-io.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index e9c36f1..205acce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # UrbanSim Templates change log +### 0.2.dev0 (2019-02-19) + +- adds first data i/o template: `urbansim_templates.io.TableFromDisk()` +- adds support for `autorun` template property + ### 0.1.1 (2019-02-05) - production release diff --git a/docs/build/.gitignore b/docs/build/.gitignore new file mode 100644 index 0000000..01b7e33 --- /dev/null +++ b/docs/build/.gitignore @@ -0,0 +1 @@ +**/* \ No newline at end of file diff --git a/docs/source/data-io.rst b/docs/source/data-io.rst new file mode 100644 index 0000000..7b726a9 --- /dev/null +++ b/docs/source/data-io.rst @@ -0,0 +1,17 @@ +Data I/O template APIs +====================== + +Data i/o templates let you set up automated model steps for loading data into Orca or saving outputs to disk. + +These templates follow the same principles as the statistical model steps. For example, to set up a data table, create an instance of the ``TableFromDisk`` class and set some properties: the table name, file type, path, and anything else that's needed. + +Registering this object with ModelManager will save it to disk as a yaml file, and create an Orca step with instructions to set up the table. "Running" the object/step registers the table with Orca, but doesn't read the data from disk yet — Orca loads data lazily as it's needed. + +Data registration steps are run automatically when you initialize ModelManager. + + +Table from disk +--------------- + +.. autoclass:: urbansim_templates.io.TableFromDisk + :members: diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 8f39858..1dce43d 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -105,7 +105,7 @@ The default file location is a ``configs`` folder located in the current working In [2]: import urbansim_templates print(urbansim_templates.__version__) - Out[2]: '0.1.dev12' + Out[2]: '0.2.dev0' Creating a model step diff --git a/docs/source/index.rst b/docs/source/index.rst index 2ba8129..4f765d0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,7 @@ UrbanSim Templates provides building blocks for Orca-based simulation models. It The library contains templates for common types of model steps, plus a tool called ModelManager that runs as an extension to the `Orca `__ task orchestrator. ModelManager can register template-based model steps with the orchestrator, save them to disk, and automatically reload them for future sessions. -v0.1.1, released February 5, 2019 +v0.2.dev0, released February 19, 2019 Contents @@ -22,5 +22,6 @@ Contents getting-started modelmanager model-steps + data-io utilities development diff --git a/docs/source/model-steps.rst b/docs/source/model-steps.rst index 54102fa..6f794fc 100644 --- a/docs/source/model-steps.rst +++ b/docs/source/model-steps.rst @@ -1,5 +1,5 @@ -Template APIs -============= +Model step template APIs +======================== The following templates are included in the core package. ModelManager can also work with templates defined elsewhere, as long as they follow the specifications described in the design guidelines. @@ -32,7 +32,6 @@ Large Multinomial Logit :members: - Segmented Large Multinomial Logit --------------------------------- diff --git a/urbansim_templates/io/tables.py b/urbansim_templates/io/tables.py index 87982d8..1e76cf1 100644 --- a/urbansim_templates/io/tables.py +++ b/urbansim_templates/io/tables.py @@ -3,7 +3,9 @@ try: import pathlib # Python 3.4+ except: - import os + pass + +import os import orca import pandas as pd @@ -14,13 +16,12 @@ @modelmanager.template class TableFromDisk(): """ - Class for registering data tables. In the initial implementation, data can come from - local CSV or HDF5 files. + Class for registering data tables from local CSV or HDF5 files. - An instance of this Table() template stores *instructions for loading a data table*, - which can be saved as a yaml file. Running these instructions registers the table - with Orca. Saved tables will be registered automatically when you initialize - ModelManager, replacing the `datasources.py` scripts used in previous versions of + An instance of this template class stores *instructions for loading a data table*, + packaged into an Orca step. Running the instructions registers the table with Orca. + Saved table registration steps will be run automatically when you initialize + ModelManager, replacing the ``datasources.py`` scripts used in previous versions of UrbanSim. Tables should include a unique index, or a set of columns that jointly represent a @@ -30,24 +31,7 @@ class TableFromDisk(): be able to use it as a join key. Following these naming conventions eliminates the need for Orca "broadcasts". - Usage - ----- - Create an empty class instance: `t = TableFromDisk()`. - - Give it some properties: `t.name = 'buildings'` etc. (These can also be passed when - you create the object.) - - Register with ModelManager: `modelmanager.register(t)`. This registers the table - loading instructions, runs them, and saves them to disk. They'll automatically be run - the next time you initialize ModelManager. - - You can use all the standard ModelManager commands to get copies of the saved table - loading instructions, modify them, and delete them: - - - `modelmanager.list_steps()` - - `t2 = modelmanager.get_step('name')` - - `modelmanager.register(t2)` - - `modelmanager.remove_step('name')` + All the parameters can also be set as properties of the class instance. Parameters ---------- @@ -102,11 +86,6 @@ class TableFromDisk(): autorun : bool, default True Automatically run the step whenever it's registered with ModelManager. - Properties and attributes - ------------------------- - All the parameters listed above can also be get and set as properties of the class - instance. - """ def __init__(self, source_type = None, @@ -205,15 +184,14 @@ def path(self, value): except: value = os.path.normpath(value) self.__path = value - print(value) def run(self): """ Register a data table with Orca. - Requires values to be set for 'source_type', 'name', and 'path'. CSV data also - requires 'csv_index_cols'. + Requires values to be set for ``source_type``, ``name``, and ``path``. CSV data + also requires ``csv_index_cols``. Returns -------