Geographic Unit Set Versions: Administrative and Crop Production

This page provides guidance on creating the upload files for administrative and crop production Geographic Unit Set Versions for the FEWS NET Data Warehouse (FDW).

Upload options

The upload file requirements are dependent on whether you are uploading spatial representation or tabular representation:

1. Spatial representation: Spatial data that includes the mapped boundaries of the Geographic Units (especially a digital version, such as a shapefile) that can be used to locate and map the Geographic Unit in relation to others.

2. Tabular representation (definitions only): A simple textual listing of the Geographic Units and the relationships between them in CSV or XLSX format. Since the actual geographic boundaries are not included, the data cannot be visualized on a map and no spatial analysis can be done.

Each period range is represented by a single Geographic Unit Set Version. For example, Sri Lanka’s crop production reporting units went through three boundary changes since 1978, and each change has its own active years. You can view these sets in the FEWS NET Data Explorer. A separate file is required for each Geographic Unit Set Version, whether it’s a shapefile or a definitions file.

There is no need to manually create a Geographic Unit Set or its versions in FDW, as this step will be handled by a member of the Hub’s Data Team once the upload files are prepared.

Classifying crop production data

Crop production data can be loaded into FDW using either of the following Geographic Unit Types:

• Administrative units

  • Unit types: Admin 1, Admin 2, Admin 3, Admin 4

  • Identified in FNIDs with the letter A

• Crop production reporting regions

  • Unit types: Level 1, Level 2, Level 3, Level 4, Level 5

  • Identified in FNIDs with the letter R

Crop production reporting regions may be used in cases where the existing admin units in FDW do not match up to the admin units used for crop reporting.

For example, crop data for Ethiopia was reported using a older, historic set of admin units, creating a mismatch with the admin unit records in FDW that are used for non-crop data. A new set of crop production reporting units were created in FDW to attribute the crop data more accurately.

When the existing administrative units in FDW are not linked to any data, it is generally safe to remove them and upload a new set of units for the country. If the official administrative units differ significantly from the crop regions, further discussion may be needed.

Administrative units and crop regions should be created in FDW before running the metadata mismatch check on the crop database.

There are small differences in the upload files for the two Geographic Unit Types, as described below.

How to structure files for Geographic Units

Below are all possible variations of the upload files, along with the situations where each should be used. In most cases, only one option is needed per country. It is strongly recommended to review the sample files (linked below, where available) for each use case to better understand the required file structure.

Shapefiles

1. Administrative units shapefile

An administrative units shapefile is used to upload administrative units with spatial data. View an example administrative units shapefile. Use the following conventions when preparing the file:

• ESRI shapefile name: Use the naming convention <two-letter country code>_Admin_<YYYY>

  • For example, SY_Admin_2018.zip.

• Layers: Each administrative level should be represented by a separate layer named using the convention <two-letter country code>_Admin<level>_<YYYY>

  • For example, ET_Admin2_2018 or KE_Admin1_2014.

• Required columns for each layer: FNID, EFF_YEAR, COUNTRY, ADMIN0. The year portion of the FNID should correspond to the EFF_YEAR (effective year) column.

• Admin level 1 columns: Include all required columns plus ADMIN1 (English name).

  • Optional columns include ADMIN1FR (French name), ADMIN1SP (Spanish name), ADMIN1PT (Portuguese name). It recommended adding these columns even if they are empty for consistency.

• Admin level 2 and lower columns: Include all required columns, previous admin level columns, and current admin level columns, e.g. ADMIN3, ADMIN3FR etc.

• Optional columns: Include ALIASES to record alternate names by which the Geographic Unit is known. Multiple aliases can be entered into the ALIASES column by adding an “~” before and after each additional alias. For example: ~Dese~Dessie~Kombolcha~. 

2. Crop production level regions shapefile

A crop production reporting regions shapefile is used to upload crop reporting regions with spatial data. This shapefile is very similar to the administrative units one with a few key differences. View an example crop production reporting regions shape file. Use the following conventions when preparing the file:

• ESRI shapefile name: Use the naming convention <two-letter country code>_Crop_<YYYY>

  • For example, ET_Crop_2021.zip.

