Title:	Retrieval and Visualization of Mobility Data from 'Telraam' Sensors
Version:	1.1.2
Description:	Streamline the processing of 'Telraam' data, sourced from open data mobility sensors. These tools range from data retrieval (without the need for API knowledge) to data visualization, including data preprocessing.
License:	CC BY 4.0
BugReports:	https://github.com/KetsiaGuichard/telraamStats/issues/
Imports:	config, dplyr, ggplot2, httr, jsonlite, lubridate, paletteer, purrr, reshape2, rlang, scales, tidyr, yaml
Encoding:	UTF-8
RoxygenNote:	7.3.1
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://annuaire.agistaterre.org/telraamStats/
Depends:	R (≥ 2.10)
LazyData:	true
NeedsCompilation:	no
Packaged:	2024-05-27 09:39:12 UTC; ketsia
Author:	Lilou Augeray [aut], Ulysse Caromel [aut], Ketsia Guichard [aut, cre], Pascal Irz [aut], Mijin Park [aut], Tanguy Richard [aut], Agis-ta-terre [cph, fnd]
Maintainer:	Ketsia Guichard <ketsia.guichard@univ-rennes.fr>
Repository:	CRAN
Date/Publication:	2024-05-27 17:40:02 UTC

Check if options are available in the options list, replace by a default otherwise.

Description

Check if options are available in the options list, replace by a default otherwise.

Usage

check_options_graph(options_selected, options_available, default)

Arguments

Value

Options consistent with the possibilities

Examples

check_options_graph(c('car','pedestrian'),
  c('car','pedestrian','bike','heavy'),c('car','heavy'))
check_options_graph(c('coucou','salut'),
  c('car','pedestrian','bike','heavy'),c('car','heavy'))
check_options_graph(NULL,
  c('car','pedestrian','bike','heavy'),c('car','heavy'))

Convert a character string into a numeric vector

Description

Convert a character string into a numeric vector

Usage

convert_string_to_list(vector)

Arguments

Value

Numeric vector. Something in the shape c(10,20,30)

Examples

convert_string_to_list("10,20,30")

Create config file if needed.

Description

If you want to specify the IDs of your own sensors, this function create a local configuration template file in the ⁠\inst⁠ directory, to edit with specific information. By default, the function doesn't create the file in the project directory but in a temp directory. If you want to have a permanent configuration, please use .

Usage

create_config(
  segments = list(`segment-01` = "9000000000", `segment-02` = "9000000000"),
  create_directory = FALSE,
  overwrite = FALSE
)

Arguments

Details

If you use the temporary options, please fill directly the name and number of your sensors in the "segments" argument.

Value

Boolean: TRUE if the file is created, FALSE overwise (config already exists for example).

Examples

create_config(create_directory=FALSE)
list_of_segments = list("Burel"= "9000002156", "Vitre" = "9000001844")
create_config(segments = list_of_segments,
  create_directory = FALSE,
  overwrite = TRUE) # the file already exists

Enrich traffic data with date informations.

Description

Enrich traffic data with date informations.

Usage

enrich_dates(data)

Arguments

Value

Same dataframe with 3 additionnal columns : day, weekday and hour.

Examples

df <- data.frame('date' = c("2022-02-18 08:00:00 CET","2022-02-18 09:00:00 CET"),
  stringsAsFactors = FALSE)
enrich_dates(df)

Enrich traffic data with segment name

Description

segment_fullname is also added : it's the combination of segment's id and name. segment_id should be in the configuration file.

Usage

enrich_name(data)

Arguments

Value

Same dataframe with two additionnal columns : segment_name and segment_fullname

Examples

df <- data.frame('segment_id' = c(9000002156, 9000001906))
enrich_name(df)

Enrich traffic data with french vacation and public holidays

Description

Enrich traffic data with french vacation and public holidays

Usage

enrich_special_days(data, vacations = NULL, public_holidays = NULL)

Arguments

Value

Same dataframe with two additionnal columns :

• holiday, boolean: TRUE if the day corresponds to public holiday, FALSE otherwise

• vacation, indicating the french vacation, "No vacation" otherwise.

Examples

df <- data.frame('day' = as.Date(c("2022-02-18","2022-01-01")),
  'date' = c('2022-02-18 12:00:00 CET','2022-01-01 12:00:00 CET'))
enrich_special_days(df)

Enrich traffic data with date features, names and uptime filters.

Description

This function add day, weekday, hour, segment_name and full_name and uptime quality boolean. This function is already used by the data retrievement process.

Usage

enrich_traffic(data)

Arguments

Value

Same dataframe with additionnal informations : day, hour, weekday, holiday, vacation, segment_name, uptime_quality

Examples

enriched_traffic <- enrich_traffic(traffic[0:10,])
setdiff(colnames(enriched_traffic[0:10,]), colnames(traffic[0:10,]))

