Setup testing

.github/workflows/build.yml

@@ -28,8 +28,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.8"]
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.8", "3.9", "3.10"]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  ubuntu-build:
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash -l {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+    env:
+      OS: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: false
+          activate-environment: test-env
+          auto-activate-base: false
+      - name: Install dependencies then test
+        run: |
+          conda install -c conda-forge gdal
+          conda install -c conda-forge pip
+          pip install .[dev]
+          coverage run -m pytest

Tutorials/EXAMPLE_Finding_links_between_pairs.ipynb

@@ -9,6 +9,32 @@
     "For most network analysis we do not consider actual geographic connections - this notebook focuses on how to calculate those direct connections between points and collect the geospatial information"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import Libraries and Define Input Data\n",
+    "\n",
+    "First we'll import the necessary libraries and define the input data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Libraries\n",
+    "\n",
+    "We'll use the following libraries:\n",
+    "\n",
+    "- `os` for setting the working directory\n",
+    "- `pickle` to load the data\n",
+    "- `networkx` to calculate travel times through the graph\n",
+    "- `geopandas` to work with the geospatial data\n",
+    "- `pandas` to work with the data\n",
+    "- `shapely.geometry` to work with the geometry of the data\n",
+    "- `GOSTnets` to apply custom functions to the network"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -21,17 +47,20 @@
     "import geopandas as gpd\n",
     "import pandas as pd\n",
     "\n",
-    "from shapely.geometry import MultiLineString"
+    "from shapely.geometry import MultiLineString\n",
+    "\n",
+    "# import the GOSTnet library\n",
+    "import GOSTnets as gn"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# import the GOSTnet library\n",
-    "import GOSTnets as gn"
+    "### Load Input Data\n",
+    "\n",
+    "We define the path to the Iceland network tutorial data, and load the network graph information.\n",
+    "Then we load the origins and destination data, so that we're ready to calculate travel times between the points."
    ]
   },
   {
@@ -59,6 +88,16 @@
     "in_churches = in_churches.to_crs(rek_grid.crs)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Calculate Shortest Paths Between Loaded Origins and Destinations\n",
+    "\n",
+    "We'll calculate the shortest paths between the loaded origins and destinations.\n",
+    "To do this we first need to snap the origins and destinations to the network, only then can we calculate the shortest paths between them."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -112,7 +151,29 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Calculate line strings connecting all origins to all destinations"
+    "## Calculate line strings connecting all origins to all destinations\n",
+    "\n",
+    "We'll calculate the line strings connecting all origins to all destinations.\n",
+    "For the sake of the example, we'll only calculate the line strings between the first 10 origins and the first 10 destinations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# for the sake of the example we truncate the number of origins and destinations\n",
+    "# to make the computation faster. We will only use the first 10 of each\n",
+    "origins = origins[:10]\n",
+    "destinations = destinations[:10]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Practically we perform this calculation by looping through all origins and destinations and calculating the line string between them."
    ]
   },
   {
@@ -155,6 +216,16 @@
     "        all_res.append([org, dest, MultiLineString(all_edges)])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Write the data to a file\n",
+    "\n",
+    "Finally, we'll write the data to a file.\n",
+    "First we write all connection data to a CSV file."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -166,6 +237,13 @@
     "all_results.to_csv(os.path.join(pth, \"tutorial_outputs\", \"all_OD_links.csv\"))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then we write the connections information out to a CSV file."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -191,13 +269,6 @@
     "    os.path.join(pth, \"tutorial_outputs\", \"OD_links_usage.csv\")\n",
     ")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

Tutorials/EXAMPLE_Fixing_your_road_network.ipynb

@@ -6,9 +6,36 @@
    "source": [
     "# Fixing your road network graph\n",
     "\n",
+    "*Note: This notebook includes processes covered in the [Step 2](Step_2-Clean_Network.ipynb) Tutorial Notebook.*\n",
+    "\n",
     "The following notebook showcases some common practices to inspect the quality of your road-network graph, and possibilities to improve it."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import Libraries and Load Data\n",
+    "\n",
+    "We will start by importing the necessary libraries and loading the data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import Libraries\n",
+    "\n",
+    "We will use the following libraries:\n",
+    "\n",
+    "- `os` to set the working directory and handle file paths\n",
+    "- `networkx` to handle the graph data structure\n",
+    "- `osmnx` to plot the network graph\n",
+    "- `pickle` to load the network data\n",
+    "- `matplotlib` to help plot and format the graph\n",
+    "- `GOSTnets` to access custom GOSTnets functionality"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -18,17 +45,20 @@
     "import os\n",
     "import networkx as nx\n",
     "import osmnx as ox\n",
-    "import pickle as pkl"
+    "import pickle as pkl\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "# import the GOSTnets library\n",
+    "import GOSTnets as gn"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# import the GOSTnets library\n",
-    "import GOSTnets as gn"
+    "### Load Data\n",
+    "\n",
+    "Define the path to the tutorial data and then load the network."
    ]
   },
   {
@@ -44,6 +74,24 @@
     "G = pkl.load(open(os.path.join(data_pth, \"iceland_network_clean.pickle\"), \"rb\"))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Graph processing\n",
+    "\n",
+    "In this notebook the first processing step we take is to load the largest subgraph."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Identify the largest subgraph\n",
+    "\n",
+    "We will start by identifying the largest subgraph in the network."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -75,6 +123,15 @@
     "print(G_largest)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Plot the largest subgraph\n",
+    "\n",
+    "We will then plot the largest subgraph to visualize the network."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -85,8 +142,12 @@
     "G_largest.graph[\"crs\"] = \"epsg:32646\"\n",
     "G_largest.graph[\"name\"] = \"Iceland\"\n",
     "\n",
+    "fig, ax = plt.subplots(figsize=(10, 14))\n",
+    "ax.set_facecolor(\"k\")\n",
+    "ax.set_title(\"Iceland - The Largest Network\")\n",
     "# largest connected subgraph\n",
-    "ox.plot_graph(G_largest, figsize=(10, 14), edge_linewidth=1, node_size=7)"
+    "fig, ax = ox.plot_graph(G_largest, ax=ax, edge_linewidth=1, node_size=7)\n",
+    "plt.show()"
    ]
   },
   {