GEORELATE

Georelate constructs design matrices from geographical data.

Introduction

Along with an explosion in the availability of granular data, researchers in the social sciences, public health and demography are increasingly interested in using location data to identify diverse spatial treatment effects, from the local health benefits of new hospitals to the economic costs of natural disasters. Yet spatial data can only be as useful as it is easy usable. Unfortunately, using this data can require sophisticated techniques. Enter GEORELATE. GEORELATE uses code that efficiently computes millions of distance pairs on a single CPU core using only Python, Numpy and Pandas to facilitate spatial analysis. This User Guide explains the package’s functionality, demonstrates its usability with datasets built into the package (also shown below) and explains how users can use GEORELATE for their own work.

User Guide

Description

GEORELATE can take any 2 datasets, each containing a set of geographic points, and output a new dataset that includes variables indicating which points in one dataset are closest to each point in the other. GEORELATE also creates a new set of variables in the output dataset that indicate how far apart each point is from the nearest points in the other dataset.

Installation

GEORELATE can be installed by running the line below:

pip install georelate

Requirements:
Python 3.10+

GEORELATE in action

To more clearly demonstrate GEORELATE’s functionality in the sections below we include an example of how to apply the package with sample files and code.

The two input files below contain fictionalized data for Brazil. The first contains the IDs and geographic coordinates of polling stations. The second contains the same information for new foreign aid projects. The image below that shows the two sets of points overlayed on a map of Brazil. Finally, GEORELATE was used to create the output dataset shown below the map. The output dataset contains the IDs and distances away of the 3 closest aid projects to each polling station.

The input and out files are below:

Polling Stations

Aid Projects

Map

Blue = polling stations

Red = aid projects

Output

Example Code

Below I include the code used to create the output file (output.csv).

```python from georelate import designmatrix from georelate.data import loadpollaiddata

load in the foreign_aid data and the polling station data

leftdf, rightdf = loadpollaid_data()

the code below creates the output dataset

df = designmatrix( left = leftdf, right = rightdf, leftid = "localid", rightid = "projectidaid", rightlat = "lataid", rightlon = "longaid", k_closest=3 ) ```

A closer look at the code above...
The line above that begins with “designmatrix” creates the final output file and includes 7 arguments.
The first argument (left = leftdf) specifies the foreign aid projects dataset. GEORELATE will review all the coordinate points in this dataset to identify which foreign aid projects are nearest to the polling stations in the dataset specified in the second argument.
The second argument (right = rightdf) specifies the polling station dataset.
The third argument (leftid = "localid") specifies the column name containing the IDs of the foreign aid projects.
The fourth argument (rightid = "projectidaid") contains the column name containing the IDs of the polling stations.
The fifth argument contains the column name containing the latitude of the foreign aid projects.
The sixth argument contains the column name containing the longitude of the foreign aid projects.
The last argument is used to set the number of nearest foreign projects GEORELATE will include in the final output file. In the example above it is set to 3. Therefore, the output file includes information about the 3 nearest foreign aid projects to each polling station.

Development

Local Dev Instructions

Run poetry install to install the env.
Run poetry run pre-commit install to initialize the git hooks.
Run poetry run pre-commit run --all-files if there are file that were committed before adding the git hooks.
Activate the shell with: poetry shell
Lint with: poetry run pylint georelate/ tests/
Test with: poetry run pytest --cov=georelate

Pushing to PyPI

Environmental variables

Environmental variables are a good way to keep our tokens secret and our options configurable. To set them, copy sample.envrc to .envrc and change the values. Leave PYPI_USERNAME=__token__ and change the value of PYPI_PASSWORD to your password.
To load .envrc, one could just run .envrc as a shell script, but direnv will make things easier by automatically loading the variable when you enter the directory, once allowed.
To install direnv on a mac running zsh, use brew to install with brew install direnv and hook in into your shell by adding eval "$(direnv hook zsh)" to your .zshrc file. For other install instructions see: https://direnv.net/.
To allow direnv to load .envrc in a directory run direnv allow.

Alternatively, set the values of the environmental variable using export PYPI_USERNAME=__token__ && export PYPI_PASSWORD=<your-pypi-token>

Push to PyPI

Run poetry publish --build --username $PYPI_USERNAME --password $PYPI_PASSWORD to build and push the package to PyPI.