Enrich traffic data with uptime quality indication

Description

If the uptime is lower than 0.5, uptime_quality will be FALSE, else TRUE

Usage

enrich_uptime(data)

Arguments

Value

Same dataframe with an additionnal column indicating if the uptime is greater (TRUE) or lower (FALSE) than 0.5.

Examples

df <- data.frame('uptime' = c(0.05, 0.95))
enrich_uptime(df)

Filter by selected criteria and aggregating traffics.

Description

Not all criteria need to be filled in. Unfilled criteria are set by default so that no filtering is performed.

Usage

filter_agg(
  data,
  date_range = NULL,
  segments = NULL,
  direction = NULL,
  modes = NULL,
  weekdays = NULL,
  hours = NULL,
  uptime_quality = TRUE
)

Arguments

Value

the filtered data, molten by mode and direction, with new columns :

• mode, the mode, one row per different transportation mode + date/hour + direction

• direction, the direction, one row per different transportation mode + date/hour + direction

• traffic_sum, the traffic for this mode/direction on this specific date/hour

Examples

date_range = as.Date(c('2022-01-01','2022-01-08'))
filter_agg(traffic,
  date_range = date_range,
  segments = 'RteVitre-06',
  direction = 'lft',
  modes = 'pedestrian',
  weekdays = 'saturday',
  hours = 12:14,
  uptime_quality = TRUE
  )

Check API state

Description

Return the state of the 'Telraam' API. Determine if updates can be made.

Usage

get_api_state(key = get_telraam_token())

Arguments

Value

Boolean: TRUE if the API responds well, FALSE otherwise.

Examples

my_token <- 'ThisIsNotAValidToken'
get_api_state(my_token)

Get the path of configuration file.

Description

The configuration file could be in the inst directory, or in a temporary directory, according to the create_directory option of the create_config() function. If the configuration file doesn't exist, this function create a file in a temporary directory and send a message to the user.

Usage

get_config_path()

Value

Character: path of the configuration file, needed for a lot of functions.

Examples

create_config(create_directory=FALSE)
get_config_path()

Colors palettes for each option (mode, direction, segment_name, weekday, hour)

Description

Colors palettes for each option (mode, direction, segment_name, weekday, hour)

Usage

get_custom_palette(segments)

Arguments

Value

list of color palettes (named vector) for each option (mode, direction, segment_name, weekday, hour)

Examples

segments <- c('Route1', 'Route2')
get_custom_palette(segments)

Create subtitles for graphics.

Description

Create subtitles for graphics.

Usage

get_graph_subtitles(
  segments = NULL,
  modes = NULL,
  directions = NULL,
  weekdays = NULL,
  hours = NULL
)

Arguments

Value

Character, with a description of all parameters filled, usable as subtitle for graphs.

Examples

get_graph_subtitles(segments = c("Route1"),
  mode = "car", direction = "lft", weekdays = "monday", hours = 12:14)

Get the name of a segment giving its id

Description

Get the name of a segment giving its id

Usage

get_segment_name(segment_id)

Arguments

Value

Name of the segment, as specified in the configuration file, NULL otherwise.

Examples

## Not run:  #run if you want to create a inst/ directory containing config file
  create_config()
  get_segment_name(9000000000)
  
## End(Not run)

Get Telraam segments into a named vector

Description

Get Telraam segments info in yml file and transform them into a named vector

Usage

get_segments()

Value

Named vector with names and segment IDs, NULL if there is no configuration file

Examples

create_config(create_directory = FALSE)
get_segments()

Get the current authentication token for the 'Telraam' API

Description

Get the current authentication token for the 'Telraam' API

Usage

get_telraam_token()

Value

Token currently used, set by set_telraam_token()

Examples

my_token <- "MyTelraamToken"
set_telraam_token(my_token)
get_telraam_token()

Availability and quality of sensors during a period through a heatmap.

Description

Higher is the uptime average, higher is the quality of data. A null uptime means that the sensor wasn't available during this period.

Usage

gg_availability(enriched_data, date_range = NULL)

Arguments

Value

Graph showing availability and quality of sensors over the selected date range.

Examples

 gg_availability(traffic)

Histogram of car speed over a period, for a segment or a subset of segment.

Description

Histogram of car speed over a period, for a segment or a subset of segment.

Usage

gg_car_speed_histogram(
  enriched_data,
  date_range = NULL,
  segments = NULL,
  weekday = NULL,
  hours = NULL,
  aggregated_by = NULL
)

Arguments

Value

Graph showing histogram of car speed over a period.

Examples

library(dplyr)
subset_traffic <- traffic %>% filter(day < '2022-02-01', hour > 9)
gg_car_speed_histogram(subset_traffic)
gg_car_speed_histogram(subset_traffic,
  aggregated_by = 'segment_name')
