Movatterモバイル変換

ripc: Download and Tidy IPC and CH Data

Description

Utilities to access Integrated Food Security Phase Classification (IPC) and Cadre Harmonisé (CH) food security data. Wrapper functions are available for all of the 'IPC-CH' Public API (https://docs.api.ipcinfo.org) simplified and advanced endpoints to easily download the data in a clean and tidy format.

Author(s)

Maintainer: Seth Caldwellcaldwellst@gmail.com [copyright holder]

See Also

Useful links:

• https://github.com/ocha-dap/ripc

• Report bugs athttps://github.com/ocha-dap/ripc/issues

Get resource from IPC API

Description

Back-end function used to drive the API calls of the otheripc_get_...()family of functions.

Usage

ipc_get(resource, return_format, pass_format, api_key = NULL, ...)

Arguments

Value

Data frame from the API

Get analyses resources from the IPC API

Description

Accesses the areas resources on the IPC API. Contains detailed analysisinformation. Ifcountry,year and/ortype parameters are passed,accesses theanalyses simplified API endpoint and pulls in all analyses orfiltered to those parameters. To get the details for a specific analysisavailable on theanalyses/{id}/{period} advanced API endpoint,pass inid. You cannot pass in both sets of parameters.

Usage

ipc_get_analyses(  country = NULL,  year = NULL,  type = NULL,  id = NULL,  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Analyses data is metadata related to specific analyses conducted by the IPC,including title of the analysis, link to its release page on the IPC website,and creation/modification dates.

Value

Data frame of analysis metadata. Refer to theIPC-CH Public API documentation for detailson the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE, the following changes are made to the initialoutput to ensure each row represents a single analysis:

1. The data is arranged bycountry,year, andcreated.

2. id column is renamed to beanalysis_id.

Examples

# get all analyses details from the simplified APIipc_get_analyses()# get analysis details for a specific analysis IDipc_get_analyses(id = 12856213)

Get areas resources from the IPC-CH API

Description

Accesses the areas resources on the IPC-CH API. Contains detailed area andpopulation data. Ifcountry,year and/ortype parameters are passed,accesses theareas simplified API endpoint and pulls in all areas filtered tothose parameters. To get all areas for a specific analysisand period, available on theareas/{id}/{period} advanced API endpoint,pass inid andperiod. You cannot pass in both sets of parameters.

Usage

ipc_get_areas(  country = NULL,  year = NULL,  type = NULL,  id = NULL,  period = NULL,  return_format = c("csv", "geojson"),  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Areas data is the typical unit of analysis in IPC-CH outputs. These aretypically administrative units (or clusters of them together). For each area,estimates of the population in each phase is provided and a general phaseclassification is assigned. Useipc_get_population() to getdetailed population data and classifications for all analysis periods.

See theIPC website andAPI documentation for more information.

Value

Data frame of IPC and CH analysis at the areas level. Refer to theIPC-CH Public API documentation for detailson the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE, the following changes are made to the initialoutput to ensure each row represents a single area analysis, and all estimatesand values are stored as columns:

1. analysis_period_start andanalysis_period_end created asDate columnsfrom thefrom andto columns respectively, allocating the day of thestart and end periods to be the 15th of the month.

2. title column is renamed to bearea_name,anl_id toanalysis_id,andid andaar_id are changed toarea_id.

3. Duplicated rows are removed from the data frame if the return value is CSV,because the duplicates are there due to polygon geometries.

Examples

# get all areas from the simplified APIipc_get_areas()# get areas for specific analysis ID and period from advanced APIipc_get_areas(id = 12856213, period = "P")# request GeoJSON returnipc_get_areas(id = 12856213, period = "P", return_format = "geojson")

Get country resources from the IPC API

Description

Accesses the country resources on the IPC API. Contains detailedcountry-level data. Ifcountry,year and/ortype parameters are passed,accesses thecountry simplified API endpoint and pulls in all country datafiltered to those parameters.

Usage

ipc_get_country(  country = NULL,  year = NULL,  type = NULL,  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Country data is the highest level of aggregation for IPC analysis. Data isthe population estimates and other details aggregated from area and pointanalyses within the country for that specific analysis. No phaseclassifications are made at the country level. Data is currently output onlyfor current periods through thecountry endpoint. Useipc_get_population() to get detailed population data for all analysisperiods.

See theIPC website andAPI documentation for more information.

Value

Data frame of IPC and CH analysis at the country level. Refer to theIPC-CH Public API documentation for detailson the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE, the following changes are made to the initialoutput to ensure each row represents a single country analysis, and all estimatesand values are stored as columns:

1. analysis_period_start andanalysis_period_end created asDate columnsfrom thefrom andto columns respectively, allocating the day of thestart and end periods to be the 15th of the month.

2. id column is renamed to beanalysis_id.

Examples

# get all areas from the simplified APIipc_get_country()# get country data just for Somaliaipc_get_country(country = "SO")

Get icons resources from the IPC API

Description

Accesses the icons resources on the IPC API. Contains links from analysis andarea IDs to the icon resource the IPC uses in maps and publications. Thisis likelynot useful for the general user. Ifyear and/ortypeparameters are passed, accesses theicons simplified API endpoint, pulls indata filtered to those parameters. To get all icons for a specific analysisand period, available on thetypes/{id}/{period} advanced API endpoint,pass inid andperiod. You cannot pass in both sets of parameters.

Usage

ipc_get_icons(  year = NULL,  type = NULL,  id = NULL,  period = NULL,  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Icons data is used internally by the IPC to link up analyses for areas and arelevant icon for display on maps and in publications. The icons are storedin an Amazon S3 bucket that is not publicly accessible and therefore notuseful for general users. Provided here for convenience.

See theIPC website andAPI documentation for more information.

Value

Data from of icons for analysis publications.Refer to theIPC-CH Public API documentationfor details on the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE,aar_id is renamed toarea_id andarea toarea_name.

Examples

# get all icons from the simplified APIipc_get_icons()# get icons for specific analysis ID and period from advanced APIipc_get_icons(id = 12135625, period = "C")

Get points resources from the IPC API

Description

Accesses the points resources on the IPC API. Contains detailed area andpopulation data. Ifyear and/ortype parameters are passed, accessesthetypes simplified API endpoint and pulls in all types data or filtered toeitheryear ortype. To get all types for a specific analysisand period, available on thetypes/{id}/{period} advanced API endpoint,pass inid andperiod. You cannot pass in both sets of parameters.

Usage

ipc_get_points(  year = NULL,  type = NULL,  id = NULL,  period = NULL,  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Points data is IPC data generated from analysis on geographicentities that are smaller than the standard areas. These are typicallyurban areas or displacement sites where food insecurity conditions mightdiffer significantly from the wider context and justify specific analysis.Population estimates as well as an overall phase classification are providedfor each point. Data is currently output only for currentperiods through thepoints endpoint. Useipc_get_population() to getdetailed population data and classifications for all analysis periods. Pointsdata is contained within theareas dataset returned fromipc_get_population().

See theIPC website andAPI documentation for more information.

Value

Data frame of IPC and CH analysis at the point level. Refer to theIPC-CH Public API documentation for detailson the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE, the following changes are made to the initialoutput to ensure each row represents a single point analysis, and all estimatesand values are stored as columns:

1. All columns containingphase orpopulation are converted to numeric.

2. aar_id is renamed toarea_id andanl_id toanalysis_id.

Examples

# get all areas from the simplified APIipc_get_points()# get areas for specific analysis ID and period from advanced APIipc_get_points(id = 18978466, period = "P")

Get population resources from the IPC API

Description

Accesses the population resources on the IPC API. Contains detailedpopulation data. Ifcountry and/orstart andend parameters are passed,accesses thepopulation advanced API endpoint and pulls in all data.filtered by those parameters. To get the population data for a specificanalysis, available on thetypes/{id} advanced API endpoint,pass inid. You cannot pass in both sets of parameters.

Usage

ipc_get_population(  country = NULL,  start = NULL,  end = NULL,  id = NULL,  api_key = NULL,  tidy_df = TRUE)

Arguments

Details

Unlike the otheripc_get_..() family of functions, this returns a list ofdatasets, corresponding tocountry,areas, andgroups data. The benefit ofipc_get_population() is that thereturned data for each level of analysis contains all periods of analysis.

Groups data, where available, are geographies within a country thatcomprise multiple areas and/or points.Areas and points data is the lowest level of IPC analysis where populationestimates for each phase are provided and a general area-level classificationis made. There is no phase classification atthe group level, but populations in each phase are provided. The same appliesto country-level data.

These datasets are available elsewhere through:

• Country data:ipc_get_country()

• Areas data:ipc_get_areas()

• Groups data: Not available through other functions

See the respective function documentation for more details on what eachdataset comprises or theIPC website andAPI documentation for more detailed andcomprehensive information on the data and analysis.

Value

A list of 3 data frames:

• Country data frame.

• Areas data frame.

• Groups data frame.

Refer to theIPC-CH Public API documentationfor details on the returned values, with variables described in full in theextended documentation.

Tidy

Whentidy_df isTRUE, the data returned from the population end point istransformed into a list of 3 data frames to ensure that each row represents asingle analysis, and all estimates and values are stored as columns, whiledata at different levels of aggregation are in completely separate dataframes. The steps are:

1. analysis_period_start andanalysis_period_end created asDate columnsfrom theperiod_dates column respectively, allocating the day of thestart and end periods to be the 15th of the month.

2. analysis_date converted to a date column, using the 15th day of the month.

3. phases is unnested from a list column to bring the phase data intothe main data frame.

4. The population estimates are pivoted to a wider format with namesphase#_numandphase#_pct.

5. id column renamed toanalysis_id.

6. Data frames are split out so multiple aggregations not present in a singlesingle data frame.

Examples

# get all populations from the simplified APIipc_get_population()# get populations for specific analysis ID from advanced APIipc_get_population(id = 12856213) # analysis with areas data frameipc_get_population(id = 65508276) # analysis with groups data frame