DOC: User guide refresh (#599)

* getting started * readme update * user guide update * fix multiindex issue in shape * fix verify_tessellation if no collapsed are present * minimise direct use of matplotlib * update index * minor fixes
pysal · Jun 14, 2024 · 96a8418 · 96a8418
1 parent 2ead868
commit 96a8418
Show file tree

Hide file tree

Showing 23 changed files with 1,947 additions and 9,026 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,13 @@
 # momepy
+
 [![Documentation Status](https://readthedocs.org/projects/momepy/badge/?version=latest)](http://docs.momepy.org/en/latest/?badge=latest) [![Actions Status](https://github.com/pysal/momepy/workflows/Tests/badge.svg)](https://github.com/pysal/momepy/actions?query=workflow%3ATests)
 [![codecov](https://codecov.io/gh/pysal/momepy/branch/main/graph/badge.svg?token=VNn0WR5JWT)](https://codecov.io/gh/pysal/momepy) [![Discord](https://img.shields.io/badge/Discord-join%20chat-7289da?style=flat&logo=discord&logoColor=cccccc&link=https://discord.gg/he6Y8D2ap3)](https://discord.gg/he6Y8D2ap3) [![DOI](https://joss.theoj.org/papers/10.21105/joss.01807/status.svg)](https://doi.org/10.21105/joss.01807)
 
 
 <img src="https://raw.githubusercontent.com/pysal/momepy/main/docs/_static/logo.png" width="50%">
 
 ## Introduction
+
 Momepy is a library for quantitative analysis of urban form - urban morphometrics. It is
 part of [PySAL (Python Spatial Analysis Library)](http://pysal.org) and is built on top
 of [GeoPandas](http://geopandas.org), other [PySAL](http://pysal.org) modules, and
@@ -15,13 +17,13 @@ of [GeoPandas](http://geopandas.org), other [PySAL](http://pysal.org) modules, a
 
 Some of the functionality that momepy offers:
 
-- Measuring [dimensions](https://docs.momepy.org/en/latest/api.html#dimension) of morphological elements, their parts, and aggregated structures.
-- Quantifying [shapes](https://docs.momepy.org/en/latest/api.html#shape) of geometries representing a wide range of morphological features.
-- Capturing [spatial distribution](https://docs.momepy.org/en/latest/api.html#spatial-distribution) of elements of one kind as well as relationships between different kinds.
-- Computing density and other types of [intensity](https://docs.momepy.org/en/latest/api.html#intensity) characters.
-- Calculating [diversity](https://docs.momepy.org/en/latest/api.html#diversity) of various aspects of urban form.
-- Capturing [connectivity](https://docs.momepy.org/en/latest/api.html#graph) of urban street networks.
-- Generating relational [elements](https://docs.momepy.org/en/latest/api.html#elements) of urban form (e.g. morphological tessellation).
+- Measuring [dimensions](https://docs.momepy.org/en/latest/api.html##measuring-dimension) of morphological elements, their parts, and aggregated structures.
+- Quantifying [shapes](https://docs.momepy.org/en/latest/api.html#measuring-shape) of geometries representing a wide range of morphological features.
+- Capturing [spatial distribution](https://docs.momepy.org/en/latest/api.html#measuring-spatial-distribution) of elements of one kind as well as relationships between different kinds.
+- Computing density and other types of [intensity](https://docs.momepy.org/en/latest/api.html#measuring-intensity) characters.
+- Calculating [diversity](https://docs.momepy.org/en/latest/api.html#measuring-diversity) of various aspects of urban form.
+- Capturing [connectivity](https://docs.momepy.org/en/latest/api.html#measuring-connectivity) of urban street networks.
+- Generating relational [elements](https://docs.momepy.org/en/latest/api.html#managing-morphological-elements) of urban form (e.g. morphological tessellation).
 
 Momepy aims to provide a wide range of tools for a systematic and exhaustive analysis of urban form. It can work with a wide range of elements, while focused on building footprints and street networks.
 
@@ -30,28 +32,19 @@ Comments, suggestions, feedback, and contributions, as well as bug reports, are
 The package is currently maintained by [**@martinfleis**](https://github.com/martinfleis) and [**@jGaboardi**](https://github.com/jGaboardi).
 
 ## Getting Started
-A quick and easy [getting started guide](http://docs.momepy.org/en/stable/user_guide/getting_started.html) is part of the [User Guide](http://docs.momepy.org/en/stable/user_guide/intro.html).
+
+A quick and easy [getting-started guide](http://docs.momepy.org/en/stable/user_guide/getting_started.html) is part of the [User Guide](http://docs.momepy.org/en/stable/user_guide/intro.html).
 
 
 ## Documentation
+
 Documentation of `momepy` is available at [docs.momepy.org](https://docs.momepy.org/).
 
 
 ## Examples
 
 ```py
-coverage = momepy.AreaRatio(tessellation, buildings, left_areas=tessellation.area,
-                            right_areas='area', unique_id='uID')
-tessellation['CAR'] = coverage.series
-```
-
-![Coverage Area Ratio](https://raw.githubusercontent.com/pysal/momepy/main/docs/_static/example1.png)
-
-```py
-area_simpson = momepy.Simpson(tessellation, values='area',
-                              spatial_weights=sw3,
-                              unique_id='uID')
-tessellation['area_simpson'] = area_simpson.series
+tessellation['area_simpson'] = momepy.simpson(tessellation.area, contiguity_k3)
 ```
 
 ![Local Simpson's diversity of area](https://raw.githubusercontent.com/pysal/momepy/main/docs/_static/diversity_22_0.png)
@@ -64,7 +57,8 @@ G = momepy.straightness_centrality(G)
 
 
 ## How to cite
-To cite `momepy` please use following [software paper](https://doi.org/10.21105/joss.01807) published in the JOSS.
+
+To cite `momepy` please use the following [software paper](https://doi.org/10.21105/joss.01807)](https://doi.org/10.21105/joss.01807) published in the JOSS.
 
 Fleischmann, M. (2019) ‘momepy: Urban Morphology Measuring Toolkit’, Journal of Open Source Software, 4(43), p. 1807. doi: 10.21105/joss.01807.
 
@@ -82,6 +76,7 @@ BibTeX:
     }
 
 ## Install
+
 You can install `momepy` using Conda from `conda-forge` (recommended):
 
     conda install -c conda-forge momepy
@@ -91,16 +86,18 @@ or from PyPI using `pip`:
     pip install momepy
 
 See the [installation instructions](http://docs.momepy.org/en/latest/install.html) for detailed instructions.
-Momepy depends on the python geospatial stack, which might cause some dependency issues.
+Momepy depends on the Python geospatial stack, which might cause some dependency issues.
 
 ## Contributing to momepy
+
 Contributions of any kind to momepy are more than welcome. That does not mean new code only, but also:
-* improvements to the documentation and user guide,
-* additional tests (ideally filling the gaps in the existing suite),
-* bug reports, or
-* ideas for what could be added or done better.
 
-All contributions should go through our GitHub repository. Bug reports, ideas, or even questions should be raised by opening an issue on the GitHub tracker. Suggestions for changes in code or documentation should be submitted as a pull request. However, if you are not sure what to do, feel free to open an issue. All discussion will then take place on GitHub to keep the development of momepy transparent.
+- improvements to the documentation and user guide,
+- additional tests (ideally filling the gaps in the existing suite),
+- bug reports, or
+- ideas for what could be added or done better.
+
+All contributions should go through our GitHub repository. Bug reports, ideas, or even questions should be raised by opening an issue on the GitHub tracker. Suggestions for changes in code or documentation should be submitted as a pull request. However, if you are not sure what to do, feel free to open an issue. All discussions will then take place on GitHub to keep the development of momepy transparent.
 
 If you decide to contribute to the codebase, ensure that you are using an up-to-date `main` branch. The latest development version will always be there, including the documentation (powered by `sphinx`).
 
@@ -110,9 +107,9 @@ Details are available in the [documentation](https://docs.momepy.org/).
 
 If you have a question regarding momepy, feel free to open an [issue](https://github.com/pysal/momepy/issues/new/choose) or a new [discussion](https://github.com/pysal/momepy/discussions) on GitHub.
 
-## Acknowledgements
+## Acknowledgments
 
-The initial release of momepy was a result of a research of [Urban Design Studies Unit (UDSU)](http://udsu-strath.com) supported by the Axel and Margaret Ax:son Johnson Foundation as a part of “The Urban Form Resilience Project” in partnership with University of Strathclyde in Glasgow, UK. Further development was supported by [Geographic Data Science Lab](https://www.liverpool.ac.uk/geographic-data-science/) of the University of Liverpool wihtin [Urban Grammar AI](https://urbangrammarai.xyz) research project.
+The initial release of momepy was a result of research of [Urban](http://udsu-strath.com) Design Studies Unit (UDSU)](http://udsu-strath.com) supported by the Axel and Margaret Ax:son Johnson Foundation as a part of “The Urban Form Resilience Project” in partnership with the University of Strathclyde in Glasgow, UK. Further development was supported by the [Geographic Data Science Lab](https://www.liverpool.ac.uk/geographic-data-science/) of the University of Liverpool within the [Urban Grammar AI](https://urbangrammarai.xyz) research project.
 
 ---
 Copyright (c) 2018-, Martin Fleischmann and PySAL Developers
diff --git a/docs/index.rst b/docs/index.rst
@@ -68,21 +68,8 @@ Examples
 
 .. code:: py
 
-   coverage = momepy.AreaRatio(tessellation, buildings, left_areas=tessellation.area,
-                               right_areas='area', unique_id='uID')
-   tessellation['CAR'] = coverage.series
+   tessellation['area_simpson'] = momepy.simpson(tessellation.area, contiguity_k3)
 
-.. figure:: https://raw.githubusercontent.com/pysal/momepy/main/docs/_static/example1.png
-   :alt: Coverage Area Ratio
-
-   Coverage Area Ratio
-
-.. code:: py
-
-   area_simpson = momepy.Simpson(tessellation, values='area',
-                                 spatial_weights=sw3,
-                                 unique_id='uID')
-   tessellation['area_simpson'] = area_simpson.series
 
 .. figure:: https://raw.githubusercontent.com/pysal/momepy/main/docs/_static/diversity_22_0.png
    :alt: Local Simpson's diversity of area

diff --git a/docs/user_guide/combined/distribution.ipynb b/docs/user_guide/combined/distribution.ipynb
diff --git a/docs/user_guide/combined/intensity.ipynb b/docs/user_guide/combined/intensity.ipynb
diff --git a/docs/user_guide/data_structure.rst b/docs/user_guide/data_structure.rst
@@ -26,14 +26,13 @@ outputs.
 2. Relational characters
 
    Relational characters are based on relations between two or more
-   ``GeoDataFrames``. Typical example is ``AreaRatio``, which requires
-   a) features to be covered (e.g. land unit) and b) features which are
-   covering them (e.g. buildings).
+   ``GeoDataFrames``. Typical example is ``street_alignment``, which requires
+   a) orientation of streets and b) orientation of buildings.
 
 
 3. Network analysis
 
-   Network analysis (``graph`` module) characters are based on
+   Network analysis characters are based on
    ``networkx.Graph`` and returns ``networkx.Graph`` with additional
    node or edge attributes.
 
@@ -78,38 +77,37 @@ Links between elements
 
 When using more than one morphological element, ``momepy`` needs to
 understand what is the relationship between them. For this, it relies on
-``unique_id`` attributes. It is expected, that every building lies on
+indices of GeoPandas objects. It is expected, that every building lies on
 certain plot or morphological cell, on certain street or within certain
 block. To use ``momepy``, each feature of each layer needs its own
-``unique_id``. Moreover, each feature also needs to bear ``unique_id``
+unique index. Moreover, each feature also needs to bear ``index``
 of related elements. Consider following sample rows of
 ``buildings_gdf``:
 
-=========== ======== ===============
-building_id block_id network_edge_id
-=========== ======== ===============
+====== =========== ==================
+index  block_index network_edge_index
+====== =========== ==================
 1           143      22
 2           143      25
 3           144      25
 4           144      25
 5           144      29
-=========== ======== ===============
+====== =========== ==================
 
-Each building has its own unique ``building_id``, while more building
-share ``block_id`` of block they belong to. In this sense, in
-``blocks_gdf`` each feature would have its own unique ``block_id`` used
+Each building has its own unique ``index``, while more buildings
+share ``block_index`` of block they belong to. In this sense, in
+``blocks_gdf`` each feature would have its own unique ``index`` used
 as a reference for ``buildings_gdf``. In principle, elements on the
-smaller scale contains IDs of elements on the larger - blocks will not
-have building IDs.
+smaller scale contains index information of elements on the larger - blocks will not
+have building index.
 
-Momepy can generate unique ID using ``momepy.unique_id()`` and :doc:`link
-certain types of elements together <elements/links>`
+Momepy can :doc:`link certain types of elements together <elements/links>`
 
-Spatial weights
----------------
+Spatial graphs
+--------------
 
-Unique IDs are also used as an ID within spatial weights matrices.
-Thanks to this, spatial weights generated on morphological tessellation
+Unique indices are also used as an index within spatial graphs.
+Thanks to this, spatial graphs generated on morphological tessellation
 (like Queen contiguity) can be directly used on buildings and vice
 versa. Detailed information on using spatial weights within momepy will
 be :doc:`discussed later <weights/weights>`.

diff --git a/docs/user_guide/elements/blocks.ipynb b/docs/user_guide/elements/blocks.ipynb
diff --git a/docs/user_guide/elements/enclosed.ipynb b/docs/user_guide/elements/enclosed.ipynb
diff --git a/docs/user_guide/elements/links.ipynb b/docs/user_guide/elements/links.ipynb
diff --git a/docs/user_guide/elements/tessellation.ipynb b/docs/user_guide/elements/tessellation.ipynb
diff --git a/docs/user_guide/getting_started.ipynb b/docs/user_guide/getting_started.ipynb
diff --git a/docs/user_guide/graph/centrality.ipynb b/docs/user_guide/graph/centrality.ipynb
diff --git a/docs/user_guide/graph/coins.ipynb b/docs/user_guide/graph/coins.ipynb
diff --git a/docs/user_guide/graph/convert.ipynb b/docs/user_guide/graph/convert.ipynb
diff --git a/docs/user_guide/graph/network.ipynb b/docs/user_guide/graph/network.ipynb
diff --git a/docs/user_guide/simple/dimension.ipynb b/docs/user_guide/simple/dimension.ipynb
diff --git a/docs/user_guide/simple/shape.ipynb b/docs/user_guide/simple/shape.ipynb
diff --git a/docs/user_guide/weights/diversity.ipynb b/docs/user_guide/weights/diversity.ipynb