Merge pull request #227 from UDST/dev

Finalizing v3.2 release

.travis.yml

@@ -1,42 +1,28 @@
 language: python
-sudo: false
+
 python:
-- '2.7'
-- '3.5'
+ - '2.7'
+ - '3.5'
+ - '3.6'
+ - '3.7'
+ - '3.8'
+
 install:
-- if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh
- -O miniconda.sh; else wget http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
- -O miniconda.sh; fi
-- bash miniconda.sh -b -p $HOME/miniconda
-- export PATH="$HOME/miniconda/bin:$PATH"
-- hash -r
-- conda config --set always_yes yes --set changeps1 no
-- conda update -q conda
-- conda info -a
-- >
- conda create -q -n test-environment
- python=$TRAVIS_PYTHON_VERSION
- cytoolz ipython-notebook jinja2 matplotlib numpy pandas patsy pip scipy
- statsmodels pytables pytest pyyaml toolz
-- source activate test-environment
-- pip install orca osmnet pandana bottle simplejson zbox
-- pip install pytest-cov coveralls pycodestyle
-- pip install .
+ - pip install .
+ - pip install -r requirements-dev.txt
+ - pip list
+ - pip show urbansim
+
 before_script:
-- git clone https://github.com/udst/sanfran_urbansim.git
-- cd sanfran_urbansim; jupyter nbconvert --to python Simulation.ipynb
-- cd ..
+ - git clone https://github.com/udst/sanfran_urbansim.git
+ - cd sanfran_urbansim; jupyter nbconvert --to python Simulation.ipynb
+ - cd ..
+
 script:
-- pycodestyle urbansim scripts
-- py.test --cov urbansim --cov-report term-missing
-- cd sanfran_urbansim; python Simulation.py
-- cd ..
+ - pycodestyle --max-line-length=100 urbansim
+ - py.test --cov urbansim --cov-report term-missing
+ - cd sanfran_urbansim; python Simulation.py
+ - cd ..
+
 after_success:
-- coveralls
-- bin/build_docs.sh
-notifications:
- slack:
- secure: LnbM2nYkvZF7FreNhqG+ExMeIsbbOWuuOi8ewZCCvMEMsYBEc9oE1hi23enpGUMElGzCTKOdCpQ/Z/QNHMycGZaL/wAZm5EPGNM7CZG1FKDrPYOTJ18ipi+k72k3GuqXM3DwGzjcRO6sw7kdy1k/3uVu8QHmkdgijLT6smIh6r4=
-env:
- global:
- - secure: c2olC+qzN1VHJZlznPy7mUtRvAyU7I2C7N3sYkv71Ds+dx5WN8InF6mpwNs/ZKfERbbA9slSVmYjB4j2c+VT8S1J33o6aI4F4hWNr6l7DgBKoPmozvaDx0GQ45hMOeSHSG5OF+DZCSTEXtxQK82uj61sCvZ6dIlDOqRvAHCjQDI=
+ - coveralls

HISTORY.rst → CHANGELOG.rst

@@ -1,3 +1,13 @@
+v3.2
+====
+
+2020/05/05
+
+* Improved installation and compatibility
+* Support for Pandas 1.0
+* Various improvements and bug fixes
+* Note that active development of certain UrbanSim components has moved to stand-alone libraries in UDST: Developer, Choicemodels, UrbanSim Templates
+
 v3.1.1
 ======
 

CONTRIBUTING.md

@@ -1,41 +1,80 @@
-Contributing to UrbanSim
-========================
+Thanks for using UrbanSim! 
 
-Style
------
+This is an open source project that's part of the Urban Data Science Toolkit. Development and maintenance is a collaboration between UrbanSim Inc, U.C. Berkeley's Urban Analytics Lab, and other contributors.
 
-- Python code should follow the [PEP 8 Style Guide][pep8].
-- Python docstrings should follow the [NumPy documentation format][numpydoc].
+You can contact Sam Maurer, the lead maintainer, at `[email protected]`.
 
-### Imports
 
-Imports should be one per line.
-Imports should be grouped into standard library, third-party,
-and intra-library imports. `from` import should follow "regular" `imports`.
-Within each group the imports should be alphabetized.
-Here's an example:
+## If you have a problem:
 
