Skip to content

Commit

Permalink
Merge pull request #18 from UDST/doc-updates
Browse files Browse the repository at this point in the history
doc-updates
  • Loading branch information
sablanchard authored Aug 29, 2019
2 parents 5ab10ee + 85e027c commit ec2dc95
Show file tree
Hide file tree
Showing 5 changed files with 42 additions and 31 deletions.
6 changes: 5 additions & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,11 @@ Installation
conda
^^^^^

conda installation is forthcoming.
OSMnet is available on conda and can be installed with:

``conda install osmnet --channel conda-forge``

It is recommended to install via conda and the conda-forge channel especially if you find you are having issues installing some of the spatial dependencies.

pip
^^^
Expand Down
4 changes: 2 additions & 2 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@

templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
master_doc = 'index'
project = u'OSMnet'
copyright = u'2017, UrbanSim Inc.'
copyright = u'2019, UrbanSim Inc.'
author = u'UrbanSim Inc.'
version = u'0.1.5'
release = u'0.1.5'
Expand Down
35 changes: 19 additions & 16 deletions docs/source/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,17 @@ Dependencies
* geopandas >= 0.2.1
* Shapely >= 1.5

Note for Windows Users when Installing Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are a Windows user and you find when importing osmnet you see an error like this: ``ImportError: DLL load failed: The specified module could not be found.`` Most likely one of osmnet's dependencies did not install or compile correctly on your Windows machine. ``geopandas`` requires the dependency package ``fiona`` which requires the dependency package ``gdal``. Windows users should not install these dependencies via conda or pip, instead you should download and install these packages via `Christoph Gohlke Windows python wheels`_: `GDAL Windows Wheel`_ and `Fiona Windows Wheel`_. Download the package that matches your Python version and Windows system architecture, then cd into the download directory and install each package for example using: ``pip install Fiona-1.7.6-cp27-cp27m-win_amd64.whl`` and
``pip install GDAL-2.1.3-cp27-cp27m-win_amd64.whl``
If you have already installed these packaged via conda or pip, force a reinstall: ``pip install Fiona-1.7.6-cp27-cp27m-win_amd64.whl --upgrade --force-reinstall`` and
``pip install GDAL-2.1.3-cp27-cp27m-win_amd64.whl --upgrade --force-reinstall``

Current status
~~~~~~~~~~~~~~~~~~

*Forthcoming improvements:*

* Tutorial/demo

Installation
~~~~~~~~~~~~~~~~~~

conda
^^^^^^^^^^^^^

conda installation is forthcoming.
OSMnet is available on conda and can be installed with:

``conda install osmnet --channel conda-forge``

It is recommended to install via conda and the conda-forge channel especially if you find you are having issues installing some of the spatial dependencies.

pip
^^^^^^^^^^^^^
Expand All @@ -58,6 +47,20 @@ To update to the latest version:

Use ``git pull`` inside the cloned repository

Note for Windows Users when Installing Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are a Windows user, dependency installation issues can be minimized by using conda and the conda-forge channel. However, if you find you are still having issues with dependencies such as when importing osmnet you see an error like this: ``ImportError: DLL load failed: The specified module could not be found.`` Most likely one of osmnet's dependencies did not install or compile correctly on your Windows machine. ``geopandas`` requires the dependency package ``fiona`` which requires the dependency package ``gdal``. Windows users could try installing these dependencies via `Christoph Gohlke Windows python wheels`_: `GDAL Windows Wheel`_ and `Fiona Windows Wheel`_. Download the package that matches your Python version and Windows system architecture, then cd into the download directory and install each package for example using: ``pip install Fiona-1.7.6-cp27-cp27m-win_amd64.whl`` and
``pip install GDAL-2.1.3-cp27-cp27m-win_amd64.whl``
If you have already installed these packaged via conda or pip, force a reinstall: ``pip install Fiona-1.7.6-cp27-cp27m-win_amd64.whl --upgrade --force-reinstall`` and
``pip install GDAL-2.1.3-cp27-cp27m-win_amd64.whl --upgrade --force-reinstall``

Current status
~~~~~~~~~~~~~~~~~~

