### FAOSTAT Package Initialization

Source: https://rdrr.io/cran/FAOSTAT/src/R/FAOSTAT-package.R

This snippet shows the basic setup for the FAOSTAT R package, including necessary imports and global variable declarations. It is used when starting a new R session that will interact with FAOSTAT data.

```R
#' @title A complementary package to the FAOSTAT database and the
#' @keywords package
#' @import RJSONIO
#' @import plyr
#' @import data.table
#' @import MASS
#' @import classInt
#' @import labeling
#' @import httr
"_PACKAGE"

.FAOSTATenv <- new.env()
# Remove CHECK note due to non-standard evaluation in data.table
utils::globalVariables(c("code", "label", "date_update"))

```

--------------------------------

### Install and Load FAOSTAT Package

Source: https://rdrr.io/cran/FAOSTAT/src/demo/FAOSTATdemo.R

Installs the FAOSTAT package from GitHub if not already installed and then loads it into the R session. It also provides commands to access package documentation and vignettes.

```R
if(!is.element("FAOSTAT", .packages(all.available = TRUE)))
  install_github(username = "mkao006", repo = "FAOSTATpackage", ref = "master", subdir = "FAOSTAT")
library(FAOSTAT)
help(package = "FAOSTAT")
vignette("FAOSTAT", package = "FAOSTAT")
```

--------------------------------

### Example: Simplest Usage (Interactive Prompt)

Source: https://rdrr.io/cran/FAOSTAT/man/faostat_login.html

This example demonstrates the simplest way to use the FAOSTAT API, relying on interactive prompts for credentials if environment variables are not set. It calls get_faostat_bulk after logging in.

```R
# Simplest usage — prompts for credentials interactively if not set:
crop_production <- get_faostat_bulk(code = "QCL", data_folder = "data_raw")

```

--------------------------------

### Install FAOSTAT from GitLab

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

Installs the FAOSTAT package from a GitLab repository if it's not already installed, then loads the library. Requires the 'remotes' package.

```r
# if(!is.element("FAOSTAT", .packages(all.available = TRUE)))
#     remotes::install_gitlab(repo="paulrougieux/faostatpackage/FAOSTAT")
# library(FAOSTAT)
```

--------------------------------

### Install FAOSTAT from CRAN

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

Installs the FAOSTAT package from CRAN if it's not already installed, then loads the library.

```r
# if(!is.element("FAOSTAT", .packages(all.available = TRUE)))
#    install.packages("FAOSTAT")
# library(FAOSTAT)
```

--------------------------------

### Example: Silent Usage (Environment Variables)

Source: https://rdrr.io/cran/FAOSTAT/man/faostat_login.html

This example shows how to use the FAOSTAT API silently by setting user credentials in environment variables. It calls get_faostat_bulk after logging in.

```R
# Silent usage — set in ~/.Renviron (run usethis::edit_r_environ() to open it):
# FAOSTAT_USER=your@email.com
# FAOSTAT_PASSWORD=yourpassword
crop_production <- get_faostat_bulk(code = "QCL", data_folder = "data_raw")

```

--------------------------------

### Example: Get Cropland Data for a Specific Year

Source: https://rdrr.io/cran/FAOSTAT/man/read_fao.html

This example demonstrates how to retrieve cropland data for a specific area, element, item, and year using the `read_fao` function. Ensure you have the correct FAOSTAT codes for each parameter.

```R
# Get data for Cropland (6620) Area (5110) in Antigua and Barbuda (8) in 2017
df = read_fao(
  area_codes = "8", element_codes = "5110", item_codes = "6620", 
  year_codes = "2017"
)
```

--------------------------------

### Example Usage of getWDItoSYB

Source: https://rdrr.io/cran/FAOSTAT/man/getWDItoSYB.html

Example of how to use the getWDItoSYB function to download total population data. Assigns the result to pop.df.

```R
## pop.df = getWDItoSYB(name = "total_population",
##                      indicator = "SP.POP.TOTL")




```

--------------------------------

### R Example: Accessing scaleUnit Help

Source: https://rdrr.io/cran/FAOSTAT/src/R/scaleUnit.R

Shows how to access the help documentation for the scaleUnit function within an R environment using the help() function.

```R
library(FAOSTAT)
help(scaleUnit)
```

--------------------------------

### Example Usage of search_dataset

Source: https://rdrr.io/cran/FAOSTAT/src/R/search_dataset.R

Demonstrates how to use the `search_dataset` function with different arguments. The `
\dontrun{}` block indicates that these examples should not be run automatically during package checks.

```R
# Find information about all datasets
fao_metadata <- search_dataset()
# Find information about forestry datasets
search_dataset(dataset_code="FO")
# Find information about datasets whose titles contain the word "Flows"
search_dataset(dataset_label="Flows")
```

--------------------------------

### Install FAOSTAT Package

Source: https://rdrr.io/cran/FAOSTAT

Install the latest version of the FAOSTAT package from CRAN. This is the primary step to begin using the package's functionalities.

```r
install.packages("FAOSTAT")
```

--------------------------------

### Example: FAOSTAT Bulk Data Download Workflow

