Geo Grid Designer

For use with geofacet.

To try it out, click here.

To try it out with a pre-populated example, click here.

Adding Grids

Although initially created to support the R geofacet package, this repository is intended to be a place for the community to share and grow a large collection of grids that might be useful for any project that can make use of them. You can contribute by submitting pull requests that add new grids following the guidelines outlined below.

Note that when a user of the geofacet R package creates a new grid, they are prompted to share it with others. To help streamline the process for them, a GitHub issue is automatically created for them that is populated with the grid data and instructions for them to provide some additional info such as an image file that represents the geographical region referred to by the grid.

Grid Data Format

To add a new grid, there are two pieces of information that must be added or updated in this repository.

1. Add a csv file containing the grid data in the grids/ directory
2. Add an entry to the list of grids, grid_list.json, with the appropriate information about your grid.

Grid csv File Guidelines

• Every grid must only have column names code, name, row, and col, and column names are always lowercase. One exception is that it is possible for there to be multiple code and name columns, in which case they can be appended with an underscore and suffix to differentiate them. For example, we might have code_fips and code_iso. Or name_en and name_de. Or name and name_abb.
• The values of the columns row and col must be jointly distinct (no overlapping grid tiles).
• The values in the “name” columns should have proper noun capitalization. No all caps.
• Naming the csv file: The general rule is lowercase / snake case with the first part of the name being the overarching geographic entity, the next being the type of geographic partitioning (e.g. county, state, province, etc.), followed by “grid[n]”, where “n” indicates the grid number. I put the grid number in just in case different users submit different layouts for the same grid. Some example names of grids can be seen here.

Good resourcea for choosing aspects of the file name include a list of ISO_3166-1_alpha-2 codes for countries. You can search for similar lists of codes for other geographic entities as well.

For example, suppose we want to take a user-submitted grid provided in this GitHub issue and get it ready to officially submit as a grid in this repository. The submitted grid data looks like this:

cod_provincias,PROVINCIAS,row,col
04,CARCHI,2,4
21,SUCUMBIOS,3,7
08,ESMERALDAS,3,2
...

There are a few things that must be corrected when submitting this data as a csv file here.

• The column names should be renamed to code, name , row, col.
• Since the code column appears to contain codes that are numeric but with leading zeros, we would probably want to place quotes around the code values in each row so that the leading zero is not lost when read in (many csv parsers would read the column as numeric and remove the leading zeros).
• The values in the name column should not be all caps.

A correct version of the csv file should look more like this:

code,name,row,col
"04",Carchi,2,4
"21",Sucumbios,3,7
"08",Esmeraldas,3,2
...

This grid has been added to this repository and the file was named ec_prov_grid1.csv

Grid List Updating Guidelines

The grid_list.json file in this repository contains an index to all of the available grids, with a few pieces of metadata that can be useful for providing some more context around the grid.

Each new grid entry should provide the following information:

• name: The name of the corresponding .csv file found in the grids/ directory (without the .csv extension). This file must exist. In the example Equador provinces grid described above, the value would be ec_prov_grid1.
• desc: A description of the grid. For example, in the Equador example, it was described as Grid layout for provinces of Ecuador.
• contrib: A URL pointing to the GitHub user page for the person who contributed the grid, for attribution. For example, for this grid it was https://github.com/Ricardo95RM.
• ref_img: We want to have a reference image that makes it convenient for users to get a quick visual feel for what geography the grid refers to. In the Ecuador example, the user uploaded a reference image attached to the GitHub issue, found here. In this case, we simply need to add the URL associated with this image to the grid list entry.

Note: In the past, we encouraged users to upload a reference image in their GitHub issues. However, GitHub has since made it difficult to publicly access images in GitHub issues so we need to find an anternative free public place to store reference images for new grids, ideally one that we feel is going to be around for a long time. It is preferred for a reference image to be uploaded somewhere that we feel confident that it will stick around, vs. just providing a direct link to the original source of the image, which could change or disappear.

Validating a Grid

If you want to validate a grid csv data file that you have created, you can install the R {geofacet} package, read the csv file into R, and call geofacet::grid_preview() on it. This will check that the grid is valid (checks column names, unique row/col values, etc.), and will plot the grid so that you can visually verify that it looks good (sometimes people will submit grids that are just rectangular and don’t look like they did anything to actually create a grid).