gg_car_speed_histogram(subset_traffic,
  weekday = c('monday','sunday'),
  segments = 'RteVitre-06',
  hours = 17:20,
  aggregated_by = "weekday")

Average of v85 car speed per hour over a period, for a segment or a subset of segment.

Description

v85 is the estimated car speed limit in km/h that 85% of all cars respect. 15% of drivers drive faster than this v85 indicator.

Usage

gg_car_speed_v85(
  enriched_data,
  date_range = NULL,
  segments = NULL,
  weekday = NULL,
  hours = NULL,
  aggregated_by = NULL
)

Arguments

Value

Graph showing the average of v85 speed per hour.

Examples

library(dplyr)
subset_traffic <- traffic %>% filter(day < '2022-02-01', hour > 9)
gg_car_speed_histogram(subset_traffic[0:100,])
gg_car_speed_histogram(subset_traffic, aggregated_by = 'segment_name')
gg_car_speed_histogram(subset_traffic,
  weekday = c('monday','sunday'),
  segments = 'RteVitre-06',
  hours = 17:20,
  aggregated_by = "weekday")

Average of traffic during a week.

Description

A short description... Average of traffic during a week, over a period for a segment or a subset of segment, for a transportation mode or more, for a direction or both.

Usage

gg_traffic_avg(
  enriched_data,
  date_range = NULL,
  segments = NULL,
  modes = c("heavy", "car"),
  direction = "both",
  weekday = NULL,
  aggregated_by = "weekday"
)

Arguments

Value

Graph showing weekly average evolution of traffic (for specified parameters) during the specified period.

Examples

gg_traffic_avg(traffic)
gg_traffic_avg(traffic,
  date_range = c('2022-07-01','2022-09-01'),
  segment = 'RteVitre-06',
  mode = 'car',
  direction = 'rgt',
  weekday = c('monday','friday')
  )

Evolution of traffic and smoothed traffic.

Description

Evolution of traffic (global, per mode ou per direction), smoothed traffic during a period.

Usage

gg_traffic_evolution(
  enriched_data,
  date_range = NULL,
  segments = NULL,
  modes = c("heavy", "car"),
  direction = "both",
  smoothed = TRUE,
  agg_day = TRUE
)

Arguments

Value

Graph showing the evolution of traffic (for specified parameters) during the specified period.

Examples

gg_traffic_evolution(traffic)
gg_traffic_evolution(traffic,
  date_range = c('2022-01-01','2022-03-01'),
  segment = 'RteVitre-06',
  mode = c('car','pedestrian'),
  direction = 'lft',
  smoothed = FALSE,
  agg_day = FALSE)

Imports data associated with a list of sensors

Description

Imports data associated with a given list of sensor names from .RData files contained in a data directory. The main purpose of this function is to load the data saved with write update data.

Usage

import_sensor(list_sensor)

Arguments

Value

A dataframe containing the imported data.

Examples

## Not run:  # This example requires a valid API key
period <- as.Date(c('2022-01-01', '2022-12-31'))
write_update_data('RteVitre-06', period[1], period[2])
write_update_data('ParisArcEnCiel-05', period[1], period[2])
import_sensor(c('RteVitre-06', 'ParisArcEnCiel-05'))

## End(Not run)

Indicates if a date is in vacation period and if true, which vacation.

Description

If the date is not in a vacation period, "No vacation" is returned.

Usage

is_vacation(date, vacation)

Arguments

Value

Vacation description if the day is between two dates, "No vacation" otherwise.

Examples

vacation <- data.frame('description' = c('Vacances de Noël'),
  start_date = as.POSIXct('2021-12-17 23:00:00'),
  end_date = as.POSIXct('2022-01-02 23:00:00'))
is_vacation(as.Date('2022-01-01'), vacation)

Melt dataframe to obtain one row per hour/segment/transportation mode/direction This format makes graphs with ggplot and filtering easier.

Description

Melt dataframe to obtain one row per hour/segment/transportation mode/direction This format makes graphs with ggplot and filtering easier.

Usage

melt_direction_mode(data)

Arguments

Value

DataFrame with one row per hour/segment/transportation mode/direction

Examples

melt_direction_mode(traffic[0:2,])

Preprocessing mandatory for car speed graphs functions

Description

Preprocessing mandatory for car speed graphs functions

Usage

preprocess_car_speed(
  enriched_data,
  aggregated_by,
  date_range,
  segments,
  weekday,
  hours
)

Arguments

Value

list of parameters and data preprocessed.

Examples

preprocess_car_speed(traffic,
  date_range = c('2022-01-01','2022-03-01'),
  segments = 'RteVitre-06',
  weekday = c('monday','sunday'),
  hours = 17:20,
  aggregated_by = "weekday")

