### Install TongFen Package

Source: https://github.com/mountainmath/tongfen/blob/main/docs/index.html

Instructions for installing the tongfen package from CRAN or the development version from GitHub.

```R
install.packages("tongfen")
remotes::install_github("mountainmath/tongfen")
library(tongfen)
```

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

### Example Usage of get_tongfen_ca_census

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_ca_census.html

Demonstrates how to define census variables, retrieve metadata, and call the tongfen function to estimate rent data across multiple census years.

```R
rent_variables <- c(rent_2001="v_CA01_1667",rent_2016="v_CA16_4901",
                    rent_2011="v_CA11N_2292",rent_2006="v_CA06_2050")
meta <- meta_for_ca_census_vectors(rent_variables)

regions=list(CMA="59933")
rent_data <- get_tongfen_ca_census(regions=regions, meta=meta, quiet=TRUE,
                                   method="estimate", level="CT", base_geo = "CA16")
```

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

### Proportionally re-aggregate census data

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/proportional_reaggregate.html

This example demonstrates how to use proportional_reaggregate to distribute dissemination area (DA) census data down to the dissemination block (DB) level using population as a weighting factor.

```R
regions <- list(CSD="5915022")
variables <- cancensus::child_census_vectors("v_CA16_3954")

da_data <- cancensus::get_census("CA16",regions=regions,
                                 vectors=setNames(variables$vector,variables$label),
                                 level="DA")
geo_data <- cancensus::get_census("CA16",regions=regions,geo_format="sf",level="DB")

db_data <- geo_data %>% proportional_reaggregate(da_data,c("DA_UID"="GeoUID"),variables$label)
```

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

### Aggregate Census Data using tongfen_aggregate

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/tongfen_aggregate.html

This example demonstrates how to aggregate census tract population data from 2006 and 2016 for the City of Vancouver. It requires a list of datasets, a correspondence object, and metadata defining the aggregation rules.

```R
regions <- list(CSD="5915022")
geo1 <- cancensus::get_census("CA06",regions=regions,geo_format='sf',level='CT')
geo2 <- cancensus::get_census("CA16",regions=regions,geo_format='sf',level='CT')
meta <- meta_for_additive_variables("CA06","Population")
correspondence <- get_tongfen_correspondence_ca_census(geo_datasets=c('CA06','CA16'),
                                                       regions=regions,level='CT')
result <- tongfen_aggregate(list(geo1 %>% rename(GeoUIDCA06=GeoUID),
                                 geo2 %>% rename(GeoUIDCA16=GeoUID)),correspondence,meta)
```

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

### Estimate Canadian Census Data for Custom Geometry

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/tongfen_estimate_ca_census.html

This example demonstrates how to use tongfen_estimate_ca_census to estimate population data within a 1km radius of a specific point. It requires defining a geometry, setting census metadata, and specifying the geographic levels for intersection.

```R
toronto_city_hall <- sf::st_point(c(-79.3839,43.6534)) %>%
  sf::st_sfc(crs=4326) %>%
  sf::st_transform(3348) %>%
  sf::st_buffer(1000) %>%
  sf::st_sf()

meta <- meta_for_additive_variables("CA16","Population")

data <- tongfen_estimate_ca_census(toronto_city_hall,meta,level="DA",intersection_level="CT")

print(paste0("Approximately ",scales::comma(data$Population,accuracy=100),
             " people live within a 1 km radius of Toronto City."))
```

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

### Estimate TongFen Correspondence for Canadian Census Data

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/estimate_tongfen_correspondence.html

This example demonstrates how to use estimate_tongfen_correspondence to reconcile 2006 and 2016 dissemination area geometries in Vancouver. It retrieves census data using the cancensus package and generates a correspondence table linking the two datasets.

```R
regions <- list(CSD="5915022")
data_06 <- cancensus::get_census("CA06", regions=regions, geo_format='sf', level="DA") %>%
  rename(GeoUID_06=GeoUID)
data_16 <- cancensus::get_census("CA16", regions=regions, geo_format="sf", level="DA") %>%
  rename(GeoUID_16=GeoUID)

correspondence <- estimate_tongfen_correspondence(list(data_06, data_16), c("GeoUID_06", "GeoUID_16"))
```

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

### Estimate Census Data on Custom Geographies

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/tongfen_estimate.html

This example demonstrates how to use tongfen_estimate to interpolate 2006 Canadian census population data onto 2016 census geographies. It requires the cancensus package to fetch source and target data and metadata defining the aggregation method.

```R
geo1 <- cancensus::get_census("CA06",regions=list(CSD="5915022"),geo_format='sf',level='DA')
geo2 <- cancensus::get_census("CA16",regions=list(CSD="5915022"),geo_format='sf',level='DA')
meta <- meta_for_additive_variables("CA06","Population")
result <- tongfen_estimate(geo2 %>% rename(Population_2016=Population),geo1,meta)
```

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

### Get US Census Data with tongfen

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_us_census.html