Source: https://rdrr.io/cran/FAOSTAT/src/R/faostat_bulk_download.R

Demonstrates a complete workflow for downloading, processing, and caching FAOSTAT bulk data. Includes creating directories, loading data via API, downloading via URL, and reading local zip files.

```R
# Create a folder to store the data
data_folder <- "data_raw"
dir.create(data_folder)

# Load crop production data via the API
crop_production <- get_faostat_bulk_api(code = "QCL", data_folder = data_folder)

# Cache the file i.e. save the data frame in the serialized RDS format for faster load time later.
saveRDS(crop_production, "data_raw/crop_production_e_all_data.rds")
# Now you can load your local version of the data from the RDS file
crop_production <- readRDS("data_raw/crop_production_e_all_data.rds")


# Download and read in one step using a direct URL
df <- get_faostat_bulk_url(
    "https://bulks-faostat.fao.org/production/Production_Crops_Livestock_E_Oceania.zip",
    data_folder = data_folder
)

# Use the lower level functions to download zip files,
# then read the zip files in separate function calls.
# In this example, to avoid a warning about "examples lines wider than 100 characters"
# the url is split in two parts: a common part 'url_bulk_site' and a .zip file name part.
# In practice you can enter the full url directly as the `url_bulk`  argument.
# Notice also that I have choosen to load global data in long format (normalized).
url_bulk_site <- "https://fenixservices.fao.org/faostat/static/bulkdownloads"
url_crops <- file.path(url_bulk_site, "crop_production_E_All_Data_(Normalized).zip")
url_forestry <- file.path(url_bulk_site, "Forestry_E_All_Data_(Normalized).zip")
# Download the files
download_faostat_bulk(url_bulk = url_forestry, data_folder = data_folder)
download_faostat_bulk(url_bulk = url_crops, data_folder = data_folder)

# Read the files and assign them to data frames
crop_production <- read_faostat_bulk("data_raw/crop_production_E_All_Data_(Normalized).zip")
forestry <- read_faostat_bulk("data_raw/Forestry_E_All_Data_(Normalized).zip")

# Save the data frame in the serialized RDS format for fast reuse later.
saveRDS(crop_production, "data_raw/crop_production_e_all_data.rds")
saveRDS(forestry,"data_raw/forestry_e_all_data.rds")
```

--------------------------------

### Run FAOSTAT Package Tests

Source: https://rdrr.io/cran/FAOSTAT/src/tests/testthat.R

Loads the testthat and FAOSTAT libraries and then runs the package tests. Ensure these libraries are installed before execution.

```r
library(testthat)
library(FAOSTAT)

test_check("FAOSTAT")

```

--------------------------------

### Example usage of read_dimension_metadata

Source: https://rdrr.io/cran/FAOSTAT/src/R/read_dataset_dimension.R

Demonstrates how to call the read_dimension_metadata function with a dataset code. This example is intended to be run interactively.

```R
library(FAOSTAT)
help(read_dimension_metadata)
```

--------------------------------

### R Package Usage Example

Source: https://rdrr.io/cran/FAOSTAT/src/R/mergeSYB.R

Demonstrates how to access the help documentation for the mergeSYB function within the FAOSTAT R package. This is useful for understanding the function's parameters and usage.

```R
library(FAOSTAT)
help(mergeSYB)
```

--------------------------------

### Example: Get Cropland Area Data

Source: https://rdrr.io/cran/FAOSTAT/src/R/read_fao.R

Retrieves cropland area data for a specific country and year, or a range of years. This example demonstrates basic usage of `read_fao` with area, element, item, and year codes.

```R
# Get data for Cropland (6620) Area (5110) in Antigua and Barbuda (8) in 2017
df = read_fao(area_codes = "8", element_codes = "5110", item_codes = "6620", 
year_codes = "2017")
# Load cropland area for a range of year
df = read_fao(area_codes = "106", element_codes = "5110", item_codes = "6620", 
year_codes = 2010:2020)
```

--------------------------------

### Example: Retrieve Dimension Metadata

Source: https://rdrr.io/cran/FAOSTAT/man/read_fao.html

These examples demonstrate how to fetch metadata for different dimensions (area, item, element) from the FAOSTAT API using the `read_dimension_metadata` function. This is useful for finding available codes.

```R
# Find which country codes are available
metadata_area <- read_dimension_metadata("RL", "area")
# Find which items are available
metadata_item <- read_dimension_metadata("RL", "item")
# Find which elements are available
metadata_element <- read_dimension_metadata("RL", "element")
```

--------------------------------

### Download Data from Direct URL

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

This example demonstrates downloading a zip file directly from a URL and reading its content into a data frame using `get_faostat_bulk_url`.

```R
# Download and read in one step using a direct URL
df <- get_faostat_bulk_url(
    "https://bulks-faostat.fao.org/production/Production_Crops_Livestock_E_Oceania.zip",
    data_folder = data_folder
)
```

--------------------------------

### Example Usage of getWDI

Source: https://rdrr.io/cran/FAOSTAT/man/getWDI.html

This is a basic example demonstrating how to call the getWDI function to retrieve population data. The output is assigned to the variable pop.df.

```R
## pop.df = getWDI()
```

