DOC: add first batch of examples + testing (#611)

* DOC: add first batch of examples + testing * move to separate action * skip those wide frames * Update _diversity.py Co-authored-by: James Gaboardi <[email protected]> * Update _diversity.py Co-authored-by: James Gaboardi <[email protected]> --------- Co-authored-by: James Gaboardi <[email protected]>
pysal · Jun 17, 2024 · a838630 · a838630
1 parent 51e561c
commit a838630
Show file tree

Hide file tree

Showing 9 changed files with 635 additions and 49 deletions.
diff --git a/.github/workflows/test_docstrings.yaml b/.github/workflows/test_docstrings.yaml
@@ -0,0 +1,41 @@
+name: Test docstrings
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+      branches:
+        - "*"
+  schedule:
+    - cron: "0 0 * * 1,4"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Manual docstring test
+        default: test
+        required: false
+
+
+jobs:
+  Test:
+    name: "Test dosctrings"
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup micromamba
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: ci/envs/312-latest.yaml
+
+      - name: Install momepy
+        run: pip install .
+
+      - name: Test docstrings
+        run: |
+          pytest -v --color=yes --doctest-only momepy/functional
+
diff --git a/.github/workflows/test_user_guide.yaml b/.github/workflows/test_user_guide.yaml
@@ -37,4 +37,5 @@ jobs:
 
       - name: Test user guide
         run: |
-          ci/envs/test_user_guide.sh
+          ci/envs/test_user_guide.sh
+
diff --git a/ci/envs/312-latest.yaml b/ci/envs/312-latest.yaml
@@ -30,6 +30,7 @@ dependencies:
   - geopy
   - ipywidgets
   - Iprogress
+  - pytest-doctestplus
   - pip
   - pip:
     - git+https://github.com/geopandas/geopandas.git

diff --git a/docs/api.rst b/docs/api.rst
@@ -164,6 +164,7 @@ A set of functions for the analysis of connectivity and configuration of street
    mean_nodes
    meshedness
    node_degree
+   node_density
    proportion
    straightness_centrality
    subgraph

diff --git a/momepy/conftest.py b/momepy/conftest.py
@@ -0,0 +1,10 @@
+import geopandas
+import pytest
+
+import momepy
+
+
+@pytest.fixture(autouse=True)
+def add_momepy_and_geopandas(doctest_namespace):
+    doctest_namespace["momepy"] = momepy
+    doctest_namespace["geopandas"] = geopandas
diff --git a/momepy/functional/_dimension.py b/momepy/functional/_dimension.py
@@ -48,6 +48,19 @@ def volume(
     -------
     NDArray[np.float64] | Series
         array of a type depending on the input
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> area = pd.Series([100, 30, 40, 75, 230])
+    >>> height = pd.Series([22, 6.5, 12, 9, 4.5])
+    >>> momepy.volume(area, height)
+    0    2200.0
+    1     195.0
+    2     480.0
+    3     675.0
+    4    1035.0
+    dtype: float64
     """
     return area * height
 
@@ -81,6 +94,30 @@ def floor_area(
     -------
     NDArray[np.float64] | Series
         array of a type depending on the input
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> area = pd.Series([100, 30, 40, 75, 230])
+    >>> height = pd.Series([22, 6.5, 12, 9, 4.5])
+    >>> momepy.floor_area(area, height)
+    0    700.0
+    1     60.0
+    2    160.0
+    3    225.0
+    4    230.0
+    dtype: float64
+
+    If you know average height of floors per each building, you can pass it directly:
+
+    >>> floor_height = pd.Series([3.2, 3, 4, 3, 4.5])
+    >>> momepy.floor_area(area, height, floor_height=floor_height)
+    0    600.0
+    1     60.0
+    2    120.0
+    3    225.0
+    4    230.0
+    dtype: float64
     """
     return area * (height // floor_height)
 
@@ -205,8 +242,53 @@ def weighted_character(
 
     Examples
     --------
-    >>> res = mm.weighted_character(buildings_df['height'],
-    ...                     buildings_df.geometry.area, graph)
+    Area-weighted elongation within 5 nearest neighbors:
+
+    >>> from libpysal import graph
+    >>> path = momepy.datasets.get_path("bubenec")
+    >>> buildings = geopandas.read_file(path, layer="buildings")
+    >>> buildings.head()
+       uID                                           geometry
+    0    1  POLYGON ((1603599.221 6464369.816, 1603602.984...
+    1    2  POLYGON ((1603042.88 6464261.498, 1603038.961 ...
+    2    3  POLYGON ((1603044.65 6464178.035, 1603049.192 ...
+    3    4  POLYGON ((1603036.557 6464141.467, 1603036.969...
+    4    5  POLYGON ((1603082.387 6464142.022, 1603081.574...
+
+    Measure elongation (or anything else):
+
+    >>> elongation = momepy.elongation(buildings)
+    >>> elongation.head()
+    0    0.908235
+    1    0.581317
+    2    0.726515
+    3    0.838843
+    4    0.727297
+    Name: elongation, dtype: float64
+
+    Define spatial graph:
+
+    >>> knn5 = graph.Graph.build_knn(buildings.centroid, k=5)
+    >>> knn5
+    <Graph of 144 nodes and 720 nonzero edges indexed by
+     [0, 1, 2, 3, 4, ...]>
+
+    Measure the area-weighted character:
+
+    >>> momepy.weighted_character(elongation, buildings.area, knn5)
+    focal
+    0      0.808188
+    1      0.817300
+    2      0.627588
+    3      0.794766
+    4      0.806400
+            ...
+    139    0.780764
+    140    0.875046
+    141    0.753670
+    142    0.440009
+    143    0.901127
+    Name: sum, Length: 144, dtype: float64
     """
 
     stats = graph.describe(y * area, statistics=["sum"])["sum"]
@@ -254,10 +336,41 @@ def street_profile(
 
     Examples
     --------
-    >>> street_prof = momepy.street_profile(streets_df,
-    ...                 buildings_df, height=buildings_df['height'])
-    >>> streets_df['width'] = street_prof['width']
-    >>> streets_df['deviations'] = street_prof['width_deviation']
+    >>> path = momepy.datasets.get_path("bubenec")
+    >>> buildings = geopandas.read_file(path, layer="buildings")
+    >>> streets = geopandas.read_file(path, layer="streets")
+    >>> streets.head()
+                                                geometry
+    0  LINESTRING (1603585.64 6464428.774, 1603413.20...
+    1  LINESTRING (1603268.502 6464060.781, 1603296.8...
+    2  LINESTRING (1603607.303 6464181.853, 1603592.8...
+    3  LINESTRING (1603678.97 6464477.215, 1603675.68...
+    4  LINESTRING (1603537.194 6464558.112, 1603557.6...
+
+    >>> result = momepy.street_profile(streets, buildings)
+    >>> result.head()
+           width  openness  width_deviation
+    0  47.905964  0.946429         0.020420
+    1  42.418068  0.615385         2.644521
+    2  32.131831  0.608696         2.864438
+    3  50.000000  1.000000              NaN
+    4  50.000000  1.000000              NaN
+
+    If you know height of each building, you can pass that along to get back
+    more information:
+
+    >>> import numpy as np
+    >>> import pandas as pd
+    >>> rng = np.random.default_rng(seed=42)
+    >>> height = pd.Series(rng.integers(low=9, high=30, size=len(buildings)))
+    >>> result = momepy.street_profile(streets, buildings, height=height)
+    >>> result.head()
+           width  openness  width_deviation     height  height_deviation  hw_ratio
+    0  47.905964  0.946429         0.020420  12.666667          4.618802  0.264407
+    1  42.418068  0.615385         2.644521  21.500000          6.467869  0.506859
+    2  32.131831  0.608696         2.864438  17.555556          4.901647  0.546360
+    3  50.000000  1.000000              NaN        NaN               NaN       NaN
+    4  50.000000  1.000000              NaN        NaN               NaN       NaN
     """
 
     # filter relevant buildings and streets