This function retrieves US census data for specified regions and variables for the 2000 and 2010 censuses. It utilizes the tidycensus package and standardizes the geography to a common level like 'tract' or 'county subdivision'. The output is an sf object containing census variables with year suffixes.

```R
get_tongfen_us_census(
  regions,
  meta,
  level = "tract",
  survey = "census",
  base_geo = NULL
)
```

```R
variables=c(population="H011001",households="H013001")

meta <- c(2000,2010) %>%
  lapply(function(year){
    v <- variables %>% setNames(paste0(names(.),"_",year))
    meta_for_additive_variables(paste0("dec",year),v)
  }) %>%
  bind_rows()
census_data <- get_tongfen_us_census(regions = list(state="CA"), meta=meta, level="tract") %>%
  mutate(change=population_2010/households_2010-population_2000/households_2000)
```

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

### Get TongFen Census CT Data (R)

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_census_ct.html

Retrieves census variables from multiple Canadian censuses on a common Census Tract (CT) geography. Requires the 'sf' package. It takes census regions and vectors as input and can return data in 'sf' format. Optional arguments control NA value handling, output verbosity, and data cache refreshing.

```R
get_tongfen_census_ct(
  regions,
  vectors,
  geo_format = NA,
  na.rm = TRUE,
  quiet = TRUE,
  refresh = FALSE
)
```

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

### Estimate Canadian Census Data on Custom Geographies with R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen-ca-estimate.html

This R code snippet demonstrates the full pipeline to estimate census data on custom geographies using the `tongfen_estimate_ca_census` function. It requires the `tongfen` and `ggplot2` libraries, and uses `cancensus` for geographic data. The example estimates the share of people in low income within Vancouver's skytrain station neighborhoods.

```R
library(tongfen)
library(ggplot2)

station_buffers <- cancensus::COV_SKYTRAIN_STATIONS

meta <- meta_for_ca_census_vectors(c(limat = "v_CA16_2540"))
station_data <- tongfen_estimate_ca_census(station_buffers, meta, level = "DA", intersection_level = "CT", 
                                               quiet=TRUE, na.rm = TRUE)

cov_background <- cancensus::get_census("CA16", regions=list(CSD="5915022"), geo_format = "sf", quiet=TRUE)

ggplot(station_data) +
  geom_sf(data=cov_background) +
  geom_sf(aes(fill=limat/100), alpha=0.7) +
  scale_fill_viridis_c(labels=scales::percent) +
  coord_sf(datum=NA) +
  labs(title="Share of people in low icome in Vancouver Skytrain station neighbourhoods",
       fill="Share of people\nin LIM-AT",
       caption="StatCan Census 2016")
```

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

### Basic TongFen Workflow (R)

Source: https://github.com/mountainmath/tongfen/blob/main/README.md

Outlines the fundamental three-step workflow for using the 'tongfen' package: 1. Generate a correspondence table between diverse geographies. 2. Create metadata for variable aggregation. 3. Aggregate datasets onto a common geography.

```R
# 1. Generate correspondence table
estimate_tongfen_correspondence(...)

# 2. Generate metadata for additive variables
meta_for_additive_variables(...)

# 3. Aggregate data onto a common geography
tongfen_aggregate(...)
```

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

### GET get_tongfen_census_ct

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_census_ct.html

Retrieves Canadian census data at the Census Tract (CT) level, aggregating variables from multiple census years onto a unified geographic base.

```APIDOC
## GET get_tongfen_census_ct

### Description
Retrieves and aggregates Canadian census variables from multiple census years onto a common geography at the Census Tract (CT) level.

### Method
GET

### Endpoint
get_tongfen_census_ct(regions, vectors, geo_format, na.rm, quiet, refresh)

### Parameters
#### Path Parameters
- **regions** (list) - Required - A list of census GeoUIDs that cover the regions across the desired census years.
- **vectors** (list) - Required - A list of cancensus vectors, potentially spanning different census years.

#### Query Parameters
- **geo_format** (string) - Optional - The geographic format for returned data; use 'sf' for sf object format.
- **na.rm** (boolean) - Optional - Whether to remove NA values during aggregation. Default is TRUE.
- **quiet** (boolean) - Optional - Suppress download progress output. Default is FALSE.
- **refresh** (boolean) - Optional - Force a refresh of the data cache for this specific call.

### Request Example
get_tongfen_census_ct(regions = c("59015"), vectors = c("v_CA16_408"), geo_format = "sf")

### Response
#### Success Response (200)
- **dataframe** (object) - A dataframe containing the requested census variables mapped to the common geography.

#### Response Example
{
  "data": "dataframe_object",
  "geography": "sf_object"
}
```

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

### Working with Election Data

Source: https://context7.com/mountainmath/tongfen/llms.txt

Demonstrates how to load, process, and aggregate election data using tongfen, including estimating correspondence between polling districts.

```APIDOC
## Working with Election Data

### Description
This example demonstrates how to load bundled election data, estimate correspondence between polling districts from different years, and aggregate vote data to a common geography.

### Methods
- `estimate_tongfen_correspondence`

### Request Example
```r
library(tongfen)
library(dplyr)
library(sf)