--------------------------------

### Example Usage of grConstruct

Source: https://rdrr.io/cran/FAOSTAT/src/R/grConstruct.R

Demonstrates how to use the grConstruct function with different 'n' periods for geometric growth rate calculation.

```R
test.df2 = data.frame(FAOST_CODE = rep(c(1, 5000), each = 5),
                        Year = rep(1990:1994, 2),
                        a = rep(1:5, 2), b = rep(1:5, 2))
grConstruct(test.df2, origVar = "a", type = "geo", n = 1)
grConstruct(test.df2, origVar = "a", type = "geo", n = 3)
grConstruct(test.df2, origVar = "a", type = "geo", n = 5)
```

--------------------------------

### Example: Load Cropland Area for a Range of Years

Source: https://rdrr.io/cran/FAOSTAT/man/read_fao.html

This example shows how to load cropland area data for a specified area, element, and item across a range of years. The `year_codes` argument accepts a vector of years.

```R
# Load cropland area for a range of year
df = read_fao(area_codes = "106", element_codes = "5110", item_codes = "6620", 
year_codes = 2010:2020)
```

--------------------------------

### Get FAOSTAT Bulk Data (Backward Compatibility)

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Alias for `get_faostat_bulk_api()`, maintained for backward compatibility. Loads data using a dataset code.

```R
get_faostat_bulk(code, data_folder = tempdir(), subset = "All Data Normalized")
```

--------------------------------

### Example Data Frame Creation

Source: https://rdrr.io/cran/FAOSTAT/man/Aggregation.html

This code snippet demonstrates how to create a sample data frame for use with the Aggregation function. It includes country codes, year, a value to be aggregated, and a weight.

```R
## example.df = data.frame(FAOST_CODE = rep(c(1, 2, 3), 2),
##                        Year = rep(c(2010, 2011), c(3, 3)),
##                        value = rep(c(1, 2, 3), 2),
##                        weight = rep(c(0.3, 0.7, 1), 2))
```

--------------------------------

### Retrieve All FAOSTAT Dataset Information

Source: https://rdrr.io/cran/FAOSTAT/man/search_dataset.html

Fetches metadata for all available datasets from the FAOSTAT database. This is useful for getting a comprehensive overview of the available data.

```R
# Find information about all datasets
fao_metadata <- search_dataset()
```

--------------------------------

### Get FAOSTAT Bulk Data from URL into Data Frame

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Downloads a bulk zip file from a URL and reads it directly into a data frame in one step. This is a convenient alternative to downloading and then reading.

```R
get_faostat_bulk_url(url_bulk, data_folder = ".")
```

--------------------------------

### Example: Take Old for Country Overlap

Source: https://rdrr.io/cran/FAOSTAT/man/check_country_overlap.html

Shows how to apply the 'takeOld' strategy for country code overlaps, favoring older data entries. Requires a data frame with FAOST_CODE, Year, and Value.

```R
check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "takeOld")

```

--------------------------------

### Get FAOSTAT Bulk Data via API

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Loads a specified dataset code via the FAOSTAT API and returns it as a data frame. This is the recommended function for general data loading and provides normalized data by default.

```R
get_faostat_bulk_api(
  code,
  data_folder = tempdir(),
  subset = "All Data Normalized"
)
```

--------------------------------

### Example: Complete Overlap Handling

Source: https://rdrr.io/cran/FAOSTAT/man/check_country_overlap.html

Demonstrates the 'complete' strategy for handling country code overlaps, which may involve a more comprehensive data reconciliation. Requires a data frame with FAOST_CODE, Year, and Value.

```R
check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "complete")

```

--------------------------------

### Example: Simple Country Overlap Check

Source: https://rdrr.io/cran/FAOSTAT/man/check_country_overlap.html

Demonstrates a basic check for country code overlaps using the 'simpleCheck' strategy. Requires a data frame with FAOST_CODE, Year, and Value columns.

```R
test.df = 
   data.frame(FAOST_CODE = rep(c(51,167,199), each = 3), 
  Year = rep(c(1990:1992), 3),
  Value = c(c(3,4,4), c(2,2,2), c(1,2,NA)))
check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "simpleCheck")

```

--------------------------------

### Example Relation Data Frame Creation

Source: https://rdrr.io/cran/FAOSTAT/man/Aggregation.html

This code snippet shows how to create a relation data frame for the Aggregation function. It defines how country codes should be mapped to new codes for aggregation purposes.

```R
## relation.df = data.frame(FAOST_CODE = 1:3, NEW_CODE = c(1, 1, 2))
```

--------------------------------

### Example: Take New for Country Overlap

Source: https://rdrr.io/cran/FAOSTAT/man/check_country_overlap.html

Illustrates using the 'takeNew' strategy to handle country code overlaps, prioritizing newer data entries. Assumes a data frame with FAOST_CODE, Year, and Value.

```R
check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "takeNew")

```

--------------------------------

### Load FAOSTAT Package and Access Help

Source: https://rdrr.io/cran/FAOSTAT/src/R/constructSYB.R

Loads the FAOSTAT package and displays the help documentation for the constructSYB function. This is useful for understanding the function's parameters and usage.

