preprocess_faf4_database: Transform FAF flow database distributed by FHWA into format...

Description Usage Arguments Details Examples

View source: R/preprocess_faf4_database.R

Description

Transform FAF flow database distributed by FHWA into format for target year

Usage

1
2
preprocess_faf4_database(fhwa_db, target_year, interpolate = FALSE,
  internal_regions = NULL, outer_regions = NULL)

Arguments

fhwa_db

Data frame containing the FAF interregional flow database in format distributed by FHWA, or string containing path and filename containing the same

target_year

The four-digit simulation year as an integer value

interpolate

A boolean variable denoting whether values for the 'target_year' should be interpolated between the two closest years if it is not one of the years included in the FAF database (defaults to FALSE, currently ignored)

internal_regions

A set of one or more FAF regions internal to the study area (optional, but must be specified if 'outer_regions' is defined)

outer_regions

A data frame containing FAF region pairs whose flows pass through the modeled area (optional, but if specified then 'internal_regions' must also be specified)

Details

This function converts the FHWA Freight Analysis Framework (FAF) commodity flows, measured in annual tons, dollars, and ton-miles between domestic FAF regions and external regions into annual flows for the specified year or closest to it in the FAF database. The 'fhwa_db' can either be a data frame previously created with the contents of the FAF flow database or a fully-qualified pathname to the data in comma- separated value (CSV) format. The latter can be in a compressed format that readr::read_csv() can handle.

It is important to note that the tons, value, and ton-miles are converted from implied thousands and millions of units in the source data. Zero values are retained, as they reportedly represent flows whose values are less than 1 unit (e.g., zero tons represent values between zero and one thousand tons since in the FAF tons are coded in implied thousands of tons).

The 'target_year' must be one of the years in the FAF database, or fall between two of the years included within it. Only data for the target or closest year is processed by this function. An optional 'interpolate' parameter will eventually allow for the tons, value, and ton-miles to be interpolated between the two closest years to the target year. The parameter is included so as to not break the interface, but the functionality is not currently implemented.

The 'internal_regions' should be specified as a list of the FAF regions inside the modeled area. Flows to, from, and between these internal regions will be allocated to synthetic firms or traffic analysis zones within the model. Flows from the remainder of the USA will be retained if they have a trip end in one of the internal regions (e.g., internal, inbound, or outbound flows). The internal regions are optional, but if omitted data from the entire USA will be considered internal to the model.

Flows likely to pass through one or more internal regions can be included as 'outer_regions'. Such flows must be defined as FAF region pairs (e.g., truck flows between California and Washington on I-5 if Oregon comprises the internal regions). The flows are assumed to be bidirectional to reduce the amount of coding required. Note that any additional fields in 'outer_regions' will be added to the FAF flows records. The user should remove any unwanted fields before or after passing the 'outer_region' definitions to this function.

Examples

1
2
3
4
annual_flows <- preprocess_faf4_database(fhwa_database, 2018, FALSE,
  c(411, 419, 532))  # Several internal regions and no outer regions defined
annual_flows <- preprocess_faf4_database("./faf4.4.1.zip", 2016, FALSE,
  160, idaho_outer_regions)   # A single internal and multiple outer regions

pbsag/swimctr documentation built on May 24, 2019, 10:38 p.m.