# Load bundled Vancouver election data
data("vancouver_elections_data_2015", package = "tongfen")
data("vancouver_elections_data_2019", package = "tongfen")
data("vancouver_elections_geos_2015", package = "tongfen")
data("vancouver_elections_geos_2019", package = "tongfen")

# Estimate correspondence between polling districts
correspondence <- estimate_tongfen_correspondence(
  data = list(vancouver_elections_geos_2015, vancouver_elections_geos_2019),
  geo_identifiers = c("PD_2015", "PD_2019"),
  method = "estimate",
  tolerance = 30  # 30 metre tolerance
)

# Aggregate vote data to common geography
vote_data <- correspondence %>%
  left_join(vancouver_elections_data_2019 %>%
              select(PD_2019, Party, Votes_2019 = Votes),
            by = "PD_2019") %>%
  left_join(vancouver_elections_data_2015 %>%
              select(PD_2015, Party, Votes_2015 = Votes),
            by = c("PD_2015", "Party")) %>%
  group_by(TongfenID, Party) %>%
  summarize(
    Votes_2019 = sum(Votes_2019, na.rm = TRUE),
    Votes_2015 = sum(Votes_2015, na.rm = TRUE),
    .groups = "drop"
  )

# Create base geography from 2019 polling districts
base_geo <- vancouver_elections_geos_2019 %>%
  left_join(correspondence, by = "PD_2019") %>%
  group_by(TongfenID) %>%
  summarise()
```
```

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

### Get StatCan DA or DB level correspondence file

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_single_correspondence_ca_census_for.html

Retrieves a correspondence file between different geographic levels (DA or DB) for a specified census year from StatCan.

```APIDOC
## GET /correspondence/ca/census

### Description
Retrieves a correspondence file for StatCan Dissemination Areas (DA) or Census Subdivisions (DB) for a given census year. This is useful for mapping or aggregating census data between different geographic granularities.

### Method
GET

### Endpoint
/correspondence/ca/census

### Query Parameters
- **year** (integer) - Required - The census year for which to retrieve the correspondence file. Supported years are 2006 through 2021.
- **level** (string) - Optional - The geographic level to retrieve. Accepts 'DA' for Dissemination Areas or 'DB' for Census Subdivisions. Defaults to 'DA' if not specified.
- **refresh** (boolean) - Optional - If TRUE, forces a reload of the correspondence files. Defaults to FALSE.

### Response
#### Success Response (200)
- **correspondence_table** (tibble) - A data frame containing the correspondence mapping between the specified geographic levels for the given year.

#### Response Example
```json
{
  "correspondence_table": [
    {"from_geography_code": "1010001", "to_geography_code": "101"},
    {"from_geography_code": "1010002", "to_geography_code": "101"}
    // ... more rows
  ]
}
```
```

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

### Get US Census Data

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_us_census.html

Retrieves US census data for specified regions and variables for the 2000 and 2010 censuses, aggregated to a common geography (e.g., census tracts).

```APIDOC
## GET /api/us_census

### Description
Retrieves US census data for 2000 and 2010 on common census tract based geography.

### Method
GET

### Endpoint
/api/us_census

### Parameters
#### Query Parameters
- **regions** (list) - Required - List containing regions to query data for (e.g., `list(state=c("CA","OR"))`).
- **meta** (list) - Required - Metadata for variables to retrieve.
- **level** (string) - Optional - Aggregation level for the data. Supported options: 'tract', 'county subdivision'. Defaults to 'tract'.
- **survey** (string) - Optional - Survey to get data for. Supported option: 'census'. Defaults to 'census'.
- **base_geo** (integer) - Optional - Census year to use as the base geography. Defaults to 2010.

### Request Example
```json
{
  "regions": {"state": ["CA", "OR"]},
  "meta": [
    {
      "survey": "dec2000",
      "variables": {
        "population_2000": "H011001",
        "households_2000": "H013001"
      }
    },
    {
      "survey": "dec2010",
      "variables": {
        "population_2010": "H011001",
        "households_2010": "H013001"
      }
    }
  ],
  "level": "tract",
  "survey": "census",
  "base_geo": 2010
}
```

### Response
#### Success Response (200)
- **sf object** (object) - An sf object containing the census variables with the census year as a suffix.

#### Response Example
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "GEOID": "06001400100",
        "population_2000": 1500,
        "households_2000": 500,
        "population_2010": 1600,
        "households_2010": 550,
        "change": 0.06666666666666667
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-122.419, 37.7749],
            [-122.418, 37.7749],
            [-122.418, 37.7759],
            [-122.419, 37.7759],
            [-122.419, 37.7749]
          ]
        ]
      }
    }
  ]
}
```
```

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

### Caching Configuration

Source: https://context7.com/mountainmath/tongfen/llms.txt

Explains how to configure caching for correspondence files to avoid repeated downloads.

```APIDOC
## Caching Configuration

