Package 'cansim'

Title: Accessing Statistics Canada Data Table and Vectors
Description: Searches for, accesses, and retrieves new-format and old-format Statistics Canada data tables, as well as individual vectors, as tidy data frames. This package deals with encoding issues, allows for bilingual English or French language data retrieval, and bundles convenience functions to make it easier to work with retrieved table data. Optional caching features are provided.
Authors: Jens von Bergmann [cre], Dmitry Shkolnik [aut]
Maintainer: Jens von Bergmann <[email protected]>
License: MIT + file LICENSE
Version: 0.3.17
Built: 2024-11-07 13:39:33 UTC
Source: CRAN

Help Index

Add provincial abbreviations as factor

Description

Add provincial abbreviations as factor

Usage

add_provincial_abbreviations(data)

Arguments

data

A tibble as returned by get_cansim with provincial level data

Value

The input tibble with additional factor GEO.abb that contains language-specific provincial abbreviations

Examples

## Not run: 
df <- get_cansim("17-10-0005")
df <- add_provincial_abbreviations(df)

## End(Not run)

Translate deprecated CANSIM table number into new NDM-format table catalogue number

Description

Returns NDM table catalogue equivalent given a standard old-format CANSIM table number

Usage

cansim_old_to_new(oldCansimTableNumber)

Arguments

oldCansimTableNumber

deprecated style CANSIM table number (e.g. "427-0001")

Value

A character string with the new-format NDM table number

Examples

## Not run: 
cansim_old_to_new("026-0018")

## End(Not run)

Use metadata to extract categories for column of specific level

Description

For tables with data with hierarchical categories, metadata containing hierarchy level descriptions is used to extract categories at a specified level of hierarchy only.

Usage

categories_for_level(
  data,
  column_name,
  level = NA,
  strict = FALSE,
  remove_duplicates = TRUE
)

Arguments

data

data table object as returned from get_cansim()
column_name

the quoted name of the column to extract categories from
level

the hierarchy level depth to which to extract categories, where 0 is top category
strict

(default FALSE) when TRUE will only extract that specific hierarchy level
remove_duplicates

(default TRUE) When set to TRUE higher level grouping categories already captured by lower level hierarchy data will be removed

Value

A vector of categories

Examples

## Not run: 
data <- get_cansim("16-10-0117")
categories_for_level(data,"North American Industry Classification System (NAICS)",level=2)

## End(Not run)

Collect data from connection and normalize cansim table output

Description

Collect data from connection and normalize cansim table output

Usage

collect_and_normalize(
  connection,
  replacement_value = "val_norm",
  normalize_percent = TRUE,
  default_month = "07",
  default_day = "01",
  factors = FALSE,
  strip_classification_code = FALSE,
  disconnect = FALSE
)

Arguments

connection

A connection to a local StatCan table SQLite database as returned by get_cansim_sqlite, possibly with filters or other dbplyr verbs applied
replacement_value

(Optional) the name of the column the manipulated value should be returned in. Defaults to adding the 'val_norm' value field.
normalize_percent

(Optional) When true (the default) normalizes percentages by changing them to rates
default_month

The default month that should be used when creating Date objects for annual data (default set to "07")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01")
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to FALSE).
strip_classification_code

(Optional) Logical value indicating if classification code should be stripped from names. (Default set to false).
disconnect

(Optional) Logical value to indicate if the database connection should be disconnected. (Default is FALSE)

Value

A tibble with the collected and normalized data

Examples

## Not run: 
library(dplyr)

con <- get_cansim_sqlite("34-10-0013")
data <- con %>%
  filter(GEO=="Ontario") %>%
  collect_and_normalize()

disconnect_cansim_sqlite(con)

## End(Not run)

Disconnect from a cansim database connection

Description

Disconnect from a cansim database connection

Usage

disconnect_cansim_sqlite(connection)

Arguments

connection

connection to database

Value

'NULL“

Examples