```R
library(FAOSTAT)
help(constructSYB)
```

--------------------------------

### Load FAOSTAT Library and Access Help

Source: https://rdrr.io/cran/FAOSTAT/src/R/getWDItoSYB.R

Loads the FAOSTAT library and displays the help documentation for the getWDItoSYB function. This is a common first step when learning to use a new function.

```r
library(FAOSTAT) 
help(getWDItoSYB)
```

--------------------------------

### R Help and Library Loading

Source: https://rdrr.io/cran/FAOSTAT/src/R/getWDImetaData.R

Demonstrates how to load the FAOSTAT library and access help documentation for the getWDImetaData function in R.

```R
library(FAOSTAT)
help(getWDImetaData)
```

--------------------------------

### Load FAOSTAT Package and Access Help

Source: https://rdrr.io/cran/FAOSTAT

Load the FAOSTAT package into your R session and access its main help documentation. This is useful for exploring the package's functions and usage.

```r
library(FAOSTAT)
help(FAOSTAT)
```

--------------------------------

### Create Data Folder and Search Metadata

Source: https://rdrr.io/cran/FAOSTAT/src/demo/FAOSTATdemo.R

Creates a directory to store raw data and then loads metadata for all available FAOSTAT datasets. This is a preparatory step before downloading specific data.

```R
# Create a folder to store the data
data_folder <- "data_raw"
dir.create(data_folder)

# Load information about all datasets into a data frame
fao_metadata <- FAOsearch()
```

--------------------------------

### Get Geographic Information

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves geographic information for countries or regions. This function is useful for mapping and spatial analysis.

```r
geogr(country_code = "CHN")
```

--------------------------------

### Download and Read FAOSTAT Bulk Files

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

This snippet illustrates using lower-level functions to download specific bulk zip files (forestry and crop production) and then reading them into separate data frames. It also shows how to save these data frames as RDS files.

```R
# Use the lower level functions to download zip files,
# then read the zip files in separate function calls.
# In this example, to avoid a warning about "examples lines wider than 100 characters"
# the url is split in two parts: a common part 'url_bulk_site' and a .zip file name part.
# In practice you can enter the full url directly as the `url_bulk`  argument.
# Notice also that I have choosen to load global data in long format (normalized).
url_bulk_site <- "https://fenixservices.fao.org/faostat/static/bulkdownloads"
url_crops <- file.path(url_bulk_site, "crop_production_E_All_Data_(Normalized).zip")
url_forestry <- file.path(url_bulk_site, "Forestry_E_All_Data_(Normalized).zip")
# Download the files
download_faostat_bulk(url_bulk = url_forestry, data_folder = data_folder)
download_faostat_bulk(url_bulk = url_crops, data_folder = data_folder)

# Read the files and assign them to data frames
crop_production <- read_faostat_bulk("data_raw/crop_production_E_All_Data_(Normalized).zip")
forestry <- read_faostat_bulk("data_raw/Forestry_E_All_Data_(Normalized).zip")

# Save the data frame in the serialized RDS format for fast reuse later.
saveRDS(crop_production, "data_raw/crop_production_e_all_data.rds")
saveRDS(forestry,"data_raw/forestry_e_all_data.rds")
```

--------------------------------

### Download FAOSTAT Bulk Data from URL

Source: https://rdrr.io/cran/FAOSTAT/src/R/faostat_bulk_download.R

Downloads a FAOSTAT bulk data file from a given URL and then reads it using `read_faostat_bulk`. Creates the destination directory if it doesn't exist.

```R
get_faostat_bulk_url <- function(url_bulk, data_folder = "."){
    dir.create(data_folder, showWarnings = FALSE, recursive = TRUE)
    file_name <- basename(url_bulk)
    dest_path <- file.path(data_folder, file_name)
    if (!file.exists(dest_path)) {
        resp <- GET(url_bulk, write_disk(dest_path, overwrite = TRUE), progress())
        if (http_error(resp)) {
            stop(sprintf("Failed to download file from %s. Status: %d", url_bulk, status_code(resp)))
        }
    }
    read_faostat_bulk(dest_path)
}
```

--------------------------------

### Create Sample Data Frame

Source: https://rdrr.io/cran/FAOSTAT/man/grConstruct.html

This snippet demonstrates how to create a sample data frame for testing the grConstruct function.

```R
test.df2 = data.frame(FAOST_CODE = rep(c(1, 5000), each = 5),
                       Year = rep(1990:1994, 2),
                       a = rep(1:5, 2), b = rep(1:5, 2))
```

--------------------------------

### Get FAOSTAT Region Profile

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves region-specific profile data from FAOSTAT. This function is useful for obtaining aggregated statistics for a defined region.

```r
FAOregionProfile(iso3c = "CHN", date = "2020")
```

--------------------------------

### Download Crop Production Data via API

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

This snippet shows how to create a data folder, download crop production data using the `get_faostat_bulk_api` function, and save it as an RDS file for later use.