### Description
Configure caching to avoid repeated downloads of correspondence files.

### Methods
Several methods can be used to configure the cache path:

1.  **Set in `.Rprofile`**: Add the following line to your `.Rprofile` file:
    ```r
    options("tongfen.cache_path" = "~/.tongfen_cache")
    ```

2.  **Set environment variable in `.Renviron`**: Add the following line to your `.Renviron` file:
    ```
tongfen.cache_path=~/.tongfen_cache
    ```

3.  **Use shared cache with other packages**: Specify a custom data path that can be shared:
    ```r
    options("custom_data_path" = "~/data_cache")
    ```
```

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

### Estimate and Visualize Rent Changes in R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen_ca.html

This snippet demonstrates how to retrieve census data for multiple years, harmonize it using tongfen, calculate percentage changes in rent, and visualize the results using ggplot2.

```R
library(dplyr)
library(ggplot2)
library(tidyr)
library(cancensus)
library(sf)
library(tongfen)

rent_variables <- c(rent_2001="v_CA01_1667",rent_2016="v_CA16_4901",rent_2011="v_CA11N_2292",rent_2006="v_CA06_2050")
meta <- meta_for_ca_census_vectors(rent_variables) 
regions=list(CMA="59933")
rent_data <- get_tongfen_ca_census(regions=regions, meta=meta, quiet=TRUE, method="estimate", level="CT", base_geo = "CA16")

periods <- c("2001-2006","2006-2011","2011-2016","2001-2016")
plot_data <- rent_data %>%
  mutate(`2001-2006`=rent_2006/rent_2001-1,
         `2006-2011`=rent_2011/rent_2006-1,
         `2011-2016`=rent_2016/rent_2011-1,
         `2001-2016`=rent_2016/rent_2001-1) %>%
  pivot_longer(cols = all_of(periods), names_to="Period",values_to="Change") %>%
  mutate(Period=factor(Period,level=periods)) %>%
  st_sf()

ggplot(plot_data,aes(fill=Change)) + 
  geom_sf(size=0.1) + 
  scale_fill_gradient2(labels=scales::percent) + 
  facet_wrap("Period",ncol=2)
```

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

### Configure TongFen Caching (R)

Source: https://github.com/mountainmath/tongfen/blob/main/README.md

Explains how to set up persistent caching for StatCan correspondence files used by 'tongfen' functions like `get_tongfen_census_ct`. This speeds up repeated downloads by specifying a local cache path.

```R
options("tongfen.cache_path"="<your local cache path>")
# or
Sys.setenv("tongfen.cache_path"="<your local cache path>")
# or
options("custom_data_path"="<your local cache path>")
```

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

### Get StatCan DA or DB level correspondence file

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_correspondence_ca_census_for.html

Retrieves the StatCan correspondence files for Data Analysis Region (DA) or Dissemination Block (DB) levels for specified census years. This function is deprecated.

```APIDOC
## GET /api/correspondence/ca/census

### Description
Retrieves StatCan correspondence files for DA or DB levels for specified census years. This function is deprecated and intended for internal use within the TongFen package.

### Method
GET

### Endpoint
/api/correspondence/ca/census

### Parameters
#### Query Parameters
- **years** (list) - Required - A list of census years for which to retrieve correspondence files.
- **level** (string) - Required - The geographic level, either 'DA' (Data Analysis Region) or 'DB' (Dissemination Block).
- **refresh** (boolean) - Optional - If TRUE, forces a reload of the correspondence files. Defaults to FALSE.

### Request Example
GET /api/correspondence/ca/census?years=c(2016, 2021)&level=DA&refresh=true

### Response
#### Success Response (200)
- **correspondence_table** (tibble) - A tibble containing the correspondence table spanning all requested years.

#### Response Example
```json
{
  "correspondence_table": [
    {
      "year": 2016,
      "DA_CODE_2016": "10100001",
      "DA_NAME_2016": "Sample DA Name 2016",
      "DA_CODE_2021": "10100001",
      "DA_NAME_2021": "Sample DA Name 2021"
    }
  ]
}
```
```

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

### Configure tongfen caching

Source: https://context7.com/mountainmath/tongfen/llms.txt

Provides methods to configure caching paths to prevent redundant downloads of correspondence files. Options include setting R profile options or environment variables.

```r
options("tongfen.cache_path" = "~/.tongfen_cache")
# tongfen.cache_path=~/.tongfen_cache
options("custom_data_path" = "~/data_cache")
```

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

### Configure TongFen Cache Path

Source: https://github.com/mountainmath/tongfen/blob/main/docs/index.html

Setting up a local cache path for StatCan correspondence files to improve performance and avoid repeated downloads.

```R
options("tongfen.cache_path"="<your local cache path>")
Sys.setenv("tongfen.cache_path"="<your local cache path>")
options("custom_data_path"="<your local cache path>")
```

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

### Create Metadata for Additive Variables (R)

Source: https://github.com/mountainmath/tongfen/blob/main/README.md

A convenience function to generate the necessary metadata table for aggregating additive variables within the 'tongfen' package. This simplifies the process of preparing data for comparison.

```R
meta_for_additive_variables(...)
```

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

### Get Canadian Census DA Level Tongfen Data

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_census_da.html

Retrieves census variables from multiple censuses on a common geography at the Census Dissemination Area (DA) level. Requires the `sf` package. It can return data as a dataframe or an `sf` object if `geo_format` is set to 'sf'.

```R
get_tongfen_census_da(
  regions,
  vectors,
  geo_format = NA,
  use_cache = TRUE,
  na.rm = TRUE,
  quiet = TRUE
)
```

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

### Aggregate Census Data for Custom Regions

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen_ca.html

Shows how to aggregate specific census variables for custom defined regions (like school districts) using the aggregate_data_with_meta function.

```R
vectors <- c("v_CA16_4836","v_CA16_4838","v_CA16_4899")
meta=meta_for_ca_census_vectors(vectors) %>%
  bind_rows(meta_for_additive_variables("CA16",c("Population","Dwellings","Households")))
