Merge pull request #141 from UDST/develop

Finalizing Pandana v0.5 release

.travis.yml

@@ -4,17 +4,13 @@ python:
   - '2.7'
   - '3.5'
   - '3.6'
-
-# This section can be removed when Python 3.7 is more cleanly supported in Travis
-matrix:
-  include:
-    - python: '3.7'
-      dist: xenial
-      sudo: true
+  - '3.7'
+  - '3.8'
 
 install:
   - pip install .
   - pip install -r requirements-dev.txt
+  - pip install -r requirements-extras.txt
   - pip list
   - pip show pandana
 
@@ -24,8 +20,3 @@ script:
 
 after_success:
   - coveralls
-  - bin/build_docs.sh
-
-env:
-  global:
-    secure: CMG0rjBgDBNy5FdfXawaaCCJm9ChzHk7e21ywVhIc1jbVS6lMn6bqwKJUnLaJAyjDhhZuxXTcHy+SALJgbzqLrH4GM5hOOL+8Rf4Jf9ESZzTBryvypRecVnUnk63SpJiq2Ki8maNrOcK1IBUAoFhFzptSgE4MDkxZ0LjsDAums8=

CHANGELOG.md

@@ -1,3 +1,16 @@
+v0.5
+====
+
+2020/07/28
+
+* Adds support for calculating shortest path lengths between arbitrary origins and destinations, with vectorization and multi-threading
+* Restores alternate names for aggregation types, which were inadvertently removed in v0.4
+* Fixes a bug with matplotlib backends
+* Improves compilation in MacOS 10.15 Catalina
+* Eliminates the scikit-learn dependency
+* Makes matplotlib and osmnet dependencies optional
+* Revises the documentation and demo notebook
+
 v0.4.4
 ======
 

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+Thanks for using Pandana! 
+
+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.
+
+You can contact Sam Maurer, the lead maintainer, at `[email protected]`.
+
+
+## If you have a problem:
+
+- Take a look at the [open issues](https://github.com/UDST/pandana/issues) and [closed issues](https://github.com/UDST/pandana/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a related discussion
+
+- 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
+
+
+## Feature proposals:
+
+- Take a look at the [open issues](https://github.com/UDST/pandana/issues) and [closed issues](https://github.com/UDST/pandana/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)
+
+
+## Contributing code:
+
+- Create a new branch of `UDST/pandana`, 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/pandana/tests) if possible!
+
+- Open a pull request to the `UDST/pandana` 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`
+  - `pandana/__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`
+
+- This should create a `dist` directory containing a gzip package file -- 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/pandana/ for the new version
+
+
+## Distributing a release on Conda Forge (for conda installation):
+
+- The [conda-forge/pandana-feedstock](https://github.com/conda-forge/pandana-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/pandana for the new version (may take a few minutes for it to appear)

MANIFEST.in

@@ -1,8 +1,10 @@
 # files to include in the source distribution on pypi (setup.py and README.md are included automatically)
 
 include CHANGELOG.md
+include CONTRIBUTING.md
 include LICENSE.txt
 include requirements-dev.txt
+include requirements-extras.txt
 include setup.cfg
 
 recursive-include examples *.ipynb *.py

README.md

@@ -1,17 +1,21 @@
-![Version](https://img.shields.io/badge/version-0.4.4-blue.svg)
+![Version](https://img.shields.io/badge/version-0.5-blue.svg)
 [![Travis build status](https://travis-ci.org/UDST/pandana.svg?branch=master)](https://travis-ci.org/UDST/pandana)
 [![Appveyor build status](https://ci.appveyor.com/api/projects/status/a90kvns7qe56kg57?svg=true)](https://ci.appveyor.com/project/smmaurer/pandana)
 [![Coverage Status](https://coveralls.io/repos/github/UDST/pandana/badge.svg?branch=master)](https://coveralls.io/github/UDST/pandana?branch=master)
 
 # Pandana
 
-Pandana is a Python package that uses [contraction hierarchies](https://en.wikipedia.org/wiki/Contraction_hierarchies) to perform rapid network calculations including shortest paths and accessibility buffers. The computations are parallelized for use on multi-core machines using an underlying C/C++ library. Pandana is tested on Mac, Linux, and Windows with Python 2.7, 3.6, and 3.7.
+Pandana is a Python library for network analysis that uses [contraction hierarchies](https://en.wikipedia.org/wiki/Contraction_hierarchies) to calculate super-fast travel accessibility metrics and shortest paths. The numerical code is in C++.
+
+v0.5 adds vectorized calculation of shortest path lengths: [network.shortest_path_lengths()](http://udst.github.io/pandana/network.html#pandana.network.Network.shortest_path_lengths). 
 
 Documentation: http://udst.github.io/pandana
 
 
 ### Installation
 
+Pandana runs on Mac, Linux, and Windows with Python 2.7, 3.6, 3.7, and 3.8.
+
 The easiest way to install Pandana is using the [Anaconda](https://www.anaconda.com/distribution/) package manager. Pandana's Anaconda distributions are pre-compiled and include multi-threading support on all platforms. 
 
 `conda install pandana --channel conda-forge`
@@ -21,25 +25,18 @@ See the documentation for information about other [installation options](http://
 
 ### Demo
 
-[Example.ipynb](https://github.com/UDST/pandana/blob/master/examples/Example.ipynb)
-
-The image below shows the distance to the _second_ nearest restaurant from each street intersection in the city of San Francisco. Pandana can calculate this in about half a second of computation time. 
+[Pandana-demo.ipynb](examples/Pandana-demo.ipynb)
 
-<img src="https://raw.githubusercontent.com/udst/pandana/master/docs/img/distance_to_restaurants.png" width=400>
 
 
-## Acknowledgments
+### Acknowledgments
 
-None of this would be possible without the help of Dennis Luxen and
-his [OSRM](https://github.com/DennisOSRM/Project-OSRM) project. Thank you Dennis!
+Pandana was created by [Fletcher Foti](https://github.com/fscottfoti), with subsequent contributions from [Matt Davis](https://github.com/jiffyclub), [Federico Fernandez](https://github.com/federicofernandez), [Sam Maurer](https://github.com/smmaurer), and others. Sam Maurer is currently the lead maintainer. Pandana relies on contraction hierarchy code from [Dennis Luxen](https://github.com/DennisOSRM) and his [OSRM project](https://github.com/DennisOSRM/Project-OSRM).
 
 
-### Academic Literature
+### Academic literature
 
-A [complete description of the
-methodology](http://onlinepubs.trb.org/onlinepubs/conferences/2012/4thITM/Papers-A/0117-000062.pdf)
-was presented at the Transportation Research Board Annual Conference in 2012. Please cite this paper when referring
-to the methodology implemented by this library.
+A [paper on Pandana](http://onlinepubs.trb.org/onlinepubs/conferences/2012/4thITM/Papers-A/0117-000062.pdf) was presented at the Transportation Research Board Annual Conference in 2012. Please cite this paper when referring to the methodology implemented by this library.
 
 
 ### Related UDST libraries

docs/README.md

@@ -0,0 +1,31 @@
+This folder generates the Pandana online documentation, hosted at https://udst.github.io/pandana/.
+
+### How it works
+
+HTML files are generated using [Sphinx](http://sphinx-doc.org) and hosted with GitHub Pages from the `gh-pages` branch of the repository. The online documentation is rendered and updated **manually**. 
+
+### Editing the documentation
+
+The files in `docs/source`, along with docstrings in the source code, determine what appears in the rendered documentation. Here's a [good tutorial](https://pythonhosted.org/an_example_pypi_project/sphinx.html) for Sphinx.
+
+### Previewing changes locally
+
+Install the copy of Pandana that the documentation is meant to reflect. Install the documentation tools.
+
+```
+pip install . 
+pip install sphinx sphinx_rtd_theme numpydoc
+```
+
+Build the documentation. There should be status messages and warnings, but no errors.
+
+```
+cd docs
+sphinx-build -b html source build
+```
+
+The HTML files will show up in `docs/build/`. 
+
+### Uploading changes
+
+Clone a second copy of the repository and check out the `gh-pages` branch. Copy over the updated HTML files, commit them, and push the changes to GitHub.

docs/build/.gitignore

@@ -0,0 +1 @@
+*.*