```R
# Create a folder to store the data
data_folder <- "data_raw"
dir.create(data_folder)

# Load crop production data via the API
crop_production <- get_faostat_bulk_api(code = "QCL", data_folder = data_folder)

# Cache the file i.e. save the data frame in the serialized RDS format for faster load time later.
saveRDS(crop_production, "data_raw/crop_production_e_all_data.rds")
# Now you can load your local version of the data from the RDS file
crop_production <- readRDS("data_raw/crop_production_e_all_data.rds")
```

--------------------------------

### Get FAOSTAT Country Profile

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves country-specific profile data from FAOSTAT. This function is useful for obtaining aggregated statistics for a single country.

```r
FAOcountryProfile(iso3c = "CHN", date = "2020")
```

--------------------------------

### R FAOSTAT Library Usage

Source: https://rdrr.io/cran/FAOSTAT/src/R/chgr.R

Demonstrates how to load the FAOSTAT library in R and access the help documentation for the chgr function.

```R
library(FAOSTAT)
help(chgr)
```

--------------------------------

### faostat_login

Source: https://rdrr.io/cran/FAOSTAT/src/R/rest.R

Registers for a FAOSTAT account and logs in to get an access token. This function can be called explicitly or will be triggered automatically by other API calls when no token is present.

```APIDOC
## faostat_login

### Description
Authenticates with the FAOSTAT API and stores the access token for the current session. Credentials can be provided as arguments, environment variables, or through an interactive prompt.

### Function Signature
```R
faostat_login(username = Sys.getenv("FAOSTAT_USER"), password = Sys.getenv("FAOSTAT_PASSWORD"), base_url = "https://faostatservices.fao.org/api/v1")
```

### Parameters
#### Arguments
- **username** (character) - Your FAOSTAT account email. Defaults to the `FAOSTAT_USER` environment variable, then an interactive prompt.
- **password** (character) - Your FAOSTAT account password. Defaults to the `FAOSTAT_PASSWORD` environment variable, then an interactive prompt.
- **base_url** (character) - Base URL for FAOSTAT authentication.

### Examples
```R
# Simplest usage — prompts for credentials interactively if not set:
# crop_production <- get_faostat_bulk(code = "QCL", data_folder = "data_raw")

# Silent usage — set in ~/.Renviron (run usethis::edit_r_environ() to open it):
# FAOSTAT_USER=your@email.com
# FAOSTAT_PASSWORD=yourpassword
# crop_production <- get_faostat_bulk(code = "QCL", data_folder = "data_raw")
```

### Internal Details
This function uses a POST request to the `/auth/login` endpoint with `username` and `password` as form-encoded parameters. It handles authentication and stores the access and refresh tokens in the `.FAOSTATenv` environment.
```

--------------------------------

### Get World Development Indicators Data

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves data from the World Development Indicators (WDI) database. This function is useful for accessing global development statistics.

```r
getWDI(country = "CHN", indicator = "SP.POP.TOTL", start_date = "2020", end_date = "2020")
```

--------------------------------

### Get World Development Indicators Metadata

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves metadata for World Development Indicators (WDI). This function helps in understanding the structure and content of WDI data.

```r
getWDImetaData()
```

--------------------------------

### Loading and Accessing CHMT Function Help in R

Source: https://rdrr.io/cran/FAOSTAT/src/R/CHMT.R

This snippet demonstrates how to load the FAOSTAT library and access the help documentation for the CHMT function in an R environment.

```R
library(FAOSTAT)
help(CHMT)
```

--------------------------------

### Get World Bank WDI Data

Source: https://rdrr.io/cran/FAOSTAT/man/getWDI.html

Use this function to extract data for a specified World Bank indicator. The default indicator is 'SP.POP.TOTL' (Total Population).

```R
getWDI(
  indicator = "SP.POP.TOTL",
  name = NULL,
  startDate = 1960,
  endDate = format(Sys.Date(), "%Y"),
  printURL = FALSE,
  outputFormat = "wide"
)
```

--------------------------------

### R check_country_overlap Function Definition

Source: https://rdrr.io/cran/FAOSTAT/src/R/check_country_overlap.R

Defines the check_country_overlap function which handles country code overlaps and multi-China entries. It includes example usage for different overlap handling strategies.