vsb_regions <- list(CSD=c("5915022","5915803"), CT=c("9330069.01","9330069.02","9330069.00"))
vsb <- get_census("CA16",regions=vsb_regions,vectors=meta$variable,labels="short")
vsb <- aggregate_data_with_meta(vsb, meta) %>%
  mutate(Total=v_CA16_4836,Renters=v_CA16_4838,rent_poor=v_CA16_4899/100) %>%
  mutate(rent_share=Renters/Total)
```

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

### Get TongFen Census DA

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_census_da.html

Retrieves Canadian Census Dissemination Area level data for specified regions and vectors, allowing for data aggregation across different census years onto a common geography. It can optionally return geographic data in sf format.

```APIDOC
## GET /tongfen/census/da

### Description
Retrieves Canadian Census Dissemination Area (DA) level data for specified regions and vectors. This function allows for the aggregation of variables from multiple census years onto a common geography. It requires the `sf` package to be installed if geographic data is requested.

### Method
GET

### Endpoint
`/tongfen/census/da`

### Parameters
#### Query Parameters
- **regions** (list) - Required - A list of GeoUIDs inclusive of all desired census years.
- **vectors** (list) - Required - A list of cancensus vectors, potentially from different census years.
- **geo_format** (string) - Optional - Set to 'sf' to also retrieve geographic data. Defaults to NA (only variables).
- **use_cache** (boolean) - Optional - Logical value passed to `cancensus::get_census` to control caching. Defaults to TRUE.
- **na.rm** (boolean) - Optional - Determines how NA values are treated during variable aggregation. Defaults to TRUE.
- **quiet** (boolean) - Optional - Suppresses download progress output. Defaults to TRUE.

### Request Example
```json
{
  "regions": ["10100001", "10100002"],
  "vectors": ["1.1.1.1", "2.2.2.2"],
  "geo_format": "sf",
  "use_cache": true,
  "na.rm": true,
  "quiet": false
}
```

### Response
#### Success Response (200)
- **data** (dataframe) - A dataframe containing the requested census variables aggregated on a common geography. If `geo_format` is 'sf', this will include an 'geometry' column.

#### Response Example
```json
{
  "data": [
    {
      "GeoUID": "10100001",
      "variable1": 100,
      "variable2": 50,
      "geometry": "..."
    }
  ]
}
```
```

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

### Core Functions - meta_for_additive_variables

Source: https://context7.com/mountainmath/tongfen/llms.txt

Generates metadata for aggregating additive variables (like counts) during TongFen operations.

```APIDOC
## meta_for_additive_variables

### Description
Generates metadata specifying how additive variables (like counts) should be aggregated during TongFen operations.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```r
library(tongfen)
library(dplyr)

# Create metadata for population counts across multiple census years
meta <- meta_for_additive_variables(
  dataset = c("CA06", "CA16"),
  variables = "Population"
)

# With named variables for clearer output labels
meta <- meta_for_additive_variables(
  dataset = c("2001", "2006", "2011", "2016"),
  variables = c(pop_2001 = "Population", pop_2006 = "Population",
                pop_2011 = "Population", pop_2016 = "Population")
)
```

### Response
#### Success Response (200)
Returns metadata object for aggregation.

#### Response Example
```r
# Example metadata object structure (simplified)
# list(
#   list(dataset = "CA06", variable = "Population", aggregation_method = "sum"),
#   list(dataset = "CA16", variable = "Population", aggregation_method = "sum")
# )
```
```

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

### Get StatCan DA or DB Level Correspondence - R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_correspondence_ca_census_for.html

Retrieves the StatCan correspondence files for Data Areas (DA) or Dissemination Blocks (DB) across specified census years. This function is useful for joining or comparing census data from different years. It can optionally reload the correspondence files if the refresh argument is set to TRUE.

```R
get_correspondence_ca_census_for <- function(years, level, refresh = FALSE) {
  # Function body to retrieve correspondence files
}
```

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

### Prepare US Census Metadata with R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen_us.html

This code snippet prepares the metadata required for fetching US census data. It defines population and household variables for two different years (2000 and 2010) and structures them for use with the `meta_for_additive_variables` function. The output is a tibble containing variable details, dataset names, and aggregation rules.

```R
library(tongfen)
library(dplyr)
library(ggplot2)

