# Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project's documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

▶ Install this skill

**Any agent** -- install with [npx](https://github.com/vercel-labs/skills):

``` bash
npx skills add https://starsimhub.github.io/starsim_data/
```

**Codex / OpenCode**

``` text
Tell the agent:
Fetch the skill file at https://starsimhub.github.io/starsim_data/skill.md and follow the instructions.
```

**Manual** -- download the skill file:

``` bash
curl -O https://starsimhub.github.io/starsim_data/skill.md
```

Or browse the [`SKILL.md`](skill.md) file.

### SKILL.md

``` gd-skills-raw
```

```` markdown
---
name: starsim_data
description: >-
  Demographic data and contact matrices for disease modeling with Starsim. Use
  when writing Python code that uses the starsim_data package.
license: MIT AND GPL-3.0-only AND CC-BY-3.0-IGO AND CC-BY-4.0
compatibility: Requires Python >=3.11.
---

# Starsim Data

Demographic data and contact matrices for disease modeling with Starsim

## Installation

```bash
pip install starsim_data
```

## API overview

### Dataclasses

Data-holding classes

- `registry.Dataset`
- `registry.Source`

### Functions

Public functions

- `load`: Load data for a location
- `fetch`: Fetch a store this package publishes but does not bundle, caching it for next time
- `download`: Download UN WPP data that is not packaged, caching it for next time
- `plot`: Plot data for a location, as a quick check before it goes into a model
- `choropleth`: Draw a filled map of an administrative value -- the geometry version of `plot(which='nodes')`
- `provenance`: Return where a dataset came from: source, license, citation and build details
- `registry.datasets`
- `registry.dataset`
- `registry.unregister_dataset`
- `registry.get_layout`
- `registry.data_dir`
- `registry.refresh`
- `load_nodes`: Load the node table for a location: centroids, areas, p-codes and hierarchy
- `distances`: Great-circle distances between node centroids -- the input a gravity model needs
- `adjacency`: Which administrative units share a border: a square boolean matrix
- `node_name`: Render an administrative unit's name in this package's canonical style
- `download_shapes`: Download administrative boundaries with full geometry from their publisher, and cache them
- `list_shape_sources`: Return the boundary sources as a dataframe: coverage, levels and license
- `download_nodes`: The node table with `population` filled in, from WorldPop, at any level and year
- `download_raster`: Download a WorldPop 1 km gridded-population raster for a country, and cache it
- `aggregate_raster`: Sum a raster inside each polygon: zonal statistics, keyed by an attribute
- `rescale_to_national`: Scale node populations so they sum to this package's national WPP total
- `list_datasets`: Return the available datasets: contact sources plus WPP demographic series
- `list_locations`: Return the sorted locations available in dataset `which`
- `list_revisions`: Return the bundled UN WPP revisions, oldest first; the last is the default
- `list_fetchable`: Return the datasets `fetch()` can retrieve: the stores published with this package
- `list_downloadable`: Return the datasets `download()` can retrieve
- `resolve`: Resolve a location string to its canonical key
- `location_info`: Return the metadata row for a location, as a `sciris.objdict`
- `list_all_locations`: Return every canonical location name known to the package, sorted
- `parse_level`: Parse an administrative level into an integer
- `register_dataset`: Add a dataset to the registry
- `register_layout`: Register a function that turns a stored array into a dataframe
- `cache_dir`: Return the directory where downloaded data is cached
- `cache_info`: Return a dataframe of what is currently cached: file, size, source URL and date
- `cache_provenance`: Return the recorded provenance for a cached file, or None if there is none
- `cached_download`: Download `url` into the cache, or return the existing path if already cached
- `clear_cache`: Delete cached downloads. Bundled data is never touched

### Constants

Module-level constants and data

- `options`: Settings for `starsim_data`; the instance to use is `starsim_data.options`

## Resources

- [Full documentation](https://starsimhub.github.io/starsim_data/)
- [llms.txt](llms.txt) -- Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) -- Comprehensive documentation for LLMs
- [Source code](https://github.com/starsimhub/starsim_data)
````
