CLI Reference#

This page provides documentation for our command line tools.

Examples#

to get a summary or a MATSim plans file: pam report summary tests/test_data/test_matsim_plansv12.xml.
plan cropping: pam crop <path_population_xml> <path_core_area_geojson> <path_output_directory>.
down/up-sampling an xml population: pam sample <path_population_xml> <path_output_directory> -s <sample_percentage> -v <matsim_version>. For example, you can use: pam sample tests/test_data/test_matsim_plansv12.xml tests/test_data/output/sampled -s 0.1 to create a downsampled (to 10%) version of the input (test_matsim_plansv12.xml) population.
combining populations: pam combine <input_population_1> <input_population_2> <input_population_3...etc> -o <outpath_directory> -m <comment> -v <matsim_version>.

pam#

Population Activity Modeller (PAM) Command Line Tool.

Usage:

pam [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--help`	boolean	Show this message and exit.	`False`

pam combine#

Combine multiple populations (e.g. household, freight.. etc).

Usage:

pam combine [OPTIONS] [POPULATION_PATHS]...

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--comment`, `-c`	text	A comment included in the output population.	``
`--population_output`, `-o`	path	Specify outpath for combined_population.xml, default is cwd	`combined_population.xml`
`--force`, `-f`	boolean	Forces overwrite of existing file.	`False`
`--help`	boolean	Show this message and exit.	`False`

pam crop#

Crop a population's plans outside a core area.

Usage:

pam crop [OPTIONS] PATH_POPULATION_INPUT PATH_BOUNDARY DIR_POPULATION_OUTPUT

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--comment`, `-c`	text	A comment included in the output population.	``
`--buffer`, `-b`	integer	A buffer distance to (optionally) apply to the core area shapefile.	`0`
`--help`	boolean	Show this message and exit.	`False`

pam report#

Various reporting for MATSim formatted plans.

Usage:

pam report [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

pam report benchmarks#

Write batch of benchmarks to directory.

Usage:

pam report benchmarks [OPTIONS] POPULATION_INPUT_PATH OUTPUT_DIRECTORY

Options:

Name	Type	Description	Default
`--sample_size`, `-s`	float	Input sample size. Default 1. Required for downsampled populations. eg, use 0.1 for a 10% input population.	`1`
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--help`	boolean	Show this message and exit.	`False`

pam report stringify#

ASCII plot activity plans to terminal.

Usage:

pam report stringify [OPTIONS] PATH_POPULATION_INPUT

Options:

Name	Type	Description	Default
`--colour` / `--bw`	boolean	Choose a colour or grey-scale (bw) output, default 'colour'	`True`
`--width`, `-w`	integer	Target character width for plot, default 72	`72`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to crop.	`True`
`--help`	boolean	Show this message and exit.	`False`

pam report summary#

Summarise a population.

Usage:

pam report summary [OPTIONS] PATH_POPULATION_INPUT

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--sample_size`, `-s`	float	Input sample size. Default 1. For example, use 0.1 to apply a 10% weighting to the input population.	`1`
`--attribute_key`, `-k`	text	Optional population attribute key to segment output, eg 'subpopulation'.	None
`--rich` / `--text`	boolean	Formatted (for terminal) or regular text output (for .txt).	`True`
`--help`	boolean	Show this message and exit.	`False`

pam sample#

Down- or up-sample a PAM population.

Usage:

pam sample [OPTIONS] PATH_POPULATION_INPUT DIR_POPULATION_OUTPUT

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--comment`, `-c`	text	A comment included in the output population.	``
`--sample_size`, `-s`	text	The sample size, eg, use 0.1 to produce a 10% version of the input population.	None
`--household_key`, `-h`	text	Household key, defaults to 'hid'.	`hid`
`--seed`	text	Random seed.	None
`--help`	boolean	Show this message and exit.	`False`

pam wipe-all-links#

Clear all link information from agent plans. Including routes and activity locations.

Usage:

pam wipe-all-links [OPTIONS] PATH_POPULATION_INPUT PATH_POPULATION_OUTPUT

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--comment`, `-c`	text	A comment included in the output population.	``
`--help`	boolean	Show this message and exit.	`False`

pam wipe-links#

Clear selected link information from agent plans. Includes routes and activity locations.

eg: pam wipe-links INPUT_PLANS.xml OUTPUT_PLANS.xml link_a link_b link_c

Usage:

pam wipe-links [OPTIONS] PATH_POPULATION_INPUT PATH_POPULATION_OUTPUT
               [LINKS]...

Options:

Name	Type	Description	Default
`-d`, `--debug`	boolean	Switch on debug verbosity.	`False`
`--keep_non_selected` / `--selected_only`	boolean	Optionally keep (read and write) non selected plans.	`False`
`--leg_route` / `--no_leg_route`	boolean	Optionally turn off reading of leg_route.	`True`
`--leg_attributes` / `--no_leg_attributes`	boolean	Optionally turn of reading of leg_attributes.	`True`
`--crop` / `--no_crop`	boolean	Crop or don't crop plans to 24 hours, defaults to no_crop.	`False`
`--autocomplete` / `--no_autocomplete`	boolean	Optionally turn off autocomplete, not recommended.	`True`
`--simplify_pt_trips`	boolean	Optionally simplify transit legs into single trip.	`False`
`--household_key`, `-h`	text	Household key, such as 'hid', default None.	None
`--matsim_version`, `-v`	integer	MATSim plan format, default 12.	`12`
`--comment`, `-c`	text	A comment included in the output population.	``
`--help`	boolean	Show this message and exit.	`False`