-```python
-import sys
-from glob import glob
+- Take a look at the [open issues](https://github.com/UDST/urbansim/issues) and [closed issues](https://github.com/UDST/urbansim/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a related discussion
 
-import numpy as np
+- Open a new issue describing the problem -- if possible, include any error messages, the operating system and version of python you're using, and versions of any libraries that may be relevant
 
-import urbansim.urbansim.modelcompile as modelcompile
-from urbansim.util import misc
-```
 
-Imports of scientific Python libraries should follow these conventions:
+## Feature proposals:
 
-```python
-import matplotlib.pyplot as plt
-import numpy as np
-import pandas as pd
-import scipy as sp
-```
+- Take a look at the [open issues](https://github.com/UDST/urbansim/issues) and [closed issues](https://github.com/UDST/urbansim/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a related discussion
 
+- Post your proposal as a new issue, so we can discuss it (some proposals may not be a good fit for the project)
 
-Thanks!
+- Please note that active development of certain UrbanSim components has moved to stand-alone libraries in UDST: Developer, Choicemodels, UrbanSim Templates
 
-[pep8]: http://legacy.python.org/dev/peps/pep-0008/
-[numpydoc]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+
+## Contributing code:
+
+- Create a new branch of `UDST/urbansim`, or fork the repository to your own account
+
+- Make your changes, following the existing styles for code and inline documentation
+
+- Add [tests](https://github.com/UDST/urbansim/tree/master/urbansim/tests) if possible!
+
+- Open a pull request to the `UDST/urbansim` dev branch, including a writeup of your changes -- take a look at some of the closed PR's for examples
+
+- Current maintainers will review the code, suggest changes, and hopefully merge it!
+
+
+## Updating the documentation: 
+
+- See instructions in `docs/README.md`
+
+
+## Preparing a release:
+
+- Make a new branch for release prep
+
+- Update the version number and changelog
+ - `CHANGELOG.md`
+ - `setup.py`
+ - `urbansim/__init__.py`
+ - `docs/source/index.rst`
+
+- Make sure all the tests are passing, and check if updates are needed to `README.md` or to the documentation
+
+- Open a pull request to the master branch to finalize it
+
+- After merging, tag the release on GitHub and follow the distribution procedures below
+
+
+## Distributing a release on PyPI (for pip installation):
+
+- Register an account at https://pypi.org, ask one of the current maintainers to add you to the project, and `pip install twine`
+
+- Check out the copy of the code you'd like to release
+
+- Run `python setup.py sdist bdist_wheel --universal`
+
+- This should create a `dist` directory containing two package files -- delete any old ones before the next step
+
+- Run `twine upload dist/*` -- this will prompt you for your pypi.org credentials
+
+- Check https://pypi.org/project/urbansim/ for the new version
+
+
+## Distributing a release on Conda Forge (for conda installation):
+
+- The [conda-forge/urbansim-feedstock](https://github.com/conda-forge/urbansim-feedstock) repository controls the Conda Forge release
+
+- Conda Forge bots usually detect new releases on PyPI and set in motion the appropriate feedstock updates, which a current maintainer will need to approve and merge
+
+- Check https://anaconda.org/conda-forge/urbansim for the new version (may take a few minutes for it to appear)

LICENSE → LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2016, UrbanSim, Inc. All rights reserved.
+Copyright (c) 2020, UrbanSim, Inc. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

MANIFEST.in

@@ -1,2 +1,5 @@
-include ez_setup.py
+include CHANGELOG.rst
+include CONTRIBUTING.md
+include LICENSE.txt
 include README.rst
+include requirements-dev.txt

README.rst

@@ -1,105 +1,52 @@
 UrbanSim
 ========
 
+.. image:: https://img.shields.io/pypi/v/urbansim.svg
+ :target: https://pypi.python.org/pypi/urbansim/
+ :alt: Latest Version
+
 .. image:: https://travis-ci.org/UDST/urbansim.svg?branch=master
- :alt: Build Status (Linux)
+ :alt: Build Status
  :target: https://travis-ci.org/UDST/urbansim
 
+.. image:: https://coveralls.io/repos/UDST/urbansim/badge.svg?branch=master
+ :alt: Test Coverage
+ :target: https://coveralls.io/r/UDST/urbansim?branch=master
 
-.. image:: https://ci.appveyor.com/api/projects/status/0ygo756020jpcrg3?svg=true
- :alt: Build Status (Windows)
- :target: https://ci.appveyor.com/project/pksohn/urbansim
+UrbanSim is a platform for building statistical models of cities and regions. These models help forecast long-range patterns in real estate development, demographics, and related outcomes, under various policy scenarios.
 
+This ``urbansim`` Python library is a core component. It contains tools for statistical estimation and simulation; domain-specific logic about housing markets, household relocation, and other processes; and frameworks and utilities for assembling a model. 
 
-.. image:: https://coveralls.io/repos/UDST/urbansim/badge.png?branch=master
- :alt: Test Coverage
- :target: https://coveralls.io/r/UDST/urbansim?branch=master
+How it works
+------------
+
+Operational UrbanSim models begin with detailed data about a particular region, and then estimate and validate a system of interconnected model components. Full models draw on a number of libraries: not just ``urbansim``, but also `Orca <https://github.com/UDST/orca>`__ for task orchestration, `Synthpop <https://github.com/UDST/synthpop>`__ for population synthesis, `Pandana <https://github.com/UDST/pandana>`__ for network analysis, and so on. Collectively, these make up the `Urban Data Science Toolkit <https://github.com/UDST>`__ (UDST).
+
+UrbanSim models are used by public agencies, consultancies, and researchers in dozens of cities around the U.S. and world. The core platform is open source, but many operational models make use of additional cloud-hosted model building and visualization tools provided by `UrbanSim Inc. <https://urbansim.com>`__
+
+Learn More
+----------
+
+* `An Introduction to UrbanSim <https://udst.github.io/urbansim/gettingstarted.html#a-gentle-introduction-to-urbansim>`__
+
+* `UrbanSim for San Francisco: An example implementation <https://github.com/UDST/sanfran_urbansim>`__
+
+* `UrbanSim Inc. <https://urbansim.com>`__
+
+Installation
+------------
+
+* ``pip install urbansim``
+
+* ``conda install urbansim --channel conda-forge``
+
+Technical documentation
+-----------------------
+
+* `Getting started <https://udst.github.io/urbansim/gettingstarted.html>`__
+
+* `Full documentation <https://udst.github.io/urbansim/>`__
+
+* Other `UDST <https://docs.udst.org>`__ libraries
 
-New version of UrbanSim, a tool for modeling metropolitan real estate
-markets
-
-.. image:: http://i.imgur.com/4YyN8ob.jpg
- :alt: UrbanSim
-
-`Detailed documentation <http://udst.github.io/urbansim/>`__ for
-UrbanSim is now available.
-
-`Click
-here <http://udst.github.io/urbansim/gettingstarted.html#installation>`__
-for installation instructions.
-
-Let us know what you are working on or if you think you have a great use case
-by tweeting us at ``@urbansim`` or post on the UrbanSim `forum`_.
-
-UrbanSim History
-----------------
-
-UrbanSim (http://www.urbansim.com) 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 UrbanSim Inc. and 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, 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.
-
-We lean heavily on the `PyData <http://pydata.org>`__ community to make
-our work easier - Pandas, `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 <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 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 the team at www.urbansim.com about your
-project to make sure you can get support when you need it,
-and know what you are getting into. For major applied projects,
-professional support is highly recommended.
-
-Reporting bugs and contributing to UrbanSim
---------------------------------------------
-
-Please report any bugs you encounter via `GitHub Issues <https://github.com/UDST/urbansim/issues>`__.
-
-If you have improvements or new features you would like to see in UrbanSim:
-
-1. Open a feature request via `GitHub Issues <https://github.com/UDST/urbansim/issues>`__.
-2. See our code contribution instructions `here <https://github.com/UDST/urbansim/blob/master/CONTRIBUTING.md>`__.
-3. Contribute your code from a fork or branch by using a Pull Request and request a review so it can be considered as an addition to the codebase.
-
-Academic literature
--------------------
-
-A selection of academic literature on UrbanSim can be found `here <http://www.urbansim.com/research/>`_.
-
-.. _forum: http://discussion.urbansim.com/
+* Documentation for `UrbanCanvas <https://cloud.urbansim.com/docs/>`__, the UrbanSim cloud platform