Tutorial

LatLongHelper Tutorial

This tutorial demonstrates how to use the three functions provided by LatLongHelper:

lat_long_binning() — bins latitude and longitude into grid cells
lat_long_distance() — calculates great-circle distance (km)
plot_binned_lat_long() — visualizes spatial density as a heatmap

Import functions

from latlonghelper import lat_long_binning
from latlonghelper import lat_long_distance
from latlonghelper import plot_binned_lat_long

Sample dataset (Vancouver / UBC)

import pandas as pd

points = pd.DataFrame(
    {
        "name": [
            "UBC",
            "UBC Library",
            "Downtown Vancouver",
            "Kitsilano",
            "Burnaby",
            "Richmond",
            "North Vancouver",
            "Surrey",
            "New Westminster",
            "Coquitlam",
            "Port Moody"
        ],
        "latitude": [
            49.2606,
            49.2620,
            49.2827,
            49.2685,
            49.2488,
            49.1666,
            49.3200,
            49.1044,
            49.2057,
            49.2838,
            49.2850
        ],
        "longitude": [
            -123.2460,
            -123.2480,
            -123.1207,
            -123.1686,
            -122.9805,
            -123.1336,
            -123.0720,
            -122.8011,
            -122.9110,
            -122.7932,
            -122.8326
        ]
    }
)

points

1. Binning coordinates with `lat_long_binning`

lat_long_binning(latitude, longitude) assigns each coordinate to a latitude–longitude grid cell.

Example A: Bin a single coordinate

lat_long_binning(49.2593, -123.2475)

Example B: Bin all points (default grid size)

bins_default = []

for i in range(len(points)):
    lat = points.loc[i, "latitude"]
    lon = points.loc[i, "longitude"]
    bins_default.append(lat_long_binning(lat, lon))

points["bin_default"] = bins_default
points[["name", "bin_default"]]

Example C: Bin all points using a 0.05° grid

bins_005 = []

for i in range(len(points)):
    lat = points.loc[i, "latitude"]
    lon = points.loc[i, "longitude"]
    bins_005.append(
        lat_long_binning(lat, lon, grid_size_latitude=0.05, grid_size_longitude=0.05)
    )

points["bin_005"] = bins_005
points[["name", "bin_005"]]

2. Distance calculation with `lat_long_distance`

lat_long_distance(lat1, lon1, lat2, lon2) returns the distance in kilometers.

Example A: Distance from UBC to Downtown Vancouver

ubc = points[points["name"] == "UBC"].iloc[0]
dt = points[points["name"] == "Downtown Vancouver"].iloc[0]

lat_long_distance(
    ubc["latitude"], ubc["longitude"],
    dt["latitude"], dt["longitude"]
)

Example B: Distance from UBC to all locations

distances = []

for i in range(len(points)):
    lat = points.loc[i, "latitude"]
    lon = points.loc[i, "longitude"]
    distances.append(
        lat_long_distance(ubc["latitude"], ubc["longitude"], lat, lon)
    )

points["distance_from_ubc_km"] = distances
points[["name", "distance_from_ubc_km"]].sort_values("distance_from_ubc_km")

3. Visualizing binned data with `plot_binned_lat_long`

import matplotlib.pyplot as plt

binned_list = points["bin_005"].tolist()

ax = plot_binned_lat_long(binned_list, width=10, height=6)
plt.show()

End-to-end workflow

bins = []
for i in range(len(points)):
    lat = points.loc[i, "latitude"]
    lon = points.loc[i, "longitude"]
    bins.append(lat_long_binning(lat, lon, 0.05, 0.05))

points["bin"] = bins
points["bin"].value_counts()

ax = plot_binned_lat_long(points["bin"].tolist())
plt.show()

distances = []
for i in range(len(points)):
    lat = points.loc[i, "latitude"]
    lon = points.loc[i, "longitude"]
    distances.append(
        lat_long_distance(ubc["latitude"], ubc["longitude"], lat, lon)
    )

points["distance_from_ubc_km"] = distances
points[["name", "bin", "distance_from_ubc_km"]]

