diff --git a/_quarto.yml b/_quarto.yml index 496bae3..a419254 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -28,6 +28,8 @@ website: href: index.qmd - text: "Reference" href: reference/index.qmd + - text: "Tutorial" + href: vignettes/tutorial.qmd - text: "Retrospective" href: retrospective.qmd diff --git a/environment.yml b/environment.yml index 1dbc152..eaa83b0 100644 --- a/environment.yml +++ b/environment.yml @@ -4,5 +4,7 @@ channels: dependencies: - python - ipykernel + - nbformat + - nbclient - pip: - quartodoc diff --git a/pyproject.toml b/pyproject.toml index 80354e6..a1d5ad8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,10 +32,13 @@ classifiers = [ # TODO: add keywords keywords = [] # Package dependencies -dependencies = [ + dependencies = [ "geopy>=2.4.0", # For geocoding (place names <-> coordinates eg: Vancouver, Canada -> (49.2827, -123.1207)) "shapely>=2.0.1", # For geometric objects and operations (eg: points, polygons, etc.) "pandas>=2.0.0", # For dataframe usage in tests/functions + "jupyterlab>=4.0", + "nbformat>=5.10.4", + "ipykernel>=6.25.2", ] [project.urls] diff --git a/vignettes/tutorial.qmd b/vignettes/tutorial.qmd new file mode 100644 index 0000000..620afc0 --- /dev/null +++ b/vignettes/tutorial.qmd @@ -0,0 +1,86 @@ +--- +title: "Geospatial Toolkit Tutorial" +format: + html: + code-fold: false +--- + +## Introduction + +The `geospatial_toolkit` is designed to simplify common geographic data tasks, such as cleaning coordinate strings, calculating distances, and finding antipodes. This tutorial demonstrates a typical workflow using the package. + +## Installation + +To install the package from TestPyPI, run: + +``` bash +pip install -i https://test.pypi.org/simple/ geospatial-toolkit +``` + +## Basic Usage + +First, let's import the necessary functions: + +``` {python} +from geospatial_toolkit import ( + standardize_latlong, + haversine_distance, + get_antipode, + point_to_city +) +``` + +**1. Cleaning Coordinates** + +Often, geospatial data comes in messy string formats. We can use standardize_latlong to convert these into float tuples. + +``` {python} +lat, lon = standardize_latlong("49.2827", "123.1207") +print(f"Cleaned Coordinates: {lat}, {lon}") +``` + +**2. Calculating Distance** + +Now, let's find the distance between our cleaned Vancouver point and the Eiffel Tower in Paris (48.8584, 2.2945). + +``` {python} +paris = (48.8584, 2.2945) +vancouver = (lat, lon) + +distance = haversine_distance(vancouver, paris, unit='km') +print(f"Distance to Paris: {distance:.2f} km") +``` + + +**3. Finding the Antipode** + +What is directly on the opposite side of the world from our Vancouver point? + +``` {python} +anti_lat, anti_lon = get_antipode((lat, lon)) +print(f"Antipode Coordinates: {anti_lat}, {anti_lon}") +``` + + +**4. Identifying the Nearest City** + +Finally, let's see if there is a major city near that antipode point in the ocean. + +``` {python} +import pandas as pd +from shapely.geometry import Polygon + +data = { + 'city_name': ['Vancouver', 'Port-aux-Français'], + 'geometry': [ + Polygon([(-124, 48), (-122, 48), (-122, 50), (-124, 50)]), + Polygon([(69, -50), (71, -50), (71, -48), (69, -48)]) + ] +} +cities_df = pd.DataFrame(data) + +city_info = point_to_city(49.2827, -123.1207, cities_df) + +print(f"Nearest City to Antipode: {city_info}") +``` +