Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@gboeing
gboeing committed Dec 17, 2024
1 parent b288115 commit d245013
Show file tree
Hide file tree
Showing 4 changed files with 50 additions and 31 deletions.
6 changes: 3 additions & 3 deletions docs/source/getting-started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ Get Started in 4 Steps

1. Install OSMnx by following the :doc:`installation` guide.

2. Read ":ref:`Introducing OSMnx`" below on this page.
2. Read ":ref:`introducing-osmnx`" below on this page.

3. Work through the OSMnx `Examples Gallery`_ for step-by-step tutorials and sample code.

4. Consult the :doc:`user-reference` for complete details on using the package.

Finally, if you're not already familiar with `NetworkX`_ and `GeoPandas`_, make sure you read their user guides as OSMnx uses their data structures and functionality.

.. _Introducing OSMnx:
.. _introducing-osmnx:

Introducing OSMnx
-----------------
Expand Down Expand Up @@ -47,7 +47,7 @@ The OSMnx `Examples Gallery`_ contains tutorials and demonstrations of all these
Configuration
^^^^^^^^^^^^^

You can configure OSMnx using the :code:`settings` module. Here you can adjust logging behavior, caching, server endpoints, and more. You can also configure OSMnx to retrieve historical snapshots of OpenStreetMap data as of a certain date. Refer to the FAQ below for server usage limitations.
You can configure OSMnx using the :code:`settings` module. Here you can adjust logging behavior, caching, server endpoints, and more. You can also configure OSMnx to retrieve historical snapshots of OpenStreetMap data as of a certain date. Read more about the :ref:`settings <osmnx-settings-module>` module.

Geocoding and Querying
^^^^^^^^^^^^^^^^^^^^^^
Expand Down
2 changes: 2 additions & 0 deletions docs/source/user-reference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,8 @@ osmnx.routing module
.. automodule:: osmnx.routing
:members:

.. _osmnx-settings-module:

osmnx.settings module
---------------------