variables=c(population="H011001",households="H013001")

meta <- c(2000,2010) %>%
  lapply(function(year){
      v <- variables %>% setNames(paste0(names(.),"_",year))
      meta_for_additive_variables(paste0("dec",year),v)
    }) %>%
  bind_rows()
meta
```

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

### Aggregate Data with Metadata

Source: https://context7.com/mountainmath/tongfen/llms.txt

Shows how to aggregate grouped census data using metadata rules, including geometry aggregation.

```APIDOC
## Aggregate Data with Metadata

### Description
Aggregates grouped census data using metadata rules. Can optionally aggregate geometry.

### Method
`aggregate_data_with_meta`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **geo** (boolean) - If TRUE, also aggregate geometry. Defaults to FALSE.
- **na.rm** (boolean) - If TRUE, remove NA values before aggregation. Defaults to FALSE.
- **quiet** (boolean) - If TRUE, suppress messages. Defaults to FALSE.

#### Request Body
- **meta** (object) - Metadata object generated by `meta_for_additive_variables`.

### Request Example
```r
# Get DA-level data
geo <- get_census("CA06",
                  regions = list(CSD = "5915022"),
                  geo_format = 'sf',
                  level = 'DA')

# Create metadata
meta <- meta_for_additive_variables("CA06", "Population")

# Aggregate to census tract level
result <- geo %>%
  group_by(CT_UID) %>%
  aggregate_data_with_meta(
    meta = meta,
    geo = TRUE,      # Also aggregate geometry
    na.rm = TRUE,
    quiet = FALSE
  )
```
```

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

### Get Canadian Census CT Data from DA Correspondence (R)

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/get_tongfen_ca_census_ct_from_da.html

Retrieves Canadian census variables at the Census Tract (CT) level using Dissemination Area (DA) correspondence. This function requires the 'sf' package and can return data with or without geographic information. It supports fetching data from multiple census years and handles NA values during aggregation.

```R
get_tongfen_ca_census_ct_from_da(
  regions,
  vectors,
  geo_format = NA,
  use_cache = TRUE,
  na.rm = TRUE,
  quiet = TRUE
)
```

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

### Build Metadata for Census Variables

Source: https://context7.com/mountainmath/tongfen/llms.txt

Builds rich metadata for Canadian census variables, including aggregation rules and parent variables for averages, using the CensusMapper API.

```R
library(tongfen)
vectors <- c(pop = "v_CA16_1", median_income = "v_CA16_2397", avg_rooms = "v_CA16_4861")
meta <- meta_for_ca_census_vectors(vectors)
print(meta)
```

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

### Generate Metadata for Additive Variables

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/meta_for_additive_variables.html

Generates metadata required for the `tongfen_aggregate` function. This is useful for variables that represent additive quantities like counts.

```APIDOC
## meta_for_additive_variables

### Description
Generates metadata to be used in `tongfen_aggregate`. Variables need to be additive like counts.

### Method
`meta_for_additive_variables(dataset, variables)`

### Parameters
#### Arguments
- **dataset** (character vector) - identifier for the dataset containing the variable
- **variables** (named character vector) - vector with additive variables

### Value
Returns a tibble to be used in `tongfen_aggregate`.

### Examples
```R
# Get metadata for additive variable Population for the CA16 and CA06 datasets
if (FALSE) {
  meta <- meta_for_additive_variables(c("CA06","CA16"),"Population")
}
```
```

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

### Proportional Reaggregation

Source: https://context7.com/mountainmath/tongfen/llms.txt

Demonstrates how to proportionally reaggregate DA (Dissemination Area) data to DB (Database) level based on population.

```APIDOC
## Proportional Reaggregation

### Description
Proportionally reaggregates DA data to DB level based on population.

### Method
`proportional_reaggregate`

### Parameters
#### Request Body
- **parent_data** (data.frame) - The parent geographic data to aggregate to.
- **geo_match** (character vector) - A named vector specifying the geographic identifiers to match between parent and child data (e.g., c("DA_UID" = "GeoUID")).
- **categories** (character vector) - The variables (labels) to reaggregate.
- **base** (character) - The variable to use as a base for proportional reaggregation (e.g., "Population").

### Request Example
```r
db_data <- db_geo %>%
  proportional_reaggregate(
    parent_data = da_data,
    geo_match = c("DA_UID" = "GeoUID"),
    categories = variables$label,
    base = "Population"  # Weight by population
  )
```
```

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

### Generate Metadata for Additive Variables with R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/meta_for_additive_variables.html

The meta_for_additive_variables function generates metadata required for the tongfen_aggregate function. It takes a dataset identifier and a vector of additive variables as input and returns a tibble suitable for aggregation. Ensure variables are additive, like counts.

```R
meta_for_additive_variables(dataset, variables)
```

```R
meta <- meta_for_additive_variables(c("CA06","CA16"),"Population")
```

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

### POST /tongfen_estimate

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/tongfen_estimate.html

Estimates data from source geometry onto target geometry using area-weighted interpolation.

```APIDOC
## POST /tongfen_estimate