--- title: "Tutorial" format: html: toc: true toc-depth: 3 code-fold: false code-tools: true execute: enabled: false --- # LatLongHelper Tutorial This tutorial demonstrates how to use the three functions provided by **LatLongHelper**: - `lat_long_binning()` — bins latitude and longitude into grid cells\ - `lat_long_distance()` — calculates great-circle distance (km)\ - `plot_binned_lat_long()` — visualizes spatial density as a heatmap ## Import functions ```{python} from latlonghelper import lat_long_binning from latlonghelper import lat_long_distance from latlonghelper import plot_binned_lat_long ``` ## Sample dataset (Vancouver / UBC) ```{python} import pandas as pd points = pd.DataFrame( { "name": [ "UBC", "UBC Library", "Downtown Vancouver", "Kitsilano", "Burnaby", "Richmond", "North Vancouver", "Surrey", "New Westminster", "Coquitlam", "Port Moody" ], "latitude": [ 49.2606, 49.2620, 49.2827, 49.2685, 49.2488, 49.1666, 49.3200, 49.1044, 49.2057, 49.2838, 49.2850 ], "longitude": [ -123.2460, -123.2480, -123.1207, -123.1686, -122.9805, -123.1336, -123.0720, -122.8011, -122.9110, -122.7932, -122.8326 ] } ) points ``` # 1. Binning coordinates with `lat_long_binning` `lat_long_binning(latitude, longitude)` assigns each coordinate to a latitude–longitude grid cell. ## Example A: Bin a single coordinate ```{python} lat_long_binning(49.2593, -123.2475) ``` ## Example B: Bin all points (default grid size) ```{python} bins_default = [] for i in range(len(points)): lat = points.loc[i, "latitude"] lon = points.loc[i, "longitude"] bins_default.append(lat_long_binning(lat, lon)) points["bin_default"] = bins_default points[["name", "bin_default"]] ``` ## Example C: Bin all points using a 0.05° grid ```{python} bins_005 = [] for i in range(len(points)): lat = points.loc[i, "latitude"] lon = points.loc[i, "longitude"] bins_005.append( lat_long_binning(lat, lon, grid_size_latitude=0.05, grid_size_longitude=0.05) ) points["bin_005"] = bins_005 points[["name", "bin_005"]] ``` # 2. Distance calculation with `lat_long_distance` `lat_long_distance(lat1, lon1, lat2, lon2)` returns the distance in kilometers. ## Example A: Distance from UBC to Downtown Vancouver ```{python} ubc = points[points["name"] == "UBC"].iloc[0] dt = points[points["name"] == "Downtown Vancouver"].iloc[0] lat_long_distance( ubc["latitude"], ubc["longitude"], dt["latitude"], dt["longitude"] ) ``` ## Example B: Distance from UBC to all locations ```{python} distances = [] for i in range(len(points)): lat = points.loc[i, "latitude"] lon = points.loc[i, "longitude"] distances.append( lat_long_distance(ubc["latitude"], ubc["longitude"], lat, lon) ) points["distance_from_ubc_km"] = distances points[["name", "distance_from_ubc_km"]].sort_values("distance_from_ubc_km") ``` # 3. Visualizing binned data with `plot_binned_lat_long` ```{python} import matplotlib.pyplot as plt binned_list = points["bin_005"].tolist() ax = plot_binned_lat_long(binned_list, width=10, height=6) plt.show() ``` ![](../images/Figure_1.png) # End-to-end workflow ```{python} bins = [] for i in range(len(points)): lat = points.loc[i, "latitude"] lon = points.loc[i, "longitude"] bins.append(lat_long_binning(lat, lon, 0.05, 0.05)) points["bin"] = bins points["bin"].value_counts() ``` ```{python} ax = plot_binned_lat_long(points["bin"].tolist()) plt.show() ``` ```{python} distances = [] for i in range(len(points)): lat = points.loc[i, "latitude"] lon = points.loc[i, "longitude"] distances.append( lat_long_distance(ubc["latitude"], ubc["longitude"], lat, lon) ) points["distance_from_ubc_km"] = distances points[["name", "bin", "distance_from_ubc_km"]] ```