Changelog and documentation

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

docs/build/.gitignore

@@ -0,0 +1 @@
+**/*

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:

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

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 <https://udst.github.io/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

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
 ---------------------------------
 

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
         -------