*Forthcoming improvements:*

* Tutorial/demo

.. _Anaconda: http://docs.continuum.io/anaconda/
.. _OSMnet repo: https://github.com/udst/osmnet
Expand Down
26 changes: 15 additions & 11 deletions osmnet/load.py
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ def osm_net_download(lat_min=None, lng_min=None, lat_max=None, lng_max=None,
Returns
-------
response_json : dict
Returns response_json as a value of dict with key 'elements'
"""

# create a filter to exclude certain kinds of ways based on the requested
Expand Down Expand Up @@ -345,15 +346,15 @@ def consolidate_subdivide_geometry(geometry, max_query_area_size):
Returns
-------
geometry : Polygon or MultiPolygon
geometry : Shapely Polygon or MultiPolygon
"""

# let the linear length of the quadrats (with which to subdivide the
# geometry) be the square root of max area size
quadrat_width = math.sqrt(max_query_area_size)

if not isinstance(geometry, (Polygon, MultiPolygon)):
raise ValueError('Geometry must be a shapely Polygon or MultiPolygon')
raise ValueError('Geometry must be a Shapely Polygon or MultiPolygon')

# if geometry is a MultiPolygon OR a single Polygon whose area exceeds
# the max size, get the convex hull around the geometry
Expand Down Expand Up @@ -394,7 +395,7 @@ def quadrat_cut_geometry(geometry, quadrat_width, min_num=3,
Returns
-------
multipoly : shapely MultiPolygon
multipoly : Shapely MultiPolygon
"""

# create n evenly spaced points between the min and max x and y bounds
Expand Down Expand Up @@ -431,13 +432,13 @@ def project_geometry(geometry, crs, to_latlong=False):
the geometry to project
crs : int
the starting coordinate reference system of the passed-in geometry
to_latlong : bool
to_latlong : bool, optional
if True, project from crs to WGS84, if False, project
from crs to local UTM zone
Returns
-------
geometry_proj, crs : tuple (projected shapely geometry, crs of the
geometry_proj, crs : tuple (projected Shapely geometry, crs of the
projected geometry)
"""
gdf = gpd.GeoDataFrame()
Expand All @@ -460,12 +461,14 @@ def project_gdf(gdf, to_latlong=False, verbose=False):
----------
gdf : GeoDataFrame
the gdf to be projected to UTM
to_latlong : bool
to_latlong : bool, optional
if True, projects to WGS84 instead of to UTM
verbose : bool, optional
if False, turns off log and print statements for this function
Returns
-------
gdf : GeoDataFrame
projected_gdf : GeoDataFrame
"""
assert len(gdf) > 0, 'You cannot project an empty GeoDataFrame.'
start_time = time.time()
Expand Down Expand Up @@ -518,7 +521,7 @@ def process_node(e):
Parameters
----------
e : dict
node : dict
individual node element in downloaded OSM json
Returns
Expand Down Expand Up @@ -583,7 +586,8 @@ def parse_network_osm_query(data):
Returns
-------
nodes, ways, waynodes : pandas.DataFrame
(nodes, ways, waynodes) : pandas.DataFrame
nodes, ways, waynodes as a tuple of pandas.DataFrames
"""
if len(data['elements']) == 0:
Expand Down Expand Up @@ -781,10 +785,10 @@ def network_from_bbox(lat_min=None, lng_min=None, lat_max=None, lng_max=None,
southern latitude of bounding box, if this parameter is used the bbox
parameter should be None.
lng_min : float
eastern latitude of bounding box, if this parameter is used the bbox
eastern longitude of bounding box, if this parameter is used the bbox
parameter should be None.
lat_max : float
northern longitude of bounding box, if this parameter is used the bbox
northern latitude of bounding box, if this parameter is used the bbox
parameter should be None.
lng_max : float
western longitude of bounding box, if this parameter is used the bbox
Expand Down
2 changes: 1 addition & 1 deletion osmnet/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ def great_circle_dist(lat1, lon1, lat2, lon2):
Returns
-------
dist : float
d : float
Distance in meters.
"""
Expand Down

0 comments on commit ec2dc95

Please sign in to comment.