### Description
Estimates data from source geometry onto target geometry using area-weighted interpolation. It supports additive data like population counts and weighted averages.

### Method
POST

### Endpoint
/tongfen_estimate

### Parameters
#### Request Body
- **target** (object) - Required - The custom geography to estimate values for.
- **source** (object) - Required - The input geography containing the original values.
- **meta** (object) - Required - Metadata defining how variables should be aggregated (e.g., additive vs averages).
- **na.rm** (boolean) - Optional - Whether to remove NA values when aggregating. Default is FALSE.

### Request Example
{
  "target": "sf_object_target",
  "source": "sf_object_source",
  "meta": "metadata_definition",
  "na.rm": false
}

### Response
#### Success Response (200)
- **result** (object) - The target geography object populated with estimated quantities from the source.

#### Response Example
{
  "status": "success",
  "data": "target_with_estimated_values"
}
```

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

### Visualize Tongfen Aggregates Across Geographies

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen.html

Aggregates Tongfen data based on common geographies from all four input geographies and visualizes the results. This provides a comprehensive overview of data consistency across different census years.

```R
years %>%
  lapply(function(year){
    tongfen_aggregate(data,correspondence,base_geo = year) %>%
      mutate(Year=year)
  }) %>%
  bind_rows() %>%
  ggplot() + 
  geom_sf(fill="steelblue",colour="brown") + 
  coord_sf(datum=NA) + 
  facet_wrap("Year") + 
  labs(title="Tongfen aggregates visual inspection",caption="StatCan Census 2001-2016")
```

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

### Compute Population Change Metrics

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen.html

Computes average annual population change metrics between different census years (2001-2006, 2006-2011, 2011-2016, and 2001-2016) using a geometric average. It also categorizes the changes into predefined bins for visualization.

```R
compute_population_change_metrics <- function(data) {
 geometric_average <- function(x,n){sign(x) * (exp(log(1+abs(x))/n)-1)}
 data %>%
  mutate(`2001 - 2006`=geometric_average((`Population_2006`-`Population_2001`)/`Population_2001`,5),
         `2006 - 2011`=geometric_average((`Population_2011`-`Population_2006`)/`Population_2006`,5),
         `2011 - 2016`=geometric_average((`Population_2016`-`Population_2011`)/`Population_2011`,5),
         `2001 - 2016`=geometric_average((`Population_2016`-`Population_2001`)/`Population_2001`,15)) %>%
  gather(key="Period",value="Population Change",c("2001 - 2006","2006 - 2011","2011 - 2016","2001 - 2016")) %>%
  mutate(Period=factor(Period,levels=c("2001 - 2006","2006 - 2011","2011 - 2016","2001 - 2016"))) %>%
   mutate(c=cut(`Population Change`,breaks=breaks, labels=labels))
}
```

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

### Load Election Data for Vancouver

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/polling_districts.html

Loads the built-in geographic and voting datasets for the 2015 and 2019 Canadian federal elections in Vancouver provided by the tongfen package.

```R
data("vancouver_elections_data_2015", package="tongfen")
data("vancouver_elections_data_2019", package="tongfen")
data("vancouver_elections_geos_2015", package="tongfen")
data("vancouver_elections_geos_2019", package="tongfen")
```

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

### Generate Metadata for Additive Variables

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen.html

Generates metadata required for aggregating additive variables like 'Population' across different years. This function ensures that the aggregation rules are correctly defined for population data.

```R
meta <- meta_for_additive_variables(years,"Population")
meta
```

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

### Proportionally reaggregate DA data to DB level

Source: https://context7.com/mountainmath/tongfen/llms.txt

Demonstrates how to reaggregate Dissemination Area (DA) data to a higher level based on population weights. This function requires parent data and specific geographic matching identifiers.

```r
db_data <- db_geo %>%
  proportional_reaggregate(
    parent_data = da_data,
    geo_match = c("DA_UID" = "GeoUID"),
    categories = variables$label,
    base = "Population"
  )
```

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

### Visualize Election Results by Polling District

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/polling_districts.html

Processes raw election data to identify the winning party per district and visualizes the results using ggplot2 and sf for spatial mapping.

```R
party_colours <- c("People's Party"="#4a3389", Conservative="#0C499C", "Bloc Québécois"="#02819E", Liberal="#A50B0B", NDP="#DA3D00", "Green Party"="#2E8724", "Independent"="#676767", Other="yellow")