```R
##' This function perform some check on the data
##'
##' The function only works for FAOST_CODE. If the country coding
##' system is not in FAOST_CODE then use the translateCountryCode
##' function to translate it.
##'
##' @param var The variable to be checked.
##' @param year The column which index the time.
##' @param data The data frame.
##' @param type The type of check.
##' @param take The type of check/replacement to be done in case of
##' type equals to overlap.
##'
##' @export
##' @examples
##' test.df = 
##'    data.frame(FAOST_CODE = rep(c(51,167,199), each = 3), 
##'   Year = rep(c(1990:1992), 3),
##'   Value = c(c(3,4,4), c(2,2,2), c(1,2,NA)))
##' check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "simpleCheck")
##' check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "takeNew")
##' check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "takeOld")
##' check_country_overlap(var = "Value", data = test.df, type = "overlap", take = "complete")

check_country_overlap = function(var, year = "Year", data, 
                    type = c("overlap", "multiChina"),
                    take = c("simpleCheck", "takeNew", "takeOld", "complete")){
    
    if (deparse(match.call()[[1]]) == "FAOcheck") {
        .Deprecated("check_country_overlap", msg = "FAOcheck has deprecated been replaced by check_country_overlap as the old API doesn't work anymore. 
                check_country_overlap was called instead")
    }
    
    type = match.arg(type)
    take = match.arg(take)
    if(type == "overlap"){
        printLab("Check for overlap between transitional country")
        ## Belgium-Luxembourg (old entity, up to 1999 included) vs 
        ## Belgium, LuxemBourg (new entities, from 2000).
        data = overlap(old = 15, new = c(255, 256), 
                       var = var, data = data, take = take)
        ## Czechoslovakia (old entity, up to 1992 included) vs
        ## Czech Republic, Slovakia (new entities, from 1993).
        data = overlap(old = 51, new = c(167, 199), 
                       var = var, data = data, take = take)
        ## Ethiopia PDR (old entity, up to 1992 included) vs 
        ## Eritrea, Ethiopia (new entities, from 1993).
        data = overlap(old = 62, new = c(178, 238), 
                       var = var, data = data, take = take)
        ## Serbia and Montenegro (old entity, up to 2005 included) vs 
        ## Serbia, Montenegro (new entities, from 2006).
        data = overlap(old = 186, new = c(272, 273), 
                       var = var, data = data, take = take)
        ## USSR (old entity, up to 1991 included) vs 
        ## Armenia, Azerbaijan, Belarus, Estonia, Georgia, Kazakistan
        ## Kyrghisistan, Latvia, Lithuania,  Moldova, Russian Federation, 
        ## Tajikistan, Turkmenistan, Ukraine, Uzbekistan (new entities, from 1992).
        data = overlap(old = 228, new = c(1,52,57,63,73,108,113,119,126,146,185,208,213,230,235), 
                       var = var, data = data, take = take)
        ## Yemen (old entities, up to ...) vs 
        ## Yemen (new entities, from ...)
        data = overlap(old = c(246, 247), new = 249, 
                       var = var, data = data, take = take)
        ## Yugoslav SFR (old entity, up to 1991 included) vs 
        ## Serbia e Montenegro, Bosnia and Herzegovina, Croatia,
        ## Slovenia, Macedonia (new entities, from 1992).
        data = overlap(old = 248, new = c(80, 98, 154, 186, 272, 273, 198),
                var = var, data = data, take = take)
        ## Sudan (former) (old entity, up to 2011 included) vs 
        ## Sudan, South Sudan (new entities, from 2012).
        data = overlap(old = 206, new = c(276, 277), 
                       var = var, data = data, take = take)
        ## Netherlands Antilles (old entity, up to 2010 included) vs 
        ## Aruba, Bonaire, Sint Eustatius and Saba, Curacao, 
        ## Sint Maarten (Dutch Part) (new entities, from 2011).
        data = overlap(old = 151, new = c(22,278,279,280), 
                       var = var, data = data, take = take)
        ## Pacific Islands, Trust Territory of (old entity, up to 1990 included) vs 
        ## Micronesia (Federated States of), the Marshall Islands,
        ## Northern Mariana Islands, Palau (new entities, from 1991).
        data = overlap(old = 164, new = c(145,127,163,180), 
                       var = var, data = data, take = take)
        message("NOTE: It is common for data reported by the predecessor\n or the new transitional country to include the new country\n")
    }
    if(type == "multiChina"){
        printLab("Check for existence of multiple China")
        data = CHMT(var = var, data = data, year = year)
    }
    data
}


FAOcheck <- check_country_overlap

```

--------------------------------

### Access FAOSTAT Vignette

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

Opens the package documentation and the main vignette for the FAOSTAT package.

```r
# help(package = "FAOSTAT")
# vignette("FAOSTAT", package = "FAOSTAT")
```

--------------------------------

### Download FAOSTAT Bulk Data from URL

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Downloads a bulk zip file from a given URL and saves it to a specified folder. Use this for direct downloads when the URL is known.

```R
download_faostat_bulk(url_bulk, data_folder = ".")
```

--------------------------------

### Retrieve Data from FAOSTAT API

Source: https://rdrr.io/cran/FAOSTAT/src/R/rest.R

Makes a GET request to a specified FAOSTAT API endpoint. It automatically logs in if no access token is found and handles basic HTTP errors.

```R
get_fao <- function(endpoint, params = list(), language = c("en", "fr", "es", "NA"), base_url = "https://faostatservices.fao.org/api/v1"){

  language = match.arg(language, several.ok = FALSE)

  if (!exists("access_token", envir = .FAOSTATenv)) {
    faostat_login()
  }
  config <- add_headers(Authorization = paste("Bearer", .FAOSTATenv$access_token))
  
  resp <- GET(paste(base_url, language, endpoint, sep = "/"), query = params, config)
  
  if (http_error(resp)) {
    if (status_code(resp) == 404) {
      stop("Error 404 - resource not found. Is something wrong with the URL?")
    }
    stop("Request failed")
  }
  
  return(resp)
  
}

```

--------------------------------

### Download World Bank Data

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

Downloads World Bank data for total population and GDP, along with metadata. Requires the 'WDI' package.

