Analyze LCZ Time Series

This function generates a graphical representation of time series air temperature data across different Local Climate Zones (LCZs). It allows for flexible temporal aggregation, faceting, smoothing, and visualization options including heatmaps, facet_plot line plots, and warming stripes. For more details on LCZ analysis, visit https://bymaxanjos.github.io/LCZ4r/articles/Introd_local_LCZ4r.html.

Usage

lcz_ts(
  x,
  data_frame = "",
  var = "",
  station_id = "",
  ...,
  time.freq = "hour",
  extract.method = "simple",
  plot_type = "basic_line",
  facet_plot = "LCZ",
  by = NULL,
  smooth = FALSE,
  impute = NULL,
  iplot = TRUE,
  isave = FALSE,
  save_extension = "png",
  palette = "VanGogh2",
  ylab = "Air temperature [Degree Celsius]",
  xlab = "Time",
  title = "LCZ - Timeseries",
  caption = "LCZ4r, 2024.",
  legend_name = "Temperature (C)"
)

Arguments

x

A SpatRaster object containing the LCZ map. The LCZ map can be obtained using the lcz_get_map(), lcz_get_map_euro(), and lcz_get_map_usa() functions.

data_frame

A data frame containing air temperature measurements and station IDs. The data frame should have a date field in hourly or higher resolution format.

var

The name of the variable in the data frame representing air temperature.

station_id

The name of the variable in the data frame representing station IDs.

...

Additional arguments for the selectByDate function from the openair package. These arguments allow for flexible selection of specific time periods (year, month, day, hour). Examples of how to use these arguments include:

Year(s): Numeric value(s) specifying the year(s) to select. For example, year = 1998:2004 selects all years between 1998 and 2004 (inclusive), while year = c(1998, 2004) selects only the years 1998 and 2004.
Month(s): Numeric or character value(s) specifying the months to select. Numeric examples: month = 1:6 (January to June), or character examples: month = c("January", "December").
Day(s): Numeric value(s) specifying the days to select. For instance, day = 1:30 selects days from 1 to 30, or day = 15 selects only the 15th day of the month.
Hour(s): Numeric value(s) specifying the hours to select. For example, hour = 0:23 selects all hours in a day, while hour = 9 selects only the 9th hour.
Start date: A string specifying the start date in either start="DD/MM/YYYY" (e.g., "1/2/1999") or "YYYY-mm-dd" format (e.g., "1999-02-01").
End date: A string specifying the end date in either end="DD/MM/YYYY" (e.g., "1/2/1999") or "YYYY-mm-dd" format (e.g., "1999-02-01").

time.freq

Defines the time period to average to. Default is “hour”, but includes “day”, “week”, “month” or “year”.

extract.method

A character string specifying the method used to assign the LCZ class to each station point. The default is "simple". Available methods are:

simple: Assigns the LCZ class based on the value of the raster cell in which the point falls. It often is used in low-density observational network.
two.step: Assigns LCZs to stations while filtering out those located in heterogeneous LCZ areas. This method requires that at least 80% of the pixels within a 5 × 5 kernel match the LCZ of the center pixel (Daniel et al., 2017). Note that this method reduces the number of stations. It often is used in ultra and high-density observational network, especially in LCZ classes with multiple stations.
bilinear: Interpolates the LCZ class values from the four nearest raster cells surrounding the point.

plot_type

A character string indicating the type of plot to generate. Options include: “basic_line”, “facet_line”, “heatmap”, “warming_stripes”. The default is “basic_line”. Note: This argument does not work if the by argument is active.

facet_plot

A character string indicating whether to divide the plot by “LCZ” or “station”. The default is “LCZ”.

by

data frame time-serie split: “year”, “season”, “seasonyear”, “month”, “monthyear”, “weekday”, “weekend”, “site”, “daylight”, “dst” (daylight saving time). Note that the Daylight option may result in both daytime and nighttime hours being represented in UTC. See NOAA https://gml.noaa.gov/grad/solcalc/ and argument type in openair package: https://openair-project.github.io/book/sections/intro/openair-package.html#the-type-option

smooth

Logical. Set to TRUE to add a smoothed trend line using a generalized additive model (GAM). The default is FALSE.

impute

Method to impute missing values (“mean”, “median”, “knn”, “bag”).

iplot

Set to TRUE to return a plot. If FALSE, a data frame is returned.

isave

Set to TRUE to save all results (plot, time-series) into your directory.

save_extension

A character string indicating the file format for saving the plot. Options include: “png”, “jpg”, “jpeg”, “tif”, “pdf”, “svg”. The default is “png”.

palette

A character string specifying the color palette to use. The default is “VanGogh2”. You can choose from palettes available in MetBrewer: https://github.com/BlakeRMills/MetBrewer?tab=readme-ov-file#palettes.

ylab

A character string for the y-axis label. The default is the variable name.

xlab

A character string for the x-axis label. The default is “Time”.

title

A character string for the plot title. The default is “""”.

caption

source data. Default can be “Source:LCZ4r,2024"”.

legend_name

Legend name for heatmap and warming stripes plots. Default is "Temperature (°C)".

Value

A ggplot object representing the time series of air temperature in different LCZs, or a data frame in CSV format if iplot = FALSE.

Author

Max Anjos (https://github.com/ByMaxAnjos)

Examples

if (FALSE) { # \dontrun{
# Hourly air temperature values in 2019.
my_ts <- lcz_ts(lcz_map, df = lcz_data, var = "airT",
                 station_id = "station", year = 2020)

} # }

Usage

Arguments

Value

See also

Author

Examples