pyautark 0.1.0a1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyautark-0.1.0a1/.gitignore +231 -0
- pyautark-0.1.0a1/PKG-INFO +269 -0
- pyautark-0.1.0a1/README.md +231 -0
- pyautark-0.1.0a1/pyautark/__init__.py +98 -0
- pyautark-0.1.0a1/pyautark/_cli.py +64 -0
- pyautark-0.1.0a1/pyautark/_serialise.py +64 -0
- pyautark-0.1.0a1/pyautark/data.py +376 -0
- pyautark-0.1.0a1/pyautark/display.py +287 -0
- pyautark-0.1.0a1/pyautark/encodings.py +100 -0
- pyautark-0.1.0a1/pyautark/links.py +19 -0
- pyautark-0.1.0a1/pyautark/selections.py +25 -0
- pyautark-0.1.0a1/pyautark/spec.py +214 -0
- pyautark-0.1.0a1/pyautark/static/autark-widget.js +47907 -0
- pyautark-0.1.0a1/pyautark/static/duckdb-browser-eh.worker.js +14 -0
- pyautark-0.1.0a1/pyautark/static/duckdb-browser-mvp.worker.js +14 -0
- pyautark-0.1.0a1/pyautark/static/duckdb-eh.wasm +4 -0
- pyautark-0.1.0a1/pyautark/static/duckdb-mvp.wasm +4 -0
- pyautark-0.1.0a1/pyautark/transforms.py +281 -0
- pyautark-0.1.0a1/pyautark/views.py +421 -0
- pyautark-0.1.0a1/pyautark/widget.py +104 -0
- pyautark-0.1.0a1/pyproject.toml +76 -0
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
.venv*
|
|
2
|
+
._*
|
|
3
|
+
*._*
|
|
4
|
+
.DS_Store
|
|
5
|
+
|
|
6
|
+
node_modules/
|
|
7
|
+
dist/
|
|
8
|
+
test-results/
|
|
9
|
+
playwright-report/
|
|
10
|
+
npm-debug.log*
|
|
11
|
+
|
|
12
|
+
# Byte-compiled / optimized / DLL files
|
|
13
|
+
__pycache__/
|
|
14
|
+
*.py[codz]
|
|
15
|
+
*$py.class
|
|
16
|
+
|
|
17
|
+
# C extensions
|
|
18
|
+
*.so
|
|
19
|
+
|
|
20
|
+
# Distribution / packaging
|
|
21
|
+
.Python
|
|
22
|
+
build/
|
|
23
|
+
develop-eggs/
|
|
24
|
+
dist/
|
|
25
|
+
downloads/
|
|
26
|
+
eggs/
|
|
27
|
+
.eggs/
|
|
28
|
+
lib/
|
|
29
|
+
lib64/
|
|
30
|
+
parts/
|
|
31
|
+
sdist/
|
|
32
|
+
var/
|
|
33
|
+
wheels/
|
|
34
|
+
share/python-wheels/
|
|
35
|
+
*.egg-info/
|
|
36
|
+
.installed.cfg
|
|
37
|
+
*.egg
|
|
38
|
+
MANIFEST
|
|
39
|
+
|
|
40
|
+
# PyInstaller
|
|
41
|
+
# Usually these files are written by a python script from a template
|
|
42
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
43
|
+
*.manifest
|
|
44
|
+
*.spec
|
|
45
|
+
|
|
46
|
+
# Installer logs
|
|
47
|
+
pip-log.txt
|
|
48
|
+
pip-delete-this-directory.txt
|
|
49
|
+
|
|
50
|
+
# Unit test / coverage reports
|
|
51
|
+
htmlcov/
|
|
52
|
+
.tox/
|
|
53
|
+
.nox/
|
|
54
|
+
.coverage
|
|
55
|
+
.coverage.*
|
|
56
|
+
.cache
|
|
57
|
+
nosetests.xml
|
|
58
|
+
coverage.xml
|
|
59
|
+
*.cover
|
|
60
|
+
*.py.cover
|
|
61
|
+
.hypothesis/
|
|
62
|
+
.pytest_cache/
|
|
63
|
+
cover/
|
|
64
|
+
|
|
65
|
+
# Translations
|
|
66
|
+
*.mo
|
|
67
|
+
*.pot
|
|
68
|
+
|
|
69
|
+
# Django stuff:
|
|
70
|
+
*.log
|
|
71
|
+
local_settings.py
|
|
72
|
+
db.sqlite3
|
|
73
|
+
db.sqlite3-journal
|
|
74
|
+
|
|
75
|
+
# Flask stuff:
|
|
76
|
+
instance/
|
|
77
|
+
.webassets-cache
|
|
78
|
+
|
|
79
|
+
# Scrapy stuff:
|
|
80
|
+
.scrapy
|
|
81
|
+
|
|
82
|
+
# Sphinx documentation
|
|
83
|
+
docs/_build/
|
|
84
|
+
|
|
85
|
+
# PyBuilder
|
|
86
|
+
.pybuilder/
|
|
87
|
+
target/
|
|
88
|
+
|
|
89
|
+
# Jupyter Notebook
|
|
90
|
+
.ipynb_checkpoints
|
|
91
|
+
|
|
92
|
+
# IPython
|
|
93
|
+
profile_default/
|
|
94
|
+
ipython_config.py
|
|
95
|
+
|
|
96
|
+
# pyenv
|
|
97
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
98
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
99
|
+
# .python-version
|
|
100
|
+
|
|
101
|
+
# pipenv
|
|
102
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
103
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
104
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
105
|
+
# install all needed dependencies.
|
|
106
|
+
# Pipfile.lock
|
|
107
|
+
|
|
108
|
+
# UV
|
|
109
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
110
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
111
|
+
# commonly ignored for libraries.
|
|
112
|
+
# uv.lock
|
|
113
|
+
|
|
114
|
+
# poetry
|
|
115
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
116
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
117
|
+
# commonly ignored for libraries.
|
|
118
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
119
|
+
# poetry.lock
|
|
120
|
+
# poetry.toml
|
|
121
|
+
|
|
122
|
+
# pdm
|
|
123
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
124
|
+
# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
|
|
125
|
+
# https://pdm-project.org/en/latest/usage/project/#working-with-version-control
|
|
126
|
+
# pdm.lock
|
|
127
|
+
# pdm.toml
|
|
128
|
+
.pdm-python
|
|
129
|
+
.pdm-build/
|
|
130
|
+
|
|
131
|
+
# pixi
|
|
132
|
+
# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
|
|
133
|
+
# pixi.lock
|
|
134
|
+
# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
|
|
135
|
+
# in the .venv directory. It is recommended not to include this directory in version control.
|
|
136
|
+
.pixi
|
|
137
|
+
|
|
138
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
139
|
+
__pypackages__/
|
|
140
|
+
|
|
141
|
+
# Celery stuff
|
|
142
|
+
celerybeat-schedule
|
|
143
|
+
celerybeat.pid
|
|
144
|
+
|
|
145
|
+
# Redis
|
|
146
|
+
*.rdb
|
|
147
|
+
*.aof
|
|
148
|
+
*.pid
|
|
149
|
+
|
|
150
|
+
# RabbitMQ
|
|
151
|
+
mnesia/
|
|
152
|
+
rabbitmq/
|
|
153
|
+
rabbitmq-data/
|
|
154
|
+
|
|
155
|
+
# ActiveMQ
|
|
156
|
+
activemq-data/
|
|
157
|
+
|
|
158
|
+
# SageMath parsed files
|
|
159
|
+
*.sage.py
|
|
160
|
+
|
|
161
|
+
# Environments
|
|
162
|
+
.env
|
|
163
|
+
.envrc
|
|
164
|
+
.venv
|
|
165
|
+
env/
|
|
166
|
+
venv/
|
|
167
|
+
ENV/
|
|
168
|
+
env.bak/
|
|
169
|
+
venv.bak/
|
|
170
|
+
|
|
171
|
+
# Spyder project settings
|
|
172
|
+
.spyderproject
|
|
173
|
+
.spyproject
|
|
174
|
+
|
|
175
|
+
# Rope project settings
|
|
176
|
+
.ropeproject
|
|
177
|
+
|
|
178
|
+
# mkdocs documentation
|
|
179
|
+
/site
|
|
180
|
+
|
|
181
|
+
# mypy
|
|
182
|
+
.mypy_cache/
|
|
183
|
+
.dmypy.json
|
|
184
|
+
dmypy.json
|
|
185
|
+
|
|
186
|
+
# Pyre type checker
|
|
187
|
+
.pyre/
|
|
188
|
+
|
|
189
|
+
# pytype static type analyzer
|
|
190
|
+
.pytype/
|
|
191
|
+
|
|
192
|
+
# Cython debug symbols
|
|
193
|
+
cython_debug/
|
|
194
|
+
|
|
195
|
+
# PyCharm
|
|
196
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
197
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
198
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
199
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
200
|
+
# .idea/
|
|
201
|
+
|
|
202
|
+
# Abstra
|
|
203
|
+
# Abstra is an AI-powered process automation framework.
|
|
204
|
+
# Ignore directories containing user credentials, local state, and settings.
|
|
205
|
+
# Learn more at https://abstra.io/docs
|
|
206
|
+
.abstra/
|
|
207
|
+
|
|
208
|
+
# Visual Studio Code
|
|
209
|
+
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
|
|
210
|
+
# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
|
|
211
|
+
# and can be added to the global gitignore or merged into this file. However, if you prefer,
|
|
212
|
+
# you could uncomment the following to ignore the entire vscode folder
|
|
213
|
+
# .vscode/
|
|
214
|
+
# Temporary file for partial code execution
|
|
215
|
+
tempCodeRunnerFile.py
|
|
216
|
+
|
|
217
|
+
# Ruff stuff:
|
|
218
|
+
.ruff_cache/
|
|
219
|
+
|
|
220
|
+
# PyPI configuration file
|
|
221
|
+
.pypirc
|
|
222
|
+
|
|
223
|
+
# Marimo
|
|
224
|
+
marimo/_static/
|
|
225
|
+
marimo/_lsp/
|
|
226
|
+
__marimo__/
|
|
227
|
+
|
|
228
|
+
# Streamlit
|
|
229
|
+
.streamlit/secrets.toml
|
|
230
|
+
tests/.specs/
|
|
231
|
+
tests/results/
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pyautark
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Declarative Python API for urban visual analytics (maps, plots, spatial joins) rendered with WebGPU and DuckDB-WASM
|
|
5
|
+
Project-URL: Homepage, https://github.com/urban-toolkit/pyautark
|
|
6
|
+
Project-URL: Repository, https://github.com/urban-toolkit/pyautark
|
|
7
|
+
Project-URL: Issues, https://github.com/urban-toolkit/pyautark/issues
|
|
8
|
+
Author: Urban Toolkit
|
|
9
|
+
License: MIT
|
|
10
|
+
Keywords: declarative,duckdb,gis,jupyter,maps,urban,visualization,webgpu
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Framework :: Jupyter
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Provides-Extra: desktop
|
|
23
|
+
Requires-Dist: pywebview>=5.0; extra == 'desktop'
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: anywidget>=0.9; extra == 'dev'
|
|
26
|
+
Requires-Dist: jsonschema>=4.0; extra == 'dev'
|
|
27
|
+
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
28
|
+
Requires-Dist: nbclient>=0.7; extra == 'dev'
|
|
29
|
+
Requires-Dist: nbformat>=5.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: pywebview>=5.0; extra == 'dev'
|
|
31
|
+
Provides-Extra: test
|
|
32
|
+
Requires-Dist: jsonschema>=4.0; extra == 'test'
|
|
33
|
+
Provides-Extra: validation
|
|
34
|
+
Requires-Dist: jsonschema>=4.0; extra == 'validation'
|
|
35
|
+
Provides-Extra: widget
|
|
36
|
+
Requires-Dist: anywidget>=0.9; extra == 'widget'
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
# Autark Python API
|
|
40
|
+
|
|
41
|
+
Declarative Python API for creating urban visual analytics views. You describe the data, the tables derived from it, the maps and the plots with Python objects. Each object writes its part of an **UrbanSpec**, the JSON specification of [autk-grammar](https://github.com/urban-toolkit/autk-grammar), and a bundled browser runtime runs that spec with the Autark modules.
|
|
42
|
+
|
|
43
|
+
## Quick Example
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import pyautark as ak
|
|
47
|
+
|
|
48
|
+
# Load GeoJSON data
|
|
49
|
+
neighborhoods = ak.GeoJSON(
|
|
50
|
+
"neighborhoods",
|
|
51
|
+
url="/data/neighborhoods.geojson",
|
|
52
|
+
coordinate_format="EPSG:4326",
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
# Create a map with styled layers
|
|
56
|
+
spec = ak.Spec(
|
|
57
|
+
metadata=ak.Metadata(title="Neighborhood Map"),
|
|
58
|
+
data=[neighborhoods],
|
|
59
|
+
views=[
|
|
60
|
+
ak.Map(
|
|
61
|
+
camera=ak.Camera(zoom=12),
|
|
62
|
+
layers=[
|
|
63
|
+
ak.Layer(neighborhoods)
|
|
64
|
+
.style(color="#3498db", opacity=0.7)
|
|
65
|
+
]
|
|
66
|
+
)
|
|
67
|
+
]
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
# The UrbanSpec, as plain Python
|
|
71
|
+
spec.to_dict()
|
|
72
|
+
|
|
73
|
+
# Export
|
|
74
|
+
spec.save_json("spec.json")
|
|
75
|
+
spec.save_html("map.html")
|
|
76
|
+
|
|
77
|
+
# Validate against schema/urbanspec.json (requires pyautark[validation])
|
|
78
|
+
spec.validate()
|
|
79
|
+
|
|
80
|
+
# Display in Jupyter without any local server (requires pyautark[widget])
|
|
81
|
+
spec.widget()
|
|
82
|
+
|
|
83
|
+
# Open the same bundled runtime in a native window from a Python script
|
|
84
|
+
# (requires: pip install -e ".[desktop]")
|
|
85
|
+
spec.window(height="760px")
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Features
|
|
89
|
+
|
|
90
|
+
- **Declarative specs** - Python objects that serialize as an UrbanSpec, which the browser bundle runs as it is
|
|
91
|
+
- **Data sources** - `GeoJSON`, `CSV` and `JSON` (latitude/longitude or WKT geometry), `OSM` (a place or a `bbox`, from Overpass or a PBF extract) and `GeoTIFF`
|
|
92
|
+
- **Spatial operations** - `SpatialJoin` and `Heatmap`
|
|
93
|
+
- **Compute transforms** - `Compute.gpgpu` (a WGSL function per feature) and `Compute.render` (render-based analysis such as sky exposure)
|
|
94
|
+
- **Interactive visualizations** - `Map`; plots (`Histogram`, `Barchart`, `Scatterplot`, `Table`, `ParallelCoordinates`, `Heatmatrix`, `EventSeries`, `Timeseries`); and linked selections
|
|
95
|
+
- **Jupyter integration** - bundled anywidget rendering
|
|
96
|
+
- **Script window display** - Open the bundled runtime in a native window via pywebview
|
|
97
|
+
- **Selections back in Python** - observe `widget.selections` for brushes
|
|
98
|
+
- **pandas/GeoPandas input** - `GeoJSON.from_dataframe()` / `from_geopandas()`
|
|
99
|
+
- **Standalone HTML export** - No Python runtime required
|
|
100
|
+
|
|
101
|
+
## Installation
|
|
102
|
+
|
|
103
|
+
**Note:** Not yet published to PyPI. Install from source:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
cd autark/python
|
|
107
|
+
pip install -e .
|
|
108
|
+
pip install -e ".[validation]" # Optional: JSON Schema validation
|
|
109
|
+
pip install -e ".[widget]" # Optional: zero-server Jupyter widget (anywidget)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Package builds use Hatch and `hatch-jupyter-builder` to run
|
|
113
|
+
`npm run build:widget` in `autk-runtime` and include
|
|
114
|
+
`autark/static/autark-widget.js` automatically.
|
|
115
|
+
|
|
116
|
+
### Displaying specs in Jupyter
|
|
117
|
+
|
|
118
|
+
`spec.widget()` renders with the runtime bundled inside the Python package. No local server needed; works in Jupyter, JupyterLab, VS Code, and Colab. DuckDB sidecar assets are packaged next to the widget bundle and used when the host exposes sibling files. Data sources must use absolute URLs or inline `values` (in JupyterLab started from a folder, `/files/<path>` URLs also work).
|
|
119
|
+
|
|
120
|
+
Plot selections sync back to the kernel, keyed by plot id (the name of the plot's selection):
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
brush = ak.interval("latitude_brush")
|
|
124
|
+
w = spec.widget()
|
|
125
|
+
w # display; brush the plot, then:
|
|
126
|
+
w.selections # {'latitude_brush': [0, 2]}
|
|
127
|
+
w.observe(lambda change: print(change["new"]), names="selections")
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
DataFrames can be passed directly as inline data:
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
trees = ak.GeoJSON.from_dataframe("trees", df, latitude="lat", longitude="lon")
|
|
134
|
+
neighborhoods = ak.GeoJSON.from_geopandas("neighborhoods", gdf) # reprojects to EPSG:4326
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
A notebook kernel keeps the widget bundle it loaded. After rebuilding the bundle, restart the kernel and reload the page.
|
|
138
|
+
|
|
139
|
+
## Names and rules
|
|
140
|
+
|
|
141
|
+
Python keeps its own words, and each builder writes the UrbanSpec fields:
|
|
142
|
+
|
|
143
|
+
| Python | UrbanSpec |
|
|
144
|
+
|---|---|
|
|
145
|
+
| a source's `name` | `outputTableName` |
|
|
146
|
+
| a source's `url` / `values` | `geojsonFileUrl` / `geojsonObject` (`csvFileUrl`, `csvObject`, `jsonFileUrl`, ...) |
|
|
147
|
+
| `ak.latlng(lat, lon)`, `ak.wkt(col)` | `geometryColumns` |
|
|
148
|
+
| `OSM(area=..., layers=[...])`, `OSM(bbox=...)` | `queryArea`, `autoLoadLayers` |
|
|
149
|
+
| a layer's source (name or object) | `dataRef` |
|
|
150
|
+
| `Layer(id=...)` | `title` |
|
|
151
|
+
| `.encode(color=ak.field(path, scale))` | `getFnv`, `isColorMap`, `colorMapInterpolator`, ... |
|
|
152
|
+
| `.style(color, opacity, strokeColor, width, size)` | `color`, `opacity`, `stroke`, `width`, `pointSize` |
|
|
153
|
+
| `SpatialJoin(root, join)` | a `join` entry of `data`: `dataRef`, `joinDataRef` |
|
|
154
|
+
| `Heatmap(source, output)` | a `heatmap` entry of `data`: `joinDataRef`, `outputTableName` |
|
|
155
|
+
| `Compute.gpgpu(source, variable_mapping, wgsl_body, result_field)` | an entry of `compute`: `dataRef`, `attributes`, `wgslFunction`, `outputColumnName` |
|
|
156
|
+
| `Compute.render(output, ...)` | a `compute` entry with `type: 'render'` |
|
|
157
|
+
| `Map(name=...)`, `Camera` | `map` with `id`, `camera` |
|
|
158
|
+
| `Histogram`, `Barchart`, `Scatterplot`, `Table`, `ParallelCoordinates`, `Heatmatrix`, `EventSeries`, `Timeseries` | `plot` with `mark` `bar`, `scatter`, `table`, `parallel-coordinates`, `heatmatrix`, `linechart` and the matching `transform` |
|
|
159
|
+
| `Link(selection, target)` | `links[]`: the plot that owns the selection, the map and layer that draw `target` |
|
|
160
|
+
|
|
161
|
+
Rules worth knowing:
|
|
162
|
+
|
|
163
|
+
- **The first source sets the workspace.** Autark cuts every later source to the extent of the first one, so a table that lies outside it comes out empty. Put the source that covers the area of interest first.
|
|
164
|
+
- **Workspaces keep areas apart.** `workspace="name"` on a source, a join, a heatmap, a compute pass, a map or a plot puts it in a named workspace, with its own extent; the entries without one share the default workspace. Two areas that must not clip each other go in two workspaces, and each workspace may hold a table of the same name (see `examples/python/osm_layers_workspaces.py`).
|
|
165
|
+
- **A table is drawn from its geometry** (points, lines or polygons); a layer does not say. A collection that mixes types goes in as one source per type.
|
|
166
|
+
- **A plot with a selection takes the selection's name as its id**, which is also the key of `widget.selections`. A link points to a layer by its `id`, and an unnamed map gets `map1`, `map2`, ... when a link needs it.
|
|
167
|
+
- **Joins and heatmaps run before compute passes.** A `SpatialJoin` or `Heatmap` that reads a table a compute pass wrote is refused.
|
|
168
|
+
- **`Compute.gpgpu` without `output` adds its result to the source table** (`properties.compute.<name>`); with `output`, it makes a new table and leaves the source as it was. `Compute.render` always makes a new table.
|
|
169
|
+
- **Links highlight.** Other actions are refused.
|
|
170
|
+
- **Give plots in a grid a `width` and `height`** (pixels) so they fit their cells.
|
|
171
|
+
- **What the grammar has no field for is reported with a `UserWarning` and left out**, for example `strokeWidth`, or sizing or opacity driven by a field.
|
|
172
|
+
- `metadata` (title, ...) is for the page that shows the spec and is not serialized.
|
|
173
|
+
|
|
174
|
+
## Example styles
|
|
175
|
+
|
|
176
|
+
Examples come in two flavors. Both build the same `Spec`; they differ in what
|
|
177
|
+
the script does when run from the command line.
|
|
178
|
+
|
|
179
|
+
**Style A (default) — terse `spec.window()`.** The spec is built at module
|
|
180
|
+
scope and `spec.window()` opens a native window when the script is run. Best
|
|
181
|
+
for small didactic examples; the spec is also importable from a REPL or
|
|
182
|
+
notebook.
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
import pyautark as ak
|
|
186
|
+
|
|
187
|
+
spec = ak.Spec(
|
|
188
|
+
data=[ak.OSM("osm", geocode_area="New York", area="Financial District",
|
|
189
|
+
layers=["roads", "buildings"])],
|
|
190
|
+
views=[ak.Map(layers=[ak.Layer("osm_roads"),
|
|
191
|
+
ak.Layer("osm_buildings")])],
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
if __name__ == "__main__":
|
|
195
|
+
spec.window(height="760px")
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**Style B — CLI flags via `ak.cli(spec)`.** Use this when the example should
|
|
199
|
+
also be runnable from CI to regenerate JSON, validate against the schema, or
|
|
200
|
+
emit standalone HTML without needing the `desktop` extra installed.
|
|
201
|
+
|
|
202
|
+
```python
|
|
203
|
+
import pyautark as ak
|
|
204
|
+
|
|
205
|
+
spec = ak.Spec(...) # same builder
|
|
206
|
+
|
|
207
|
+
if __name__ == "__main__":
|
|
208
|
+
ak.cli(spec)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Resulting CLI:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
python ex.py # opens a window (same as Style A)
|
|
215
|
+
python ex.py --output spec.json # write the UrbanSpec as JSON
|
|
216
|
+
python ex.py --html out.html # write standalone HTML
|
|
217
|
+
python ex.py --validate # validate against schema/urbanspec.json
|
|
218
|
+
python ex.py --json # print JSON to stdout
|
|
219
|
+
python ex.py --height 800px # override window/HTML height
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Action flags suppress the window. `--validate` can be combined with `--output`
|
|
223
|
+
or `--html`.
|
|
224
|
+
|
|
225
|
+
## Documentation
|
|
226
|
+
|
|
227
|
+
- **[examples/](../examples/)** - Working examples
|
|
228
|
+
- [simple_geojson_map.py](../examples/python/simple_geojson_map.py) - Basic map
|
|
229
|
+
- [csv_points_map.py](../examples/python/csv_points_map.py) - CSV points + histogram
|
|
230
|
+
- [spatial_join.py](../examples/python/spatial_join.py) - Spatial join workflow
|
|
231
|
+
- [geopandas_workflow.py](../examples/python/geopandas_workflow.py) - GeoPandas workflow
|
|
232
|
+
- [specs/](../examples/specs/) - the same kind of views as UrbanSpec JSON files
|
|
233
|
+
- The **pyautark tutorial** (https://github.com/ctsilva/pyautark-tutorial): six notebooks, from data formats to GPU computing
|
|
234
|
+
- The UrbanSpec itself: [autk-grammar](https://github.com/urban-toolkit/autk-grammar)
|
|
235
|
+
|
|
236
|
+
## Design
|
|
237
|
+
|
|
238
|
+
The Autark Python API follows the Vega-Lite/Altair pattern:
|
|
239
|
+
|
|
240
|
+
1. Python authors **structured specifications**
|
|
241
|
+
2. Specifications **serialize to an UrbanSpec** (JSON)
|
|
242
|
+
3. The browser bundle **runs the UrbanSpec with `AutkGrammar`** (autk-db, autk-compute, autk-map, autk-plot)
|
|
243
|
+
4. All rendering/compute happens in **WebGPU/DuckDB-WASM**
|
|
244
|
+
|
|
245
|
+
Benefits:
|
|
246
|
+
- Shareable as JSON or HTML
|
|
247
|
+
- Jupyter-friendly
|
|
248
|
+
- LLM/agent-friendly
|
|
249
|
+
- No Python runtime needed for visualization
|
|
250
|
+
- One specification and one engine: the UrbanSpec runs in any autk-grammar host
|
|
251
|
+
|
|
252
|
+
## Testing
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
# Run Python tests
|
|
256
|
+
python -m unittest discover -s tests
|
|
257
|
+
|
|
258
|
+
# Type check (pip install -e ".[dev]")
|
|
259
|
+
python -m mypy
|
|
260
|
+
|
|
261
|
+
# Validate examples
|
|
262
|
+
python ../examples/python/simple_geojson_map.py --validate
|
|
263
|
+
python ../examples/python/csv_points_map.py --validate
|
|
264
|
+
python ../examples/python/spatial_join.py --validate
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## License
|
|
268
|
+
|
|
269
|
+
MIT License
|