Skip to content

Commit ccd5a60

Browse files
mapninjapre-commit-ci[bot]mfisher87github-actions[bot]
authored
Updated and organized ipynb examples directory for clarity (#872)
* Add new JGIS documents and examples for spatial data visualization - Created new JGIS files: shapefile.jGIS, test.jGIS, and world.jGIS with various layers and sources. - Added Jupyter notebooks for creating a new JGIS document, exploring data in a map, and opening existing JGIS projects. - Implemented vector styling examples and added raster and GeoJSON layers to demonstrate usage of the JupyterGIS API. - Enhanced documentation with markdown cells to provide context and instructions for users. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add introductory content and explanations for creating a new JGIS document * rename open map doc * push branch to Main * Relocate example jGIS projects, fix data references * Update JupyterLite build for new content locations * Move QGZ project files out of data directory * Remove spaces from filename * Copy nyc data folder for Lite build * Move a missed project file out of `data/` dir * Copy examples excluding unwanted content instead of enumerating all wanted content * Add all example content in RTD build * Pass in only the examples directory as jupyterlite_contents The globstar doesn't work how I expected! <jupyterlite/jupyterlite-sphinx#307> * Re-add jgis.ipynb as test data * Un-nest the examples directory in the content directory The contents of `examples/` should be directly visible at the root of the filesystem in the Lite deployment, not inside an `examples/` directory. * Move all ui-test dependencies into ui-tests/content subdir Use symlinks to any files that also exist in `examples/` and `cp --dereference` when copying into the JupyterLite deployment * Add more test dependency symlinks * Restore previous viewport position to updated examples * Update Playwright Snapshots * Fix broken test.jGIS project file * Update Playwright Snapshots --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Matt Fisher <[email protected]> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent ae02cb7 commit ccd5a60

37 files changed

+625
-229
lines changed

‎.github/workflows/build.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,8 @@ jobs:
285285
working-directory: lite
286286
run: |
287287
set -eux
288-
mkdir -p content && cp ../examples/*.jGIS ../examples/*.qgz ../examples/*.geojson ../examples/*.tif ../examples/*.zip ../examples/*.ipynb ../examples/*.gif ./content
288+
cp --recursive --dereference ../ui-tests/content ./content
289+
find ./content -type d -name ".ipynb_checkpoints" -exec rm -rf {} +
289290
jupyter lite build --contents content --output-dir dist
290291
291292
- name: Upload Lite artifacts

‎docs/conf.py‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,7 @@
3535
language = "en"
3636

3737
jupyterlite_contents = [
38-
"../examples/*.jGIS",
39-
"../examples/*.geojson",
40-
"../examples/*.zip",
41-
"../examples/*.gif",
42-
"../examples/*.geojson",
43-
"../examples/*.tif",
44-
"../examples/*.ipynb",
38+
"../examples",
4539
]
4640
jupyterlite_dir = "."
4741
jupyterlite_config = "jupyter_lite_config.json"

‎examples/01-Create_a_new_JGIS_document.ipynb‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "8dbc9440",
6+
"metadata": {},
7+
"source": [
8+
"## What is \"The Map\" in a Geographic Information System (GIS) context?\n",
9+
"\n",
10+
"In traditional geography, a **map** is a picture that shows the layout of some part of the world — things like roads, rivers, buildings, or population data, all drawn at a certain scale and intended to illustrate or enable something specific.\n",
11+
"\n",
12+
"But in **digital mapping** (or Geographic Information Systems, GIS), a map is much more than just a picture — it's made up of **data** that can be viewed, edited, analyzed, and combined with other data.\n",
13+
"\n",
14+
"In GIS software like **JupyterGIS**, a digital map is actually a **document** that holds:\n",
15+
"\n",
16+
"- **Layers** — These are pieces of data, like roads, rivers, or land use. Each layer represents one kind of thing or phenomenon, in the physical world.\n",
17+
"- **Basemaps** — These are background images, like satellite imagery or street maps, that help give context to your data layers.\n",
18+
"- **Tools** — Things that let you analyze or edit the layers on your map.\n",
19+
"\n",
20+
"---\n",
21+
"\n",
22+
"## Dana Tomlin's Cartographic Model (Simplified)\n",
23+
"\n",
24+
"In his foundational work [GIS & Cartographic Modeling](https://archive.org/details/geographicinform00toml), Dana Tomlin, one of the founders of modern GIS, described the **Cartographic Model** as a way to think of maps not just as images, but as **tools for thinking and analysis**.\n",
25+
"\n",
26+
"In his model:\n",
27+
"> A map is not just a picture of the world, but a **set of layers of data** that can be combined using logic and rules.\n",
28+
"\n",
29+
"In other words, each layer on the map has meaning — and by combining layers in specific ways we can answer questions like:\n",
30+
"- Where is the best place to build a school?\n",
31+
"- Which areas are at risk of flooding?\n",
32+
"- How has a city's land use changed over time?"
33+
]
34+
},
35+
{
36+
"cell_type": "code",
37+
"execution_count": null,
38+
"id": "639b7342-688d-47c6-be9f-d4f7e60b74e7",
39+
"metadata": {
40+
"editable": true,
41+
"slideshow": {
42+
"slide_type": ""
43+
},
44+
"tags": []
45+
},
46+
"outputs": [],
47+
"source": [
48+
"from jupytergis import GISDocument\n",
49+
"\n",
50+
"# Create a new GIS document (a digital map)\n",
51+
"doc = GISDocument(\"local.jGIS\")\n",
52+
"\n",
53+
"# Display the map document in the notebook\n",
54+
"doc"
55+
]
56+
},
57+
{
58+
"cell_type": "markdown",
59+
"id": "1c58c922",
60+
"metadata": {},
61+
"source": [
62+
"### What does this code do?\n",
63+
"\n",
64+
"1. `from jupytergis import GISDocument`\n",
65+
" This line tells Python to load the `GISDocument` module from the `jupytergis` library. Think of the `GISDocument` module as the part of the pre-written JupyterGIS code that creates your digital map container in the notebook.\n",
66+
"\n",
67+
"2. `doc = GISDocument(\"local.jGIS\")`\n",
68+
" This defines a variable called `doc` to store the command that will import the file `local.jGIS` as the `GISDocument`.\n",
69+
" This document is where you'll add your layers (roads, rivers, buildings, etc.) and tools.\n",
70+
"\n",
71+
"3. `doc`\n",
72+
" When you type this in a notebook cell and run it, it runs the module `GISDocument` to create an interactive map in your notebook, using the `local.jGIS` file. You can then later add layers, change the basemap, and do spatial analysis. You *could* use the complete command `GISDocument(\"local.jGIS\")` to run the GISModule, but storing the command in a short variable (like, `doc`) allows you to easily reuse the command, with less text, in your code. \n",
73+
"\n",
74+
"---\n",
75+
"\n",
76+
"### Summary\n",
77+
"\n",
78+
"So far, you've created the **foundation** of your GIS project — a digital **Map Document** that can hold multiple layers and allow you to explore and analyze spatial data.\n",
79+
"\n",
80+
"This is like opening a new document in Word or Google Docs — but instead of writing an essay, you're going to build and explore a map!"
81+
]
82+
}
83+
],
84+
"metadata": {
85+
"kernelspec": {
86+
"display_name": "Python 3 (ipykernel)",
87+
"language": "python",
88+
"name": "python3"
89+
},
90+
"language_info": {
91+
"codemirror_mode": {
92+
"name": "ipython",
93+
"version": 3
94+
},
95+
"file_extension": ".py",
96+
"mimetype": "text/x-python",
97+
"name": "python",
98+
"nbconvert_exporter": "python",
99+
"pygments_lexer": "ipython3",
100+
"version": "3.10.18"
101+
}
102+
},
103+
"nbformat": 4,
104+
"nbformat_minor": 5
105+
}

examples/explore.ipynb renamed to examples/99-Explore_data_in_a_map.ipynb

Lines changed: 68 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,50 @@
33
{
44
"cell_type": "markdown",
55
"id": "c3f4096f-cbd3-43e8-a986-520681f03581",
6-
"metadata": {},
6+
"metadata": {
7+
"editable": true,
8+
"slideshow": {
9+
"slide_type": ""
10+
},
11+
"tags": []
12+
},
713
"source": [
814
"# ESPM 157 - Intro to Spatial Data\n",
915
"\n",
1016
"<https://espm-157.carlboettiger.info/spatial-1>\n",
17+
"\n"
18+
]
19+
},
20+
{
21+
"cell_type": "code",
22+
"execution_count": null,
23+
"id": "0d1dbcb0",
24+
"metadata": {
25+
"editable": true,
26+
"slideshow": {
27+
"slide_type": ""
28+
},
29+
"tags": []
30+
},
31+
"outputs": [],
32+
"source": [
33+
"# Install dependencies:\n",
1134
"\n",
12-
"Install dependencies:\n",
13-
"\n",
14-
"```bash\n",
15-
"micromamba install geopandas ibis-duckdb\n",
16-
"```"
35+
"#!conda install geopandas ibis-framework\n",
36+
"!mamba install geopandas ibis-framework -y"
1737
]
1838
},
1939
{
2040
"cell_type": "code",
2141
"execution_count": null,
2242
"id": "b76ae1f0-334e-41c0-9533-407c879b4ad6",
23-
"metadata": {},
43+
"metadata": {
44+
"editable": true,
45+
"slideshow": {
46+
"slide_type": ""
47+
},
48+
"tags": []
49+
},
2450
"outputs": [],
2551
"source": [
2652
"import ibis\n",
@@ -32,7 +58,13 @@
3258
"cell_type": "code",
3359
"execution_count": null,
3460
"id": "837aa4e0-5eeb-48c1-97ce-3f8706503911",
35-
"metadata": {},
61+
"metadata": {
62+
"editable": true,
63+
"slideshow": {
64+
"slide_type": ""
65+
},
66+
"tags": []
67+
},
3668
"outputs": [],
3769
"source": [
3870
"redlines = con.read_geo(\n",
@@ -44,7 +76,13 @@
4476
"cell_type": "code",
4577
"execution_count": null,
4678
"id": "4d3319fa-b3b4-4931-b073-98b649e41b65",
47-
"metadata": {},
79+
"metadata": {
80+
"editable": true,
81+
"slideshow": {
82+
"slide_type": ""
83+
},
84+
"tags": []
85+
},
4886
"outputs": [],
4987
"source": [
5088
"city = redlines.filter(redlines.city == \"New Haven\")"
@@ -55,7 +93,12 @@
5593
"execution_count": null,
5694
"id": "34f7f4d6-28d6-4716-8e03-ac32c6ae3bb7",
5795
"metadata": {
58-
"scrolled": true
96+
"editable": true,
97+
"scrolled": true,
98+
"slideshow": {
99+
"slide_type": ""
100+
},
101+
"tags": []
59102
},
60103
"outputs": [],
61104
"source": [
@@ -66,7 +109,13 @@
66109
{
67110
"cell_type": "markdown",
68111
"id": "d37a610a-1444-43a3-900f-dfe16a890ab9",
69-
"metadata": {},
112+
"metadata": {
113+
"editable": true,
114+
"slideshow": {
115+
"slide_type": ""
116+
},
117+
"tags": []
118+
},
70119
"source": [
71120
"## OK, but what about spatial context?\n",
72121
"\n",
@@ -77,7 +126,13 @@
77126
"cell_type": "code",
78127
"execution_count": null,
79128
"id": "6e68aaac-dfc0-42d8-a3b9-05fce59524b2",
80-
"metadata": {},
129+
"metadata": {
130+
"editable": true,
131+
"slideshow": {
132+
"slide_type": ""
133+
},
134+
"tags": []
135+
},
81136
"outputs": [],
82137
"source": [
83138
"from jupytergis import explore\n",
@@ -103,7 +158,7 @@
103158
"name": "python",
104159
"nbconvert_exporter": "python",
105160
"pygments_lexer": "ipython3",
106-
"version": "3.12.9"
161+
"version": "3.10.18"
107162
}
108163
},
109164
"nbformat": 4,

0 commit comments

Comments
 (0)