Retrieves data associated with a sensor from the Telraam API

Description

Retrieves data associated with a sensor from the Telraam API. The data is retrieved for a specified time period between start_date and end_date (inclusive).

Usage

retrieve_sensor(segment_name, start_date, end_date, key = get_telraam_token())

Arguments

Value

Dataframe from Telraam API, enriched with enrich_traffic() function.

Examples

## Not run:  # This function requires a valid API key
period <- as.Date(c('2022-01-01', '2022-12-31'))
retrieve_sensor('RteVitre-06', period[1], period[2])

## End(Not run)

Generate sequence of intervals with three-month periods

Description

This function is used internally in the retrieve_sensor function to generate a sequence of intervals with three-month periods. It takes a start date (start_date) and an end date (end_date), and returns a data frame with two columns representing the start and end dates of each interval.

Usage

seq_by_3_month(start_date, end_date)

Arguments

Value

Dataframe with a start and an end columns, each row represents 3 months period.

Examples

seq_by_3_month(as.Date('2023-11-01'),as.Date('2024-11-01'))

Function to set up the global variables for public holidays and vacations, with the default being the french dates from a governmental API.

Description

Function to set up the global variables for public holidays and vacations, with the default being the french dates from a governmental API.

Usage

set_global_vars(vacations = NULL, public_holidays = NULL)

Arguments

Value

Don't return anything, set up the global variables for public holidays and vacations.

Examples

pkg.globals <- new.env(parent = emptyenv())
set_global_vars()
print(pkg.globals$vacations)

Saves an authentication token for the 'Telraam' API.

Description

If you want to get this token after this instruction, please use get_telraam_token().

Usage

set_telraam_token(token)

Arguments

Value

Boolean: TRUE if the token is correctly set

Examples

my_token <- "MyTelraamToken"
set_telraam_token(my_token)
get_telraam_token()

Traffic data of Telraam sensors in Châteaubourg (FR)

Description

Telraam sensors continously monitor a street form a citizen window. They count heavy vehicules, cars, twok-wheelers and pedestrians, every hour. Châteaubourg is one of the city in France with the highest density of sensors This dataframe is a subset of sensors data in Châteaubourg for 2022. Additional properties are not present natively in the Telraam API but are added by the package.

Usage

traffic

Format

traffic

A data frame with 16,729 rows and 22 columns:

instance_id

Sensor number. Equals -1 if the API request was made for a road segment and not for a camera.

segment_id

Road segment Telraam ID. Equals -1 if the API request was made for a camera and not for a road segment.

segment_name

Additional property - Segment name specified in configuration file.

segment_fullname

Additional property - Concatenation of the segment_id and the segment name specified in configuration.

date

date and UTC time of the reporting interval (beginning of the interval).

day

Additional property - Day of the reporting interval.

hour

Additional property - Hour of the reporting interval.

weekday

Additional property - Weekday of the reporting interval.

holiday

Additional property - boolean, indicates whether this entry is during a French public holiday.

vacation

Indicates whether this entry is during a French vacation period, and if true, the vacation period name.

interval

can be "hourly" or "daily" for hourly or daily aggregate data.

uptime

between 0 and 1, represents the portion of the reporting interval that was actively spent counting the traffic

uptime_quality

Additional property - boolean, indicates whether this entry has an uptime greather or equal than 0.

heavy, heavy_lft, heavy_rgt

number of heavy vehicles, total and in both directions.

car, car_lft, car_rgt

number of cars, total and in both directions.

bike, bike_lft, bike_rgt

number of two-wheelers, total and in both directions.

pedestrian, pedestrian_lft, pedestrian_rgt

number of pedestrians, total and in both directions.

direction

1, internal consistency value for Telraam.

car_speed_hist_0to70plus, car_speed_hist_0to120plus

the estimated car speed distribution in 10 km/h bins from 0 to 70+ km/h or 120+ km/h (in percentage of the total 100%).

timezone

name of the Time zone where the segment can be found.

v85

estimated car speed limit in km/h that 85% of all cars respect

Source

https://telraam-api.net/

Write or update the sensor data in the data folder

Description

Writes or updates the sensor data in the data folder. It retrieves the data for the specified sensor between start_date and end_date (inclusive) using the retrieve_sensor function, and then converts certain columns to character strings before writing the data to a RData file in the data folder (if create_directory = TRUE), to a temporary folder otherwise.

Usage

write_update_data(segment_name, start_date, end_date, create_directory = FALSE)

Arguments

Value

Boolean: TRUE if the data is well saved/written, FALSE otherwise (no data for example)

Examples

## Not run:  # This function requires a valid API key
period <- as.Date(c('2022-01-01', '2022-12-31'))
write_update_data('RteVitre-06', period[1], period[2])

## End(Not run)