Expand Down
11 changes: 9 additions & 2 deletions osmnx/convert.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -380,8 +380,15 @@ def to_undirected(G: nx.MultiDiGraph) -> nx.MultiGraph:
"""
Convert MultiDiGraph to undirected MultiGraph.
Maintains parallel edges only if their geometries differ. See also
`to_digraph` to convert MultiDiGraph to DiGraph.
This function has a limited use case: it allows you to create a MultiGraph
for use with functions/algorithms which only accept a MultiGraph object.
Rather, if you want a fully bidirectional graph (such as for a walking
network), configure the `settings` module's `bidirectional_network_types`
before creating your graph and OSMnx will generate a fully bidirectional
MultiDiGraph.
This function maintains parallel edges only if their geometries differ.
See also `to_digraph` to convert MultiDiGraph to DiGraph.
Parameters
----------
Expand Down
62 changes: 36 additions & 26 deletions osmnx/graph.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,11 @@ def graph_from_bbox(
Use the `settings` module's `useful_tags_node` and `useful_tags_way`
settings to configure which OSM node/way tags are added as graph node/edge
attributes. You can also use the `settings` module to retrieve a snapshot
of historical OSM data as of a certain date, or to configure the Overpass
server timeout, memory allocation, and other custom settings.
attributes. If you want a fully bidirectional network, ensure your
`network_type` is in `settings.bidirectional_network_types` before
creating your graph. You can also use the `settings` module to retrieve a
snapshot of historical OSM data as of a certain date, or to configure the
Overpass server timeout, memory allocation, and other customizations.
Parameters
----------
Expand All @@ -72,8 +74,8 @@ def graph_from_bbox(
If True, return the entire graph even if it is not connected. If
False, retain only the largest weakly connected component.
truncate_by_edge
If True, retain nodes outside bounding box if at least one of node's
neighbors is within the bounding box.
If True, retain nodes the outside bounding box if at least one of
the node's neighbors lies within the bounding box.
custom_filter
A custom ways filter to be used instead of the `network_type` presets,
e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
Expand Down Expand Up @@ -133,9 +135,11 @@ def graph_from_point(
Use the `settings` module's `useful_tags_node` and `useful_tags_way`
settings to configure which OSM node/way tags are added as graph node/edge
attributes. You can also use the `settings` module to retrieve a snapshot
of historical OSM data as of a certain date, or to configure the Overpass
server timeout, memory allocation, and other custom settings.
attributes. If you want a fully bidirectional network, ensure your
`network_type` is in `settings.bidirectional_network_types` before
creating your graph. You can also use the `settings` module to retrieve a
snapshot of historical OSM data as of a certain date, or to configure the
Overpass server timeout, memory allocation, and other customizations.
Parameters
----------
Expand All @@ -160,8 +164,8 @@ def graph_from_point(
If True, return the entire graph even if it is not connected. If
False, retain only the largest weakly connected component.
truncate_by_edge
If True, retain nodes outside bounding box if at least one of node's
neighbors is within the bounding box.
If True, retain nodes the outside bounding box if at least one of
the node's neighbors lies within the bounding box.
custom_filter
A custom ways filter to be used instead of the `network_type` presets,
e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
Expand Down Expand Up @@ -230,9 +234,11 @@ def graph_from_address(
Use the `settings` module's `useful_tags_node` and `useful_tags_way`
settings to configure which OSM node/way tags are added as graph node/edge
attributes. You can also use the `settings` module to retrieve a snapshot
of historical OSM data as of a certain date, or to configure the Overpass
server timeout, memory allocation, and other custom settings.
attributes. If you want a fully bidirectional network, ensure your
`network_type` is in `settings.bidirectional_network_types` before
creating your graph. You can also use the `settings` module to retrieve a
snapshot of historical OSM data as of a certain date, or to configure the
Overpass server timeout, memory allocation, and other customizations.
Parameters
----------
Expand All @@ -256,8 +262,8 @@ def graph_from_address(
If True, return the entire graph even if it is not connected. If
False, retain only the largest weakly connected component.
truncate_by_edge
If True, retain nodes outside bounding box if at least one of node's
neighbors is within the bounding box.
If True, retain nodes the outside bounding box if at least one of
the node's neighbors lies within the bounding box.
custom_filter
A custom ways filter to be used instead of the `network_type` presets,
e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
Expand Down Expand Up @@ -331,9 +337,11 @@ def graph_from_place(
Use the `settings` module's `useful_tags_node` and `useful_tags_way`
settings to configure which OSM node/way tags are added as graph node/edge
attributes. You can also use the `settings` module to retrieve a snapshot
of historical OSM data as of a certain date, or to configure the Overpass
server timeout, memory allocation, and other custom settings.
attributes. If you want a fully bidirectional network, ensure your
`network_type` is in `settings.bidirectional_network_types` before
creating your graph. You can also use the `settings` module to retrieve a
snapshot of historical OSM data as of a certain date, or to configure the
Overpass server timeout, memory allocation, and other customizations.
Parameters
----------
Expand All @@ -348,10 +356,10 @@ def graph_from_place(
If True, return the entire graph even if it is not connected. If
False, retain only the largest weakly connected component.
truncate_by_edge
If True, retain nodes outside bounding box if at least one of node's
neighbors is within the bounding box.
If True, retain nodes outside the place boundary polygon(s) if at
least one of the node's neighbors lies within the polygon(s).
which_result
which geocoding result to use. if None, auto-select the first
Which geocoding result to use. if None, auto-select the first
(Multi)Polygon or raise an error if OSM doesn't return one.
custom_filter
A custom ways filter to be used instead of the `network_type` presets,
Expand Down Expand Up @@ -412,9 +420,11 @@ def graph_from_polygon(
Use the `settings` module's `useful_tags_node` and `useful_tags_way`
settings to configure which OSM node/way tags are added as graph node/edge
attributes. You can also use the `settings` module to retrieve a snapshot
of historical OSM data as of a certain date, or to configure the Overpass
server timeout, memory allocation, and other custom settings.
attributes. If you want a fully bidirectional network, ensure your
`network_type` is in `settings.bidirectional_network_types` before
creating your graph. You can also use the `settings` module to retrieve a
snapshot of historical OSM data as of a certain date, or to configure the
Overpass server timeout, memory allocation, and other customizations.
Parameters
----------
Expand All @@ -430,8 +440,8 @@ def graph_from_polygon(
If True, return the entire graph even if it is not connected. If
False, retain only the largest weakly connected component.
truncate_by_edge
If True, retain nodes outside bounding box if at least one of node's
neighbors is within the bounding box.
If True, retain nodes outside `polygon` if at least one of the node's
neighbors lies within `polygon`.
custom_filter
A custom ways filter to be used instead of the `network_type` presets,
e.g. `'["power"~"line"]' or '["highway"~"motorway|trunk"]'`. If `str`,
Expand Down

0 comments on commit d245013

Please sign in to comment.