## Not run: 
con <- get_cansim_sqlite("34-10-0013")
disconnect_cansim_sqlite(con)

## End(Not run)

Retrieve a Statistics Canada data table using NDM catalogue number

Description

Retrieves a data table using an NDM catalogue number as a tidy data frame. Retrieved table data is cached for the duration of the current R session only by default.

Usage

get_cansim(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200,
  factors = TRUE,
  default_month = "07",
  default_day = "01"
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to TRUE).
default_month

The default month that should be used when creating Date objects for annual data (default set to "07")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01") Set to higher values for large tables and slow network connection. (Default is 200).

Value

A tibble with StatCan Table data and added Date column with inferred date objects and added val_norm column with normalized value from the VALUE column.

Examples

## Not run: 
get_cansim("34-10-0013")

## End(Not run)

Retrieve a list of modified tables since a given date

Description

Retrieve a list of tables that have been modified or updated since the specified date.

Usage

get_cansim_changed_tables(start_date, end_date = NULL)

Arguments

start_date

Starting date in YYYY-MM-DD format to look for changes that changed on or after that date
end_date

Optional end date in YYYY-MM-DD format to look for changes that changed on or before that date, default is same as start date

Value

A tibble with Statistics Canada data table product ids and their release times

Examples

## Not run: 
get_cansim_changed_tables("2018-08-01")

## End(Not run)

Get NDM code sets

Description

Useful to get a list of surveys or subjects and used internally

Usage

get_cansim_code_set(
  code_set = c("scalar", "frequency", "symbol", "status", "uom", "survey", "subject",
    "wdsResponseStatus"),
  refresh = FALSE
)

Arguments

code_set

the code set to retrieve.
refresh

Default is FALSE, repeated calls during the same session will hit the cached data. To refresh the code list during a running R session set to TRUE

Value

A tibble with english and french labels for the given code set

Examples

## Not run: 
get_cansim_code_set("survey")

## End(Not run)

Retrieve Statistics Canada data table categories for a specific column

Description