• Layers: Each crop level should be represented by a separate layer named by “<two-letter country code>_Crop_level<level>_<YYYY>” e.g. ET_Crop_level2_2021 or SR_Crop_level3_2014.

• Required columns for each layer: FNID, EFF_YEAR, COUNTRY, ADMIN0. The year portion of the FNID should correspond to the EFF_YEAR (effective year) column.

• Crop level 1 columns: Include all required columns plus ADMIN1 (English name).

  • Optional columns include ADMIN1FR (French name), ADMIN1SP (Spanish name), ADMIN1PT (Portuguese name). It recommended adding these columns even if they are empty for consistency.

• Crop level 2 and lower columns: Include all required columns, previous admin level columns, and current admin level columns, e.g. ADMIN3, ADMIN3FR etc.

• Optional columns: Include ALIASES to record alternate names by which the Geographic Unit is known. Multiple aliases can be entered into the ALIASES column by adding an “~” before and after each additional alias. For example: ~Dese~Dessie~Kombolcha~.

Definitions

File structure for single levels

The structure of the unit definitions upload file depends on the number of levels included. Below are examples of definitions with a single level (admin1 or crop_level1).

1. Administrative unit definitions with a single admin level

The administrative unit definitions with a single admin level file is used to upload administrative definitions that only contain Level 1 units. View an example administrative unit definitions with a single admin level file. Use the following conventions when preparing the file:

• CSV file name: Use the naming convention <two-letter country code>_Admin1_<YYYY>

  • For example, VN_Admin1_2015.csv.

• Required columns: FNID, EFF_YEAR, COUNTRY_CODE, ADMIN0, ADMIN1.

• Optional columns: Include ALIASES to record alternate names by which the Geographic Unit is known. Multiple aliases can be entered into the ALIASES column by adding an “~” before and after each additional alias. For example: ~Dese~Dessie~Kombolcha~.

2. Crop production reporting region definitions with a single crop level

The crop production reporting region definitions with a single crop level file is used to upload crop production definitions that only contain Level 1 regions. Use the following conventions when preparing the file:

• CSV file name: Use the naming convention <two-letter country code>_Crop_level1_<YYYY>

  • For example, VN_Crop_level1_2015.csv.

• Required columns: FNID, EFF_YEAR, COUNTRY_CODE, crop_level0, crop_level1.

• Optional columns: Include ALIASES to record alternate names by which the Geographic Unit is known. Multiple aliases can be entered into the ALIASES column by adding an “~” before and after each additional alias. For example: ~Dese~Dessie~Kombolcha~.

File structure for multiple levels

In cases when there are more than one level of units, the following upload files in XLSX format need to be created.

1. Administrative unit definitions with more than one admin level

Use the following conventions when preparing the file:

• Excel file name: Use the naming convention <two-letter country code>_Admin_Definitions_<YYYY>

  • For example, PL_Admin_Definitions_2020.xlsx.

• Tabs: Each admin level is considered as a separate layer and should be added as a spreadsheet tab, named with the convention <two-letter country code>_admin<level>_<YYYY>

  • For example, PL_admin1_2020 or PL_admin4_2020.

  • There is no need to create a tab for admin0; this layer will be created automatically.

• Required columns in each tab: FNID, EFF_YEAR, COUNTRY_CODE, ADMIN0, ADMIN1.

• Additional lower level columns: Each lower level should have all required columns plus its own e.g. ADMIN2 or ADMIN3.

2. Crop reporting regions definitions with more than one crop level

View an example of crop reporting regions definitions with more than one crop level. Use the following conventions when preparing the file:

• Excel file name: Use the naming convention <two-letter country code>_Crop_Level_Definitions_<YYYY>

  • For example, LK_Crop_Level_Definitions_1988.xlsx.

• Tabs: Each crop level is considered as a separate layer and should be added as a spreadsheet tab, named with the convention <two-letter country code>_crop_level<level>_<YYYY>

  • For example, LK_crop_level1_1988 or LK_crop_level2_1988.

  • There is no need to create a tab for crop_level0; this layer will be created automatically.

• Required columns in each tab: FNID, EFF_YEAR, COUNTRY_CODE, crop_level0, crop_level1.

• Additional lower level columns: Each lower level should have all required columns plus its own e.g. crop_level2 or crop_level4.