Inputs#

The Van model has a number of input files which can be provided in the GUI, or via a configuration file (example below). This section details all of the input files which are needed in order to run the Van model.

To run the Van model with a configuration file it needs to be ran from command line. The command for running it is caf.van -c "path/to/config.yml", (see Usage for more information). An example of the configuration file is shown below.

Note

Help text for running the tool through the command line can be seen with caf.van -h, it’s also shown in Usage.

zoning: Name of the zoning system to use for the model
model_zones: Path to CSV containing lookup for zones in model study area.

household_paths:
   occupied: Path to the occupied dwellings data DVector
      No specific segmentation is required as it is aggregated to total households by zone.
   zc_path: Path to the zone correspondence CSV.
   unoccupied: Optional - Path to the unoccupied dwellings data DVector.
      No specific segmentation is required as it is aggregated to total households by zone."""

employment_paths:
   path: Path to the TfN Land-use DVector. Required segmentation is 'sic_1_digit'.
   zc_path: Path to the zone correspondence CSV.

warehouse_path: Path for the warehouse floorspace data CSV at LSOA level
commute_warehouse_paths:
  medium: CSV of LSOA warehouse floorspace for commute segment (medium weighting),
    required
  low: CSV of LSOA warehouse floorspace for commute segment (low weighting), optional
  high: CSV of LSOA warehouse floorspace for commute segment (high weighting), optional

parameters_path: Path to the van model parameters Excel workbook.
qs606ew_path: Path to the England & Wales Census Occupation data CSV
qs606sc_path: Path to the Scottish Census Occupation data CSV
constructions_path: Path to GB construction data csv.
lsoa_lookup_path: Path to the LSOA to model zone correspondence CSV
tripend_balancing_regions_path: Path to csv containing trip end balancing regions to zone correspondence
cost_matrix_path: Path to CSV containing cost matrix, should be square matrix with
  zone numbers as column names and indices
summary_zone_translation:
   path: Path to model zones to summary zones correspondence CSV
   from_zoning: Name of model zoning system in translation file
   to_zoning: Name of summary zoning system in translation file

gm_parameters:
   # Separate gravity model parameters for each van segment:
   # service, delivery_parcel_stem, delivery_parcel_bush,
   # delivery_grocery, commuting_drivers, commuting_skilled_trades
   service:
      trip_length_distribution_path: Path to the Trip Length Distribution CSV.
      cost_function: The cost function to use for the gravity model. Either 'log_normal' or 'tanner'
      cost_function_params: Starting (calibration)/run params for the cost function.
      calibrate: Whether to calibrate the cost function params (True) or run with given params (False).
      cat_zone_correspondence_path: Path to CSV with correspondence between the categories in the TLD and the model zones.
      furness_jacobian: Whether to Furness the Jacobian matrix in the gravity model. Find your nearest demand modelling expert for more information.
   delivery_parcel_stem:
      ...
output_folder: Path to folder to save outputs to
personal_matrix_inputs:
# Optional only pass if you want to create a personal matrix
   normits_pa_folder: Path to the full PA Normits car matrices, should contain all non home
      based and home based matrices
   personal_zone_translation: Car matrix zoning to model zoning lookup.
   personal_factor: This is the factor that the personal data should have applied to
      just include van data 4% is a starting point
   personal_purposes: Personal purpose types defined by Normits

Household data#

UK household data in caf.base.DVector format. Singular DVectors are required for each of the data inputs. No specific segmentation is required, since the data is aggregated to the number of household per zone. Occupied dwellings is required and unoccupied dwellings is optional. If both are given the number of dwellings used is the sum of both datasets, if unoccupied is not given, the occupied data is used as is.

The zone correspondence path should point to a CSV, which contains zone correspondence from the DVector’s zoning to the model zoning, see Zone Correspondences for information on the format of the CSV.

Employment Data#

UK employment data in caf.base.DVector format. A single DVector is required for the data input. The DVector must be segmented by ‘sic_1_digit’, any other segments will be aggregated. The zone correspondence path should point to a csv in caf.space format which contains zone correspondence from the DVector’s zoning to the model zoning.

Warehouse Data#

Warehouse floorspace area data is used for calculating trip ends for the delivery and commute segments. The warehouse floorspace data used by Transport for the North is aggregated from Ordnance Survey’s Address Base Premium and Master map data.

The following four warehouse floorspace input files are required (all at LSOA zoning):

  • Warehouse floorspace for delivery stem productions, required

  • Warehouse floorspace for attracting LGV commuting drivers

    • Medium relevance floorspace, required

    • High relevance floorspace, optional

    • Low relevance floorspace, optional

All the warehouse floorspace input files are in the same format, they should be a CSV file with two columns, as defined in the table below.

Column definitions for the warehouse floorspace input files.#

Column Name

Data Type

Description

LSOA11CD

Text

LSOA zone ID.

area

Real

Total warehouse floorspace for the LSOA (\(m^2\)).

Note

Any missing LSOAs are assumed to have zero floorspace.

Van Parameters Spreadsheet#

This input should be an Excel spreadsheet containing a variety of sheets with different parameters for the van model. Each of the required sheets in this input file are discussed in the following sections.

Parameters#

The sheet named “Parameters” should contain two columns with the headers “Parameter” and “Value”. The following table gives the names of the parameters and a description of what value should be provided.

Required parameters for the Van Model, parameters must be labelled exactly as given.#

Parameter

Data Type

Description

LGV growth

Real

A factor to increase the van trips from the van survey year to the model year

Average new house size

Real

The average new house size in \(m^2\)

Scotland SOC821 / SOC82

Real (0 - 1)

The proportion of SOC821 occupations in the SOC82 segment.

Model Year

Integer

The model year e.g. 2018

Commute Trips by Main Usage#

The sheet named “Commute trips by main usage” should contain the annual number of commute van trips from the van survey by usage type. The following usage types should be included:

  • G: Carrying goods

  • S: Service / trades

  • C: Commuting

  • T: Carrying people

  • O: Other

This sheet should have two columns with the headers in the first row, the table below lists the columns.

Required columns for the commute trips by main usage sheet.#

Column Name

Data Type

Description

Main Usage

Character (1)

Usage code for each of the types listed above

Trips

Real

The annual number of commuting LGV trips for that usage type

Commute Trips by Land Use#

The sheet named “Commute trips by land use” should contain the annual number of commute van trips from the van survey by land use type. The following land uses should be included:

  • Residential

  • Construction

  • Employment

This sheet should have two columns with the headers in the first row, the table below lists the columns.

Required columns for the commute trips by land use sheet.#

Column Name

Data Type

Description

Land use at trip end

Text

The name of the land use type e.g. Residential

Trips

Real

The annual number of commuting LGV trips for that land use

Annual Service Trips#

The sheet named “Annual Service Trips” should contain the annual number of LGV service trips by land use type from the DfT van survey. The sheet should contain the following land uses:

  • Residential

  • Office

  • All Other

This sheet should have two columns with the headers in the first row, the table below lists the columns.

Required columns for the annual service trips sheet.#

Column Name

Data Type

Description

Segment

Text

The name of the land use type e.g. Residential

Annual Service Trips

Real

The annual number of LGV service trips for that land use

Delivery Segment Parameters#

The sheet name “Delivery Segment Parameters” contains various mandatory parameters, listed in the table below. The sheet should have the column headers “Parameter” and “Value” on the first row.

Required parameters for the delivery segment sheet, parameters should be named exactly as written.#

Parameter

Data Type

Description

Annual Trip Productions - Parcel Stem

Integer

The total annual trip productions for the delivery parcel stem segment from the DfT van survey, for the base year.

Annual Trips - Parcel Bush

Integer

The total annual trips for the delivery parcel bush segment from the DfT van survey, for the base year.

Annual Trips - Grocery Bush

Integer

The total annual trips for the delivery grocery bush segment from the DfT van survey, for the base year.

Delivery Growth Factor

Real (> 0)

Growth factor to apply to the annual delivery trips to factor to forecast year.

B2C vs B2B Weighting

Real (> 0)

The ratio of business-to-customer vs business-to-business delivery trips.

Depots Infill Zones

Comma-separated list

List of all zones in areas that aren’t covered by the warehouse dataset (e.g. Scotland), these zones will have depots allocated based on number of households.

Commute Warehouse Parameters#

The sheet named “Commute Warehouse Parameters” should contain all the parameters for the warehouse input calculations, including the weighting factors and infilling parameters. The table below describes all the required values and their use, the different weighting factors correspond to the input files described in Warehouse Data.

Description of the commute warehouse parameters#

Parameter

Data Type

Description

Weighting - High

Number

Factor to apply to the high relevance warehouse floorspace input.

Weighting - Medium

Number

Factor to apply to the medium relevance warehouse floorspace input.

Weighting - Low

Number

Factor to apply to the low relevance warehouse floorspace input.

Model Zone Infill

Comma-separated list

List of model zones in commute warehouse data which should be infilled.

Zone Infill Method

Text (from options below)

Method for infilling model zones.

Zone infill method calculates an infill value after all the warehouse data has been factored and combined and then infills any zones in the “Model Zone Infill” list, which don’t contain non-zero values already. The following methods can be chosen for calculating the infill value:

  • min: minimum value from existing data (including zeros)

  • mean: mean value from existing data

  • median: median value from existing data

  • non_zero_min: minimum non-zero value from existing data

  • zero: infills zones with zero

Time Period Factors#

The sheet named “Time Period Factors” should contain all the factors for converting from the annual matrices to the time periods for each model segment. The table should contain one factor for each time period / segment combination, a list of the required columns is given below.

The time period factors (\(f_{tp}\)) are multiplied by the annual matrix (\(M_{annual}\)) to get the time period matrix (\(M_{tp}\)) using the formula below. This calculation is done for each segment and time period separately.

\[M_{tp} = M_{annual} \times f_{tp}\]

Note

The time period factors are expected to convert from annual trips to average daily time period, therefore each factor should be less than, approximately, 1/365.

Required columns for the time period factors sheet.#

Column Names

Data Type

Description

Time Period

Text

The name of the time period, will be used for naming the outputs.

Service

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment.

Delivery Parcel Stem

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment.

Delivery Parcel Bush

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment

Delivery Grocery

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment

Commuting Drivers

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment

Commuting Skilled Trades

Real

The factor to multiply the annual matrix by to get the average daily time period (e.g. AM) for this segment

Gravity Model Parameters#

The gravity model is ran separately for each van segment, therefore the parameters (gm_parameters) should be specified separately for each. The segment names should be given exactly as follows: ‘service’, ‘delivery_parcel_stem’, ‘delivery_parcel_bush’, ‘delivery_grocery’, ‘commuting_drivers’, ‘commuting_skilled_trades’.

The following sections outline the parameters which should be defined for each segment.

Trip Length Distribution#

The trip_length_distribution_path should be a path to a CSV containing the trip length distribution(s) (TLD) to use for calibration. The CSV should contain the following columns, with names:

Format of the trip length distribution CSV#

Column Name

Data Type

Description

area

string or int

This labels which area the TLD belongs to. Area Ids should correspond to those in the Category Zone Correspondence.

from

Real

The lower bin edge for the TLD.

to

Real

The upper bin edge for the TLD.

av_distance

Real

The average distance travelled within that bin and area.

normalised

Real

The proportion of trips that fall within that bin and area.

Note

If cat_zone_correspondence_path is not given, the CSV does not need to contain the area column and the tool will perform a single TLD calibration. Alternatively, TLDs can be calibrated to separately for different zones.

Category-Zone Correspondence#

The category-zone correspondence (cat_zone_correspondence_path) is an optional lookup which defines which model zones are calibrated to each TLD provided. This is required when attempting to perform multi-TLD gravity model calibration.

Format of the category zone correspondence#

Column Name

Data Type

Description

area

string or int

This labels which category the Zone belongs to. Ids should correspond to those in the Trip Length Distribution.

zone_id

text or int

Should contain the IDs of all zones in the mode zone system, without duplicates.

Cost Function#

The cost function (cost_function) to use for the gravity model, either “log_normal” or “tanner”. If you don’t know which to use, consult TAG or your nearest demand modelling expert.

Note

If using multi-TLD calibration all TLDs will use the same cost function, although different parameters can be defined for each (see Cost Function Parameters).

Log Normal#

The log normal function is defined as:

\[f(C_{ij}) = \frac{1}{C_{ij} \cdot \sigma \cdot \sqrt{2\pi}} \cdot \exp\left(-\frac{(\ln C_{ij}-\mu)^2}{2\sigma^2}\right)\]

where:

  • \(C_{ij}\): cost from i to j.

  • \(\sigma, \mu\): calibration parameters.

Tanner#

The tanner function is defined as:

\[f(C_{ij}) = C_{ij}^\alpha \cdot \exp(\beta C_{ij})\]

where:

  • \(C_{ij}\): cost from i to j.

  • \(\alpha, \beta\): calibration parameters.

Cost Function Parameters#

The starting values for the cost function parameters (cost_function_params) to use when calibrating, or just the values to use if calibration is off. Both cost functions require two parameters (in a specific order):

  • Log normal: \(\mu\) (mu), \(\sigma\) (sigma)

  • Tanner: \(\alpha\) (alpha), \(\beta\) (beta)

If a single pair of parameters is provided these will be used for all TLDs, alternatively separate parameters can be provided for each of the area IDs in Category-Zone Correspondence.

Calibrate#

  • True to calibrate the gravity model to the TLD(s).

  • False to run the gravity model with given cost parameters.

Furness Jacobian#

Whether to furness the Jacobian matrix in the gravity model, see caf.distribute for the implementation details.

Warning

Setting this to True may cause poor results for matrices that fail to converge, this a known issue for the “bush” matrices (“delivery grocery” and “delivery bush”) which contain mostly intrazonal trips by definition. If you find poor results for these matrices, try setting furness jacobian to off.

Trip End Balancing regions#

The tripend_balancing_regions_path is an optional path to a CSV containing zone groups which the van trip ends will be balanced at. The CSV should be in the same format as the Category-Zone Correspondence.

If this isn’t given then the trip ends will be balanced at all zones, i.e. the GB total trip ends.

Constructions#

The constructions_path should point to a CSV containing the dwelling and employment floorspace changes in the model zoning.

Required columns in the Constructions CSV#

Column Name

Data Type

Description

zone

Text or int

The model zoning IDs.

additional_dwellings

Real

The number of dwellings constructed in the model year within the zone.

demolished_dwellings

Real

The number of dwellings constructed in the model year within the zone.

business_floorspace

Real

The floorspace, in m^2, constructed in the model year, within the zone.

Census Occupation Data#

The census occupation data is provided to the tool in two separate comma-separated values (CSV) files, both of which are available on the NOMIS website. The census tables required are QS606EW and QS606UK, both tables contain meta data in the first eight rows and the column names on row nine.

The QS606EW census table contains occupation data for England and Wales at LSOA level, and more occupation categories, a list of the expected columns is given in the table below. The table should be provided with the units persons.

Required columns for the QS606EW occupation data CSV.#

Column Name

Data Type

Description

2011 super output area - lower layer

Text

LSOA name

mnemonic

Text

LSOA area code

All categories: Occupation

Integer

Total occupation

51. Skilled agricultural and related trades

Integer

Occupation numbers for this segment

52. Skilled metal, electrical and electronic trades

Integer

Occupation numbers for this segment

53. Skilled construction and building trades

Integer

Occupation numbers for this segment

  1. Road Transport Drivers

Integer

Occupation numbers for this segment

The QS606UK census table should contain the occupation data extracted for Scotland only at datazone level and should be provided with the units persons. The expected columns for this input are shown in the table below.

Required columns for the QS606UK occupation data CSV.#

Column Name

Data Type

Description

2011 scottish datazone

Text

Datazone name

mnemonic

Text

Datazone area code

All categories: Occupation

Integer

Total occupation

51. Skilled agricultural and related trades

Integer

Occupation numbers for this segment

52. Skilled metal, electrical and electronic trades

Integer

Occupation numbers for this segment

53. Skilled construction and building trades

Integer

Occupation numbers for this segment

82. Transport and mobile machine drivers and operatives

Integer

Occupation numbers for this segment

Zone Correspondences#

Zone correspondence CSVs are required for converting Warehouse and Occupation data from LSOA to the model zone system and annual matrices to a summary zone system. The summary zone system can be chosen by the user to suit the specific situation. LSOA to model zones requires column names on the first row and three required columns, listed in the table below.

Required columns for the LSOA zone correspondence CSV, column names are ignored the columns just need to be in the correct order.#

Column

Data Type

Description

1

Text

Area code e.g. E01000001

2

Integer

Corresponding model zone ID

3

Real

Splitting factor for correspondence

The summary zone correspondence should be in caf.space format, containing the following columns:

  • {from_zoning}_id - the model zone ID

  • {to_zoning}_id - the summary zone ID

  • {from_zoning}_{to_zoning} - translation factor, best practice is to use aggregated zones for the summary, so all of theses should be 1.

Zoning#

This should be the name of the model zoning system, which should match that in the zone correspondence file.

Model zones#

The model zones file should contain a complete list of the zone IDs.

Required columns for the study area lookup CSV, column names must be exactly as listed any other columns are ignored.#

Column Name

Data Type

Description

zone

Integer

The model zone number

Cost Matrix#

Matrix CSV containing the cost values for all zones in the model, the units of the costs should be the same as the units in the Trip Length Distribution. The CSV file should be in square matrix format where the first column and row contains all the zone numbers, an example of a three by three matrix with the same costs for all zones is shown below.

Example 3x3 matrix#

1

2

3

1

10

10

10

2

10

10

10

3

10

10

10

Calibration Matrix#

The calibration matrix should be a CSV in the same format as Cost Matrix. This matrix is used during the gravity model process to adjust the impact of trips between certain zone pairs and should have positive values around 0 - 2. The Gravity Model section outlines the methodology where this input is used.

Output Folder#

The parent directory where all the outputs will be saved. A new sub-folder will be created with the name convention “LGV Model Outputs - {date} {time}” (e.g. “LGV Model Outputs - 2021-08-05 19.15.32”) will be created to store the outputs for a single run of the van model.