```r
## Download World Bank data and meta-data
# WB.lst = getWDItoSYB(indicator = c("SP.POP.TOTL", "NY.GDP.MKTP.CD"),
#                      name = c("totalPopulation", "GDPUSD"),
#                      getMetaData = TRUE, printMetaData = TRUE)
```

--------------------------------

### Load FAOSTAT and View Help for check_country_overlap

Source: https://rdrr.io/cran/FAOSTAT/src/R/check_country_overlap.R

Loads the FAOSTAT library and displays the help documentation for the check_country_overlap function. This is a common first step when learning about a new function.

```r
library(FAOSTAT)
help(check_country_overlap)
```

--------------------------------

### Download and Inspect Bulk Crop Production Data

Source: https://rdrr.io/cran/FAOSTAT/src/demo/FAOSTATdemo.R

Downloads bulk data for crop production (code 'QC') into a specified folder. It then shows the structure of the downloaded data frame.

```R
# Load crop production data
production_crops <- get_faostat_bulk(code = "QC", data_folder = data_folder)
# Show the structure of the data
str(crop_production)
```

--------------------------------

### Get WDI to SYB Data

Source: https://rdrr.io/cran/FAOSTAT/f

Retrieves and transforms World Development Indicators (WDI) data to a format suitable for the State of Food and Agriculture (SYB) report. This function facilitates data integration.

```r
getWDItoSYB(country = "CHN", indicator = "SP.POP.TOTL", date = "2020")
```

--------------------------------

### download_faostat_bulk

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Loads data from a given URL and saves it to a compressed zip file.

```APIDOC
## download_faostat_bulk

### Description
Loads data from the given url and saves it to a compressed zip file.

### Usage
download_faostat_bulk(url_bulk, data_folder = ".")

### Arguments
* `url_bulk` (character): URL of the faostat bulk zip file to download.
* `data_folder` (character): Path of the local folder where to download the data.

### Value
Data frame of FAOSTAT data.
```

--------------------------------

### Login to FAOSTAT API

Source: https://rdrr.io/cran/FAOSTAT/src/R/rest.R

Authenticates with the FAOSTAT API and stores the access token. Credentials can be provided as arguments, environment variables, or interactively. API calls trigger this automatically if no token is present.

```R
faostat_login <- function(username = Sys.getenv("FAOSTAT_USER"),
                          password = Sys.getenv("FAOSTAT_PASSWORD"),
                          base_url = "https://faostatservices.fao.org/api/v1"){
  if (nchar(username) == 0) {
    message("Please login to the FAOSTAT API")
    username <- readline("FAOSTAT email: ")
  }
  if (nchar(password) == 0) {
    if (requireNamespace("rstudioapi", quietly = TRUE) && rstudioapi::isAvailable()) {
      password <- rstudioapi::askForPassword("FAOSTAT password")
    } else {
      password <- readline("FAOSTAT password: ")
    }
  }

  auth_url <- paste0(base_url, "/auth/login")

  # The API documentation says:
  # HTTP Method: POST
  # Content-Type: application/x-www-form-urlencoded
  # Request Parameters (Body): username, password

  resp <- httr::POST(auth_url,
                     body = list(username = username, password = password),
                     encode = "form")

  if (httr::http_error(resp)) {
    stop("Login failed. Check your username and password.")
  }

  auth_data <- httr::content(resp)

  # The response structure is nested: {"AuthenticationResult": {"AccessToken": "...", ...}}
  auth_result <- auth_data$AuthenticationResult

  if (!is.null(auth_result) && !is.null(auth_result$AccessToken)) {
    .FAOSTATenv$access_token <- auth_result$AccessToken
    if (!is.null(auth_result$RefreshToken)) {
      .FAOSTATenv$refresh_token <- auth_result$RefreshToken
    }
    message("Successfully logged in to FAOSTAT.")
  } else {
    stop("Could not retrieve access token from response. Structure might have changed.")
  }

  invisible(auth_data)
}

```

--------------------------------

### FAOSTAT Login Function Signature

Source: https://rdrr.io/cran/FAOSTAT/man/faostat_login.html

This snippet shows the default usage of the faostat_login function, including its arguments and how they resolve credentials.

```R
faostat_login(
  username = Sys.getenv("FAOSTAT_USER"),
  password = Sys.getenv("FAOSTAT_PASSWORD"),
  base_url = "https://faostatservices.fao.org/api/v1")


```

--------------------------------

### Constructing New Variables with FAOSTAT

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

This snippet shows how to define and construct new statistical variables using the `constructSYB` function based on a data frame of construction rules. It is useful for creating derived indicators like growth rates or shares from raw data.

