# GigaSpatial

Acquires published geospatial datasets into a data store you control, loads them for a source, and processes them. A generator maps a dataset onto points of interest or zones. The result is a view: those places with attributes from the datasets attached. That mapping is one use of the data, not the purpose of the library.

Install with `pip install giga-spatial`. Import `gigaspatial`.

A handler is a dataset published as files. A fetcher is a dataset served as a query. A source is the place you load for, or an explicit list of stored files. A data store is where a handler keeps its files. `LocalDataStore` is the default.

# Tutorial

This tutorial builds H3 cells for Rwanda and attaches WorldPop population to each cell. The result is a view.

The first run downloads the country's population raster into the data store. That can take a few minutes. Later runs read the stored files. WorldPop does not need an API key.

```python
from gigaspatial import H3ViewGenerator

zones = H3ViewGenerator(source="RWA", resolution=6)
view = zones.map_wp_pop(country="RWA")
print(view.head())
```

`source` is the country the cells cover. `resolution=6` is the H3 size: about 36 km² per cell. `map_wp_pop` loads the WorldPop raster for that country and sums it onto the cells. `view` is a table of cells with a `population` column and a geometry.

`S2ViewGenerator` and `MercatorViewGenerator` follow the same pattern: construct them with a country, then call `map_wp_pop`.

A handler acquired the WorldPop files and stored them. The generator mapped that dataset onto zones. The view is those zones with population attached. That attachment is enrichment.

# Datasets

A dataset is a named product the library can acquire, such as WorldPop population or Google Open Buildings.

## Handler

A handler is a dataset published as files. It keeps those files in a data store and loads them for a source.

A source is the place you load for, or an explicit list of stored files. A place is a country, a geometry, points, or a frame.

```python
from gigaspatial import GHSLDataHandler

population = GHSLDataHandler(product="GHS_POP", year=2020, resolution=1000)
frame = population.load_into_dataframe("RWA")
```

The first call downloads the tiles that cover Rwanda. `load_data` and `load_into_dataframe` take the source as the first argument.

`crop_to_source=True` cuts the loaded data to that source. A path source is not cropped. A country source is not cropped when the dataset is already one file for that country. An unknown keyword raises `TypeError`.

```python
frame = population.load_into_dataframe("RWA", crop_to_source=True)
```

## Fetcher

A fetcher is a dataset served as a query, from an API or a database. It returns records. It does not store the dataset as files.

```python
from gigaspatial import OSMLocationFetcher

clinics = OSMLocationFetcher(country="RWA", location_types=["clinic"]).fetch_locations()
```

`MLabFetcher` queries M-Lab speed tests in BigQuery.

## Data store

A data store is where a handler keeps its files. `LocalDataStore` is the default. It may also be remote. A client, such as `BigQueryClient`, queries a database and is not a data store.

Pass `data_store=` when you construct a handler or a generator to choose the store.

# Where to read more

- Tutorial: https://unicef.github.io/giga-spatial/latest/getting-started/quickstart/
- Datasets: https://unicef.github.io/giga-spatial/latest/getting-started/datasets/
- API reference: https://unicef.github.io/giga-spatial/latest/api/
- Handler base: https://unicef.github.io/giga-spatial/latest/api/handler-base/
- Source: https://github.com/unicef/giga-spatial
