Merge branch 'master' into high-level-docs

Conflicts:
	docs/examples.rst

README.md

@@ -7,33 +7,25 @@ New version of UrbanSim, a tool for modeling metropolitan real estate markets
 
 ![synthicity](http://i.imgur.com/4YyN8ob.jpg)
 
-Documentation is on the github wiki: https://github.com/synthicity/urbansim/wiki
+[Detailed documentation](http://synthicity.github.io/urbansim/) for UrbanSim is now available.
 
-**Installation instructions** for UrbanSim users are available on [this page](http://synthicity.github.io/urbansim/gettingstarted.html#installation).
+[Click here](http://synthicity.github.io/urbansim/gettingstarted.html#installation) for installation instructions.
 
 UrbanSim
--------
-UrbanSim [1] is a model system for analyzing urban development.  It is an open source platform that has been continuously refined and distributed for planning applications around the world for over 15 years.  Part of the evolution of the platform is the necessary process of re-engineering the code to take advantage of new developments in computational libraries and infrastructure.  We implemented UrbanSim initially in Java in the late 1990's, and by 2005 determined that it was time to re-implement it in Python, and created the Open Platform for Urban Simulation (OPUS) software implementation at that time.  Now, almost a decade later, it is time again to revisit the implementation to take advantage of an amazing amount of innovation in the scientific computing community. The new implementation is hosted on this GitHub site, and maintained by Synthicity and hopefully a growing community of contributors.
+--------
+[UrbanSim](http://urbansim.org/) is a model system for analyzing urban development.  It is an open source platform that has been continuously refined and distributed for planning applications around the world for over 15 years.  Part of the evolution of the platform is the necessary process of re-engineering the code to take advantage of new developments in computational libraries and infrastructure.  We implemented UrbanSim initially in Java in the late 1990's, and by 2005 determined that it was time to re-implement it in Python, and created the Open Platform for Urban Simulation (OPUS) software implementation at that time.  Now, almost a decade later, it is time again to revisit the implementation to take advantage of an amazing amount of innovation in the scientific computing community. The new implementation is hosted on this GitHub site, and maintained by Synthicity and hopefully a growing community of contributors.
 
 New UrbanSim Implementation
--------
+---------------------------
 
-This new code base is a streamlined complete re-implementation of the longstanding UrbanSim project  aimed at *reducing the complexity* of using the UrbanSim methodology.  Redesigned from the ground up, it is a tool to make installation as trivial as any other Python package available today, and making modeling much more widely accessible to planners and new modelers.
+This new code base is a streamlined complete re-implementation of the longstanding UrbanSim project aimed at *reducing the complexity* of using the UrbanSim methodology.  Redesigned from the ground up, the new library is trivial to install, the development process is made transparent via this GitHub site, and exhaustive documentation has been created in the hopes of making modeling much more widely accessible to planners and new modelers.
 
-This UrbanSim package uses no code from the svn repository currently hosted on urbansim.org, though it makes every effort to implement the exact same methodology, but with a lighter footprint.  We lean heavily on the PyData [2] community to make our work easier - *Pandas, HDF5 file storage, and statsmodels* are ubiquitous in this work.  These Python libraries essentially replace the UrbanSim Dataset class, tools to read and write from other storage, and some of the statistical estimation currently present in UrbanSim.
+We lean heavily on the [PyData](http://pydata.org) community to make our work easier - [Pandas](pandas.pydata.org), [IPython](http://ipython.org/) and [statsmodels](http://statsmodels.sourceforge.net/) are ubiquitous in this work.  These Python libraries essentially replace the UrbanSim Dataset class, tools to read and write from other storage, and some of the statistical estimation previously implemented by UrbanSim.
 
-This makes our task easier as we can focus on urban modeling and leave the infrastructure to the wider Python community.  The Pandas [3] library is the core of the new UrbanSim, and is an extremely well documented library that has a large community providing support, and a very helpful *book* [4].  So please refer to those resources for detailed information on Pandas. 
+This makes our task easier as we can focus on urban modeling and leave the infrastructure to the wider Python community.  The [Pandas](http://pandas.pydata.org) library is the core of the new UrbanSim, which is an extremely popular data manipulation library with a large community providing support and a very helpful [book](http://www.amazon.com/Python-Data-Analysis-Wes-McKinney/dp/1449319793).
 
-We have now converted a full set of UrbanSim models in the new framework, enabling a complete UrbanSim application, and have these running for applications in Paris, Albuquerque, Denver, and others currently being implemented or converted from the earlier OPUS implementation.  These models include 1) *hedonic price models* 2) MNL and nested *location choice models* 3) transition models for increasing population, jobs, and development and 4) relocation rate models to specify the movement of population and jobs.  We have also implemented a new real estate development model using proforma analysis.
-
-**If you just want to begin experimenting and creating regression and choice models and map their inputs and outputs, you've also come to the right place.**
-
-[1] http://urbansim.org/
-
-[2] http://pydata.org
-
-[3] http://pandas.pydata.org
-
-[4] http://www.amazon.com/Python-Data-Analysis-Wes-McKinney/dp/1449319793
+We have now converted a full set of UrbanSim models to the new framework, and have running applications for the Paris, Albuquerque, Denver, Bay Area, and Detroit regions.  We have implemented a complete set of hedonic price models, location choice models, relocation and transition models, as well as a new real estate development model using proforma analysis.
 
 We do strongly recommend that you contact info@synthicity.org about your project to make sure you can get professional support when you need it, and know what you are getting into.  For major applied projects, professional support is highly recommended.
+
+**On the other hand, if you just want to begin experimenting and creating regression and choice models and map their inputs and outputs, you've also come to the right place.**

docs/examples.rst

@@ -208,14 +208,14 @@ One thing to note is the `autoreload magic <http://ipython.org/ipython-doc/dev/c
 Estimation Workflow
 ~~~~~~~~~~~~~~~~~~~
 
-A sample estimation workflow is available `in the San Francisco example <http://nbviewer.ipython.org/github/synthicity/sanfran_urbansim/blob/462f1f9f7286ffbaf83ae5ad04775494bf4d1677/Estimation.ipynb>`_.
+A sample estimation workflow is available `in this Notebook <http://nbviewer.ipython.org/github/synthicity/sanfran_urbansim/blob/462f1f9f7286ffbaf83ae5ad04775494bf4d1677/Estimation.ipynb>`__.
 
 This notebook estimates all of the models in the example that need estimation (because they are statistical models).  In fact, every cell simply calls the `sim.run <sim/index.html#running-simulations>`_ method with one of the names of the model entry points defined in ``models.py``. The ``sim.run`` method resolves all of the dependencies and prints the output of the model estimation in the result cell of the IPython Notebook.  Note that the hedonic models are estimated first, then simulated, and then the location choice models are estimated since the hedonic models are dependencies of the location choice models.  In other words, the ``rsh_simulate`` method is configured to create the ``residential_sales_price`` column which is then a right hand side variable in the ``hlcm_estimate`` model (because residential price is theorized to impact the location choices of households).
 
 Simulation Workflow
 ~~~~~~~~~~~~~~~~~~~
 
-A sample simulation workflow (for a complete UrbanSim simulation is available `here <http://nbviewer.ipython.org/github/synthicity/sanfran_urbansim/blob/462f1f9f7286ffbaf83ae5ad04775494bf4d1677/Simulation.ipynb>`_.
+A sample simulation workflow (a complete UrbanSim simulation is available `in this Notebook <http://nbviewer.ipython.org/github/synthicity/sanfran_urbansim/blob/462f1f9f7286ffbaf83ae5ad04775494bf4d1677/Simulation.ipynb>`__.
 
 This notebook is possibly even simpler than the estimation workflow as it has only one substantive cell which runs all of the available models in the appropriate sequence.  Passing a range of years will run the simulation for multiple years (the example simply runs the simulation for a single year).  Other parameters are available to the  `sim.run <sim/index.html#running-simulations>`_ method which write the output to an HDF5 file.
 
@@ -230,7 +230,7 @@ This is another simple and powerful notebook which can be used to quickly map va
 
 See :ref:`dframe-explorer` for detailed information on how to call the ``start`` method and what queries the website is performing.
 
-Once the ``start``method has been called, the IPython Notebook is running a web service which will respond to queries from a web browser.  Try is out - open your web browser and navigate to http://localhost:8765/ or follow the same link embedded in your notebook.  Note the link won't work on the web example - you need to have the example running on your local machine - all queries are run interactively between your web browser and the IPython Notebook.  Your web browser should show a page like the following:
+Once the ``start`` method has been called, the IPython Notebook is running a web service which will respond to queries from a web browser.  Try is out - open your web browser and navigate to http://localhost:8765/ or follow the same link embedded in your notebook.  Note the link won't work on the web example - you need to have the example running on your local machine - all queries are run interactively between your web browser and the IPython Notebook.  Your web browser should show a page like the following:
 
 .. image:: screenshots/dframe_explorer_screenshot.png