Returns table column details given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_column_categories(
  cansimTableNumber,
  column,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
column

the specified column for which to retrieve category information for
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with detailed information on StatCan table categories for the specified field

Examples

## Not run: 
get_cansim_column_categories("34-10-0013", "Geography")

## End(Not run)

Retrieve Statistics Canada data table column list

Description

Returns table column details given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_column_list(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble listing the column names of the StatCan table.

Examples

## Not run: 
get_cansim_column_list("34-10-0013")

## End(Not run)

Retrieve table metadata from Statistics Canada API

Description

Retrieves table metadata given an input table number or vector of table numbers using either the new or old table number format. Patience is suggested as the Statistics Canada API can be very slow. The 'list_cansim_tables()' function can be used as an alternative to retrieve a (cached) list of CANSIM tables with (more limited) metadata.

Usage

get_cansim_cube_metadata(cansimTableNumber, type = "overview", refresh = FALSE)

Arguments

cansimTableNumber

A new or old CANSIM/NDM table number or a vector of table numbers
type

Which type of metadata to get, options are "overview", "members", "notes", or "corrections".
refresh

Refresh the data from the Statistics Canada API

Value

a tibble containing the table metadata

Examples

## Not run: 
get_cansim_cube_metadata("34-10-0013")

## End(Not run)

Retrieve data for specified Statistics Canada data product for last N periods for specific coordinates

Description

Allows for the retrieval of data for a Statistics Canada data table with specific coordinates for the N most-recently released periods. Caution: coordinates are concatenations of table member ID values and require familiarity with the TableMetadata data structure. Coordinates have a maximum of ten dimensions.

Usage

get_cansim_data_for_table_coord_periods(
  cansimTableNumber,
  coordinate,
  periods = 1,
  language = "english",
  refresh = FALSE,
  timeout = 200,
  factors = TRUE,
  default_month = "07",
  default_day = "01"
)

Arguments

cansimTableNumber

Statistics Canada data table number
coordinate

A string of table coordinates in the form "1.1.1.36.1.0.0.0.0.0"
periods

Numeric value for number of latest periods to retrieve data for
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to TRUE).
default_month

The default month that should be used when creating Date objects for annual data (default set to "07")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01")

Value

A tibble with data matching specified coordinate and period input arguments

Examples

## Not run: 
get_cansim_data_for_table_coord_periods("35-10-0003",coordinate="1.12.0.0.0.0.0.0.0.0",periods=3)

## End(Not run)

Major economic indicator release schedule

Description

Returns every release date of major economic indicators since March 14, 2012. This also includes scheduled future releases.

Usage

get_cansim_key_release_schedule()

Value

a tibble with data, and details for major economic indicator release

Examples

## Not run: 
get_cansim_key_release_schedule()

## End(Not run)

Retrieve a Statistics Canada data table using NDM catalogue number as SQLite database connection

Description

Retrieves a data table using an NDM catalogue number as an SQLite table. Retrieved table data is cached permanently if a cache path is supplied or for duration of the current R session. The function will check against the lastest release data for the table and emit a warning message if the cached table is out of date.

Usage

get_cansim_sqlite(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  auto_refresh = FALSE,
  timeout = 1000,
  cache_path = getOption("cansim.cache_path")
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
auto_refresh

(Optional) When set to TRUE, it will reload of data table if a new version is available (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.
cache_path

(Optional) Path to where to cache the table permanently. By default, the data is cached in the path specified by 'getOption("cansim.cache_path")', if this is set. Otherwise it will use 'tempdir()'.

Value

A database connection to a local SQLite database with the StatCan Table data.

Examples

## Not run: 
con <- get_cansim_sqlite("34-10-0013")

# Work with the data connection
head(con)

disconnect_cansim_sqlite(con)

## End(Not run)

Retrieve Statistics Canada data table information

Description

Returns table information given an NDM table catalogue number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_table_info(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with the table overview information

Examples

## Not run: 
get_cansim_table_info("34-10-0013")

## End(Not run)

Get the latest release data for a StatCan table, if available

Description

This can be used to check when a table has last been updated.

Usage

get_cansim_table_last_release_date(cansimTableNumber)

Arguments

cansimTableNumber

the NDM table number

Value

A datatime object if a release data is available, NULL otherwise.

Examples

## Not run: 
get_cansim_table_last_release_date("34-10-0013")

## End(Not run)

Retrieve Statistics Canada data table notes and column categories

Description

Returns table notes given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_table_notes(
  cansimTableNumber,
  language = "en",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with table notes.

Examples

## Not run: 
get_cansim_table_notes("34-10-0013")

## End(Not run)

Retrieve Statistics Canada data table overview text

Description

Prints table overview information as console output. In order to display table overview information, the selected CANSIM table must be loaded entirely to display overview information. Overview information is printed in console an in English or French, as specified.

Usage

get_cansim_table_overview(
  cansimTableNumber,
  language = "english",
  refresh = FALSE
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)

Value

none

Examples

## Not run: 
get_cansim_table_overview("34-10-0013")

## End(Not run)

Retrieve Statistics Canada data table short notes

Description

Returns table notes given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_table_short_notes(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with the StatCan Notes for the table

Examples

## Not run: 
get_cansim_table_short_notes("34-10-0013")

## End(Not run)

Retrieve Statistics Canada data table subject detail

Description

Returns table subject detail given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_table_subject(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with the table subject code and name.

Examples

## Not run: 
get_cansim_table_subject("34-10-0013")

## End(Not run)

Retrieve Statistics Canada data table survey detail

Description

Returns table survey detail given an NDM table number in English or French. Retrieved table information data is cached for the duration of the R session only.

Usage

get_cansim_table_survey(
  cansimTableNumber,
  language = "english",
  refresh = FALSE,
  timeout = 200
)

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (default set to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.

Value

A tibble with the table survey code and name

Examples

## Not run: 
get_cansim_table_survey("34-10-0013")

## End(Not run)

Retrieve a Statistics Canada data table URL given a table number

Description

Retrieve URL of a table from the API given a table number. Offers a more stable approach than manually guessing the URL of the table.

Usage

get_cansim_table_url(cansimTableNumber, language = "en")

Arguments

cansimTableNumber

the NDM table number to load
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)

Value

String object containing URL for specified table number

Examples

## Not run: 
get_cansim_table_url("34-10-0013")
get_cansim_table_url("34-10-0013", language = "fr")

## End(Not run)

Retrieve data for a Statistics Canada data vector released within a given time frame

Description

Retrieve data for a Statistics Canada data vector released within a given time frame

Usage

get_cansim_vector(
  vectors,
  start_time = as.Date("1800-01-01"),
  end_time = Sys.time(),
  use_ref_date = TRUE,
  language = "english",
  refresh = FALSE,
  timeout = 200,
  factors = TRUE,
  default_month = "07",
  default_day = "01"
)

Arguments

vectors

The list of vectors to retrieve
start_time

Starting date in YYYY-MM-DD format, applies to REF_DATE or releaseTime, depending on use_ref_date parameter
end_time

Set an optional end time filter in YYYY-MM-DD format (defaults to current system time)
use_ref_date

Optional, TRUE by default. When set to TRUE, uses REF_DATE of vector data to filter, otherwise it uses StatisticsCanada's releaseDate value for filtering the specified vectors.
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to TRUE).
default_month

The default month that should be used when creating Date objects for annual data (default set to "07")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01")

Value

A tibble with data for vectors released between start and end time

Examples

## Not run: 
get_cansim_vector("v41690973","2015-01-01")

## End(Not run)

Retrieve data for specified Statistics Canada data vector(s) for last N periods

Description

Allows for the retrieval of data for specified vector series for the N most-recently released periods.

Usage

get_cansim_vector_for_latest_periods(
  vectors,
  periods = 1,
  language = "english",
  refresh = FALSE,
  timeout = 200,
  factors = TRUE,
  default_month = "07",
  default_day = "01"
)

Arguments

vectors

The list of vectors to retrieve
periods

Numeric value for number of latest periods to retrieve data for
language

"en" or "english" for English and "fr" or "french" for French language versions (defaults to English)
refresh

(Optional) When set to TRUE, forces a reload of data table (default is FALSE)
timeout

(Optional) Timeout in seconds for downloading cansim table to work around scenarios where StatCan servers drop the network connection.
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to TRUE).
default_month

The default month that should be used when creating Date objects for annual data (default set to "07")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01")

Value

A tibble with data for specified vector(s) for the last N periods

Examples

## Not run: 
get_cansim_vector_for_latest_periods("v41690973",10)

## End(Not run)

Retrieve metadata for specified Statistics Canada data vectors

Description

Allows for the retrieval of metadatadata for Statistics Canada data vectors

Usage

get_cansim_vector_info(vectors)

Arguments

vectors

a vector of cansim vectors

Value

A tibble with metadata for selected vectors

Examples

## Not run: 
get_cansim_vector_info("v41690973")

## End(Not run)

Get overview list for all Statistics Canada data cubes

Description

Generates an overview table containing metadata of available Statistics Canada data cubes.

Usage

list_cansim_cubes(lite = FALSE, refresh = FALSE, quiet = FALSE)

Arguments

lite

Get the version without cube dimensions and comments for faster retrieval, default is FALSE.
refresh

Default is FALSE, repeated calls during the same session will hit the cached data.
quiet

Optional, suppress messages To refresh the code list during a running R session set to TRUE

Value

A tibble with available Statistics Canada data cubes, including NDM table number, cube title, start and end dates, achieve status, subject and survey codes, frequency codes and a list of cube dimensions.

Examples

## Not run: 
list_cansim_cubes()

## End(Not run)

List cached cansim SQLite database

Description

List cached cansim SQLite database

Usage

list_cansim_sqlite_cached_tables(
  cache_path = getOption("cansim.cache_path"),
  refresh = FALSE
)

Arguments

cache_path

Optional, default value is 'getOption("cansim.cache_path")'.
refresh

Optional, refresh the last updated date of cached cansim tables

Value

A tibble with the list of all tables that are currently cached at the given cache path.

Examples

## Not run: 
list_cansim_sqlite_cached_tables()

## End(Not run)

Normalize retrieved data table values to appropriate scales

Description

Facilitates working with Statistics Canada data table values retrieved using the package by setting all units to counts/dollars instead of millions, etc. If "replacement_value" is not set, it will replace the VALUE field with normalized values and drop the scale column. Otherwise it will keep the scale columns and create a new column named replacement_value with the normalized value. It will attempt to parse the REF_DATE field and create an R date variable. This is currently experimental.

Usage

normalize_cansim_values(
  data,
  replacement_value = NA,
  normalize_percent = TRUE,
  default_month = "01",
  default_day = "01",
  factors = FALSE,
  strip_classification_code = FALSE,
  cansimTableNumber = NULL
)

Arguments

data

A retrieved data table as returned from get_cansim() pr get_cansim_ndm()
replacement_value

(Optional) the name of the column the manipulated value should be returned in. Defaults to replacing the current value field
normalize_percent

(Optional) When true (the default) normalizes percentages by changing them to rates
default_month

The default month that should be used when creating Date objects for annual data (default set to "01")
default_day

The default day of the month that should be used when creating Date objects for monthly data (default set to "01")
factors

(Optional) Logical value indicating if dimensions should be converted to factors. (Default set to false).
strip_classification_code

(strip_classification_code) Logical value indicating if classification code should be stripped from names. (Default set to false).
cansimTableNumber

(Optional) Only needed when operating on results of SQLite connections.

Value

Returns the input tibble with with adjusted values

Examples

## Not run: 
cansim_table <- get_cansim("34-10-0013")
normalize_cansim_values(cansim_table)

## End(Not run)

Remove cached cansim SQLite database

Description

Remove cached cansim SQLite database

Usage

remove_cansim_sqlite_cached_table(
  cansimTableNumber,
  language = NULL,
  cache_path = getOption("cansim.cache_path")
)

Arguments

cansimTableNumber

Number of the table to be removed
language

Language for which to remove the cached data. If unspecified ('NULL') tables for all languages will be removed
cache_path

Optional, default value is 'getOption("cansim.cache_path")'

Value

'NULL“

Examples

## Not run: 
con <- get_cansim_sqlite("34-10-0013")
disconnect_cansim_sqlite(con)
remove_cansim_sqlite_cached_table("34-10-0013")

## End(Not run)

Search through Statistics Canada data cubes

Description

Searches through Statistics Canada data cubes using a search term.

Usage

search_cansim_cubes(search_term, refresh = FALSE)

Arguments

search_term

User-supplied search term used to find Statistics Canada data cubes with matching titles, table numbers, subject and survey codes.
refresh

Default is FALSE. The underlying cube list is cached for the duration of the R sessions and will regenerate the cube list if set to TRUE

Value

A tibble with available Statistics Canada data cubes, listing title, Statistics Canada data cube catalogue number, deprecated CANSIM table number, survey and subject.

Examples

## Not run: 
search_cansim_cubes("Labour force")

## End(Not run)

View CANSIM table or vector information in browser

Description

Opens CANSIM table or vector on Statistics Canada's website using default browser. This may be useful for getting further info on CANSIM table and survey methods.

Usage

view_cansim_webpage(cansimTableNumber = NULL)

Arguments

cansimTableNumber

CANSIM or NDM table number or cansim vectors with "v" prefix. If no number is provided, the vector search page on the Statistic Canada website will be opened.

Value

none

Examples

## Not run: 
view_cansim_webpage("34-10-0013")

## End(Not run)