raw_vote_data <- bind_rows(
  vancouver_elections_geos_2015 %>% 
    left_join(vancouver_elections_data_2015 %>% group_by(PD_2015) %>% top_n(1, Votes), by="PD_2015") %>% mutate(Year="2015"),
  vancouver_elections_geos_2019 %>% 
    left_join(vancouver_elections_data_2019 %>% group_by(PD_2019) %>% top_n(1, Votes), by="PD_2019") %>% mutate(Year="2019")
) %>% mutate(Party=case_when(grepl("NDP", Party) ~ "NDP", Party %in% names(party_colours) ~ Party, TRUE ~ "Other"))

ggplot(raw_vote_data) +
  geom_sf(aes(fill=Party), size=0.2, color="black") +
  facet_wrap("Year") +
  scale_fill_manual(values=party_colours) +
  theme(legend.position = "bottom") +
  coord_sf(datum=NA) +
  labs(title="Canada federal election winning candidate party by polling district", caption = "Data: Elections Canada")
```

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

### Aggregate census data using metadata rules

Source: https://context7.com/mountainmath/tongfen/llms.txt

Shows the process of aggregating census data to a target geography (e.g., Census Tract) using predefined metadata rules. It includes geometry aggregation and handles missing values.

```r
library(tongfen)
library(cancensus)
library(dplyr)

geo <- get_census("CA06",
                  regions = list(CSD = "5915022"),
                  geo_format = 'sf',
                  level = 'DA')

meta <- meta_for_additive_variables("CA06", "Population")

result <- geo %>%
  group_by(CT_UID) %>%
  aggregate_data_with_meta(
    meta = meta,
    geo = TRUE,
    na.rm = TRUE,
    quiet = FALSE
  )
```

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

### Generate Metadata for Additive Variables in R

Source: https://context7.com/mountainmath/tongfen/llms.txt

Generates metadata for aggregating additive variables (like counts) in the tongfen package. This function is crucial for specifying how variables should be combined during data harmonization, especially across different census datasets.

```r
library(tongfen)
library(dplyr)

# Create metadata for population counts across multiple census years
meta <- meta_for_additive_variables(
  dataset = c("CA06", "CA16"),
  variables = "Population"
)

# With named variables for clearer output labels
meta <- meta_for_additive_variables(
  dataset = c("2001", "2006", "2011", "2016"),
  variables = c(pop_2001 = "Population", pop_2006 = "Population",
                pop_2011 = "Population", pop_2016 = "Population")
)
```

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

### Generate Zoomed Plot of Tongfen Boundaries

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/polling_districts.html

Generates a zoomed-in plot of the Tongfen geometries within a specified bounding box. This visualization helps in understanding how areas are joined up in the Tongfen process within a specific region of interest.

```R
bb <- st_bbox(bbox)
ggplot(compare_geos) +
  facet_wrap("type") +
  geom_sf(size=0.25) +
  geom_sf(data=ridings,size=0.75,fill=NA) +
  geom_sf(data=bbox,color="red",fill=NA,size=1) +
  coord_sf(datum = NA, xlim=c(bb$xmin,bb$xmax),ylim=c(bb$ymin,bb$ymax)) +
  labs(title="Federal electoral poll district boundaries TongFen",caption="Elections Canada")

```

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

### Define Bounding Box for Focus Area

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/polling_districts.html

Defines a bounding box around a specific focus area (identified by TongfenID) buffered by 200 meters. This is used for zooming into a particular region of interest for detailed visualization.

```R
focus_area <- base_geo[base_geo$TongfenID=="59039_51",]
bbox <- focus_area %>% st_buffer(200) %>% st_bbox() %>% st_as_sfc()

```

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

### Visualize US Census Data Change with R

Source: https://github.com/mountainmath/tongfen/blob/main/docs/articles/tongfen_us.html

This R code uses ggplot2 to visualize the change in average household size in the Bay Area between 2000 and 2010. It bins the calculated 'change' variable into categories and uses `geom_sf` to display the spatial data, coloring the census tracts based on the magnitude of change. The plot is further refined with specific coordinate limits to focus on the Bay Area.

```R
census_data %>%
  mutate(c=cut(change,c(-Inf,-0.5,-0.3,-0.2,-0.1,0,0.1,0.2,0.3,0.5,Inf))) %>%
  ggplot() +
  geom_sf(aes(fill=c), size=0.05) +
  scale_fill_brewer(palette = "RdYlGn") +
  labs(title="Bay area change in average household size 2000-2010", fill=NULL) +
  coord_sf(datum=NA,xlim=c(-122.6,-121.7),ylim=c(37.2,37.9))
```

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

### Estimate Tongfen Correspondence (R)

Source: https://github.com/mountainmath/tongfen/blob/main/docs/reference/estimate_tongfen_single_correspondence.html

Generates correspondence data for two input geometries (sf objects). It links unique identifiers from both geometries to a common geometry enumeration. The function handles tolerance for feature matching and allows specifying a computation CRS and robustness for geometry validation.

```R
estimate_tongfen_single_correspondence(
  geo1,
  geo2,
  geo1_uid,
  geo2_uid,
  tolerance = 1,
  computation_crs = NULL,
  robust = FALSE
)
```