```r
con.df = data.frame(STS_ID = c("arableLandPC", "arableLandShareOfTotal",
                                "totalPopulationGeoGR", "totalPopulationLsGR",
                                "totalPopulationInd", "totalPopulationCh"),
                    STS_ID_CONSTR1 = c(rep("arableLand", 2),
                                       rep("totalPopulation", 4)),
                    STS_ID_CONSTR2 = c("totalPopulation", NA, NA, NA, NA, NA),
                    STS_ID_WEIGHT = rep("totalPopulation", 6),
                    CONSTRUCTION_TYPE = c("share", "share", "growth", "growth",
                                          "index", "change"),
                    GROWTH_RATE_FREQ = c(NA, NA, 10, 10, NA, 1),
                    GROWTH_TYPE = c(NA, NA, "geo", "ls", NA, NA),
                    BASE_YEAR = c(NA, NA, NA, NA, 2000, NA),
                    AGGREGATION = rep("weighted.mean", 6),
                    THRESHOLD_PROP = rep(60, 6),
                    stringsAsFactors = FALSE)

postConstr.lst = with(con.df,
                      constructSYB(data = preConstr.df,
                                   origVar1 = STS_ID_CONSTR1,
                                   origVar2 = STS_ID_CONSTR2,
                                   newVarName = STS_ID,
                                   constructType = CONSTRUCTION_TYPE,
                                   grFreq = GROWTH_RATE_FREQ,
                                   grType = GROWTH_TYPE,
                                   baseYear = BASE_YEAR))
```

--------------------------------

### Download FAOSTAT Bulk Data

Source: https://rdrr.io/cran/FAOSTAT/f

Use this function to download bulk data from FAOSTAT. Ensure you have the necessary credentials if required.

```r
download_faostat_bulk(data_path = "/datasets/", data_name = "FS_TCL")
```

--------------------------------

### Alias for FAOSTAT Bulk API Download

Source: https://rdrr.io/cran/FAOSTAT/src/R/faostat_bulk_download.R

Provides an alias for the `get_faostat_bulk_api` function, simplifying access to FAOSTAT bulk data.

```R
get_faostat_bulk <- get_faostat_bulk_api
```

--------------------------------

### Cache and Load FAOSTAT Data using RDS

Source: https://rdrr.io/cran/FAOSTAT/src/demo/FAOSTATdemo.R

Saves the downloaded crop production data frame to an RDS file for faster reuse. It then demonstrates how to load the data back from the local RDS file.

```R
# Cache the file i.e. save the data frame in the serialized RDS format for fast reuse later.
saveRDS(production_crops, "data_raw/production_crops_e_all_data.rds")
# Now you can load your local version of the data from the RDS file
production_crops <- readRDS("data_raw/production_crops_e_all_data.rds")
```

--------------------------------

### get_faostat_bulk_url

Source: https://rdrr.io/cran/FAOSTAT/man/download_faostat_bulk.html

Downloads a bulk zip file from a URL and reads it into a data frame in one step.

```APIDOC
## get_faostat_bulk_url

### Description
Downloads a bulk zip file from a URL and reads it into a data frame in one step.

### Usage
get_faostat_bulk_url(url_bulk, data_folder = ".")

### Arguments
* `url_bulk` (character): URL of the faostat bulk zip file to download.
* `data_folder` (character): Path of the local folder where to download the data.

### Value
Data frame of FAOSTAT data.
```

--------------------------------

### Download FAOSTAT Data via API using Dataset Code

Source: https://rdrr.io/cran/FAOSTAT/src/R/faostat_bulk_download.R

Retrieves FAOSTAT data by dataset code. It first fetches metadata to find the correct URL, then downloads and reads the data.

```R
get_faostat_bulk_api <- function(code, data_folder = tempdir(), subset = "All Data Normalized"){

    dir.create(data_folder, showWarnings = FALSE, recursive = TRUE)

    # Load information about the given dataset code
    metadata <- read_bulk_metadata(dataset_code = code)

    metadata_url = metadata[metadata$FileContent == subset, "URL"]

    # Use the result of the search to download the data and assign it to a data frame
    download_faostat_bulk(url_bulk = metadata_url, data_folder = data_folder)
    output <- read_faostat_bulk(file.path(data_folder, basename(metadata_url)))
    return(output)
}
```

--------------------------------

### Download FAOSTAT Bulk Data

Source: https://rdrr.io/cran/FAOSTAT/src/R/faostat_bulk_download.R

Downloads a specified FAOSTAT bulk zip file from a URL to a local folder. It handles authentication and provides progress feedback. Use this for downloading raw zip files.

```R
download_faostat_bulk <- function(url_bulk, data_folder = "."){
    file_name <- basename(url_bulk)
    dest_path <- file.path(data_folder, file_name)

    if (!exists("access_token", envir = .FAOSTATenv)) {
      faostat_login()
    }
    config <- add_headers(Authorization = paste("Bearer", .FAOSTATenv$access_token))

    # Use httr::GET to download so we can include headers
    resp <- GET(url_bulk, config, write_disk(dest_path, overwrite = TRUE), progress())

    if (http_error(resp)) {
      stop(sprintf("Failed to download file from %s. Status: %d", url_bulk, status_code(resp)))
    }

    return(dest_path)
}
```

--------------------------------

### Download FAO Bulk Data via URL

Source: https://rdrr.io/cran/FAOSTAT/src/inst/doc/FAOSTAT.R

Downloads a specified bulk data zip file from a FAO URL and saves it to a specified data folder.

```r
# library(FAOSTAT)
# df <- get_faostat_bulk_url("https://bulks-faostat.fao.org/production/Inputs_LandUse_E_All_Data_(Normalized).zip",
#                             data_folder = "data_raw")
```