iplot_pheno {AeRobiology}

Phenological Plot

Description

Generates a boxplot based on phenological parameters (start_dates and end_dates) that are calculated by the estimation of the main parameters of the pollen season

Usage

iplot_pheno(data, method = "percentage", n.types = 15, th.day = 100,
  perc = 95, def.season = "natural", reduction = FALSE,
  red.level = 0.9, derivative = 5, man = 11, th.ma = 5,
  n.clinical = 5, window.clinical = 7, window.grains = 5,
  th.pollen = 10, th.sum = 100, type = "none",
  interpolation = TRUE, int.method = "lineal", type.plot = "static",
  export.plot = FALSE, export.format = "pdf", ...)

Arguments

data

A data.frame object including the general database where calculation of the pollen season must be applied in order to generate the phenological plot based on the start_dates and end_dates. This data.frame must include a first column in Date format and the rest of columns in numeric format belonging to each pollen type by column.

method

A character string specifying the method applied to calculate the pollen season and the main parameters. The implemented methods that can be used are: "percentage", "logistic", "moving", "clinical" or "grains". A more detailed information about the different methods for defining the pollen season may be consulted in calculate_ps function.

n.types

A numeric (integer) value specifying the number of the most abundant pollen types that must be represented in the pollen calendar. A more detailed information about the selection of the considered pollen types may be consulted in Details. The n.types argument will be 15 types by default.

th.day

A numeric value in order to calculate the number of days when this level is exceeded for each year and each pollen type. This value will be obtained in the results of the function. The th.day argument will be 100 by default.

perc

A numeric value ranging 0_100. This argument is valid only for method = "percentage". This value represents the percentage of the total annual pollen included in the pollen season, removing (100_perc)/2% of the total pollen before and after of the pollen season. The perc argument will be 95 by default.

def.season

A character string specifying the method for selecting the best annual period to calculate the pollen season. The pollen seasons may occur within the natural year or otherwise may occur between two years which determines the best annual period considered. The implemented options that can be used are: "natural", "interannual" or "peak". The def.season argument will be "natural" by default. A more detailed information about the different methods for selecting the best annual period to calculate the pollen season may be consulted in calculate_ps function.

reduction

A logical value. This argument is valid only for the "logistic" method. If FALSE the reduction of the pollen data is not applicable. If TRUE a reduction of the peaks above a certain level (red.level argument) will be carried out before the definition of the pollen season. The reduction argument will be FALSE by default. A more detailed information about the reduction process may be consulted in calculate_ps function.

red.level

A numeric value ranging 0_1 specifying the percentile used as level to reduce the peaks of the pollen series before the definition of the pollen season. This argument is valid only for the "logistic" method. The red.level argument will be 0.90 by default, specifying the percentile 90.

derivative

A numeric (integer) value belonging to options of 4, 5 or 6 specifying the derivative that will be applied to calculate the asymptotes which determines the pollen season using the "logistic" method. This argument is valid only for the "logistic" method. The derivative argument will be 5 by default.

man

A numeric (integer) value specifying the order of the moving average applied to calculate the pollen season using the "moving" method. This argument is valid only for the "moving" method. The man argument will be 11 by default.

th.ma

A numeric value specifying the threshold used for the "moving" method for defining the beginning and the end of the pollen season. This argument is valid only for the "moving" method. The th.ma argument will be 5 by default.

n.clinical

A numeric (integer) value specifying the number of days which must exceed a given threshold (th.pollen argument) for defining the beginning and the end of the pollen season. This argument is valid only for the "clinical" method. The n.clinical argument will be 5 by default.

window.clinical

A numeric (integer) value specifying the time window during which the conditions must be evaluated for defining the beginning and the end of the pollen season using the "clinical" method. This argument is valid only for the "clinical" method. The window.clinical argument will be 7 by default.

window.grains

A numeric (integer) value specifying the time window during which the conditions must be evaluated for defining the beginning and the end of the pollen season using the "grains" method. This argument is valid only for the "grains" method. The window.grains argument will be 5 by default.

th.pollen

A numeric value specifying the threshold that must be exceeded during a given number of days (n.clinical or window.grains arguments) for defining the beginning and the end of the pollen season using the "clinical" or "grains" methods. This argument is valid only for the "clinical" or "grains" methods. The th.pollen argument will be 10 by default.

th.sum

A numeric value specifying the pollen threshold that must be exceeded by the sum of daily pollen during a given number of days (n.clinical argument) exceeding a given daily threshold (th.pollen argument) for defining the beginning and the end of the pollen season using the "clinical" method. This argument is valid only for the "clinical" method. The th.sum argument will be 100 by default.

type

A character string specifying the parameters considered according to a specific pollen type for calculating the pollen season using the "clinical" method. The implemented pollen types that may be used are: "birch", "grasses", "cypress", "olive" or "ragweed". As result for selecting any of these pollen types the parameters n.clinical, window.clinical, th.pollen and th.sum will be automatically adjusted for the "clinical" method. If no pollen types are specified (type = "none"), these parameters will be considered by the user. This argument is valid only for the "clinical" method. The type argument will be "none" by default.

interpolation

A logical value. If FALSE the interpolation of the pollen data is not applicable. If TRUE an interpolation of the pollen series will be applied to complete the gaps with no data before the calculation of the pollen season. The interpolation argument will be TRUE by default. A more detailed information about the interpolation method may be consulted in Details.

int.method

A character string specifying the method selected to apply the interpolation method in order to complete the pollen series. The implemented methods that may be used are: "lineal", "movingmean", "spline" or "tseries". The int.method argument will be "lineal" by default.

type.plot

A character string specifying the type of plot selected to show the phenological plot. The implemented types that may be used are: "static" generates a static ggplot object and "dynamic" generates a dynamic plotly object.

export.plot

A logical value specifying if a phenological plot saved in the working directory will be required or not. If FALSE graphical results will only be displayed in the active graphics window. If TRUE graphical results will be displayed in the active graphics window and also a pdf or png file (according to the export.format argument) will be saved within the plot_AeRobiology directory automatically created in the working directory. This argument is applicable only for "static" plots. The export.plot will be FALSE by default.

export.format

A character string specifying the format selected to save the phenological plot. The implemented formats that may be used are: "pdf" and "png". This argument is applicable only for "static" plots. The export.format will be "pdf" by default.

...

Other additional arguments may be used to customize the exportation of the plots using pdf or png files and therefore arguments from pdf and png functions (grDevices package) may be implemented. For example, for pdf files the user may custom the arguments: width, height, family, title, fonts, paper, bg, fg, pointsize...; and for png files the user may custom the arguments: width, height, units, pointsize, bg, res...

Details

This function allows to calculate the pollen season using five different methods which are described in calculate_ps function. After calculating the start_date and end_date for each pollen type and each year a phenological plot will be generated using the boxplot approach where axis x represents the time (Day of the Year) and axis y includes the considered pollen types. The phenological plot will be generated only for the specified number of the most abundant pollen types using the n.types argument by the user. The implemented methods for defining the pollen season includes the most commonly used methodologies (Nilsson and Persson, 1981; Andersen, 1991; Galan et al., 2001; Ribeiro et al., 2007; Cunha et al., 2015, Pfaar et al., 2017) and a new implemented method (see calculate_ps function).
Pollen time series frequently have different gaps with no data and this fact could be a problem for the calculation of specific methods for defining the pollen season even providing incorrect results. In this sense by default a linear interpolation will be carried out to complete these gaps before to define the pollen season (interpolation = TRUE). Additionally, the users may select other interpolation methods using the int.method argument, as "lineal", "movingmean", "spline" or "tseries". For more information to see the interpollen function.

Value

This function returns different results:
If export.plot = FALSE graphical results will only be displayed in the active graphics window as ggplot graph. Additional characteristics may be incorporated to the plot by ggplot syntax (see ggplot2 package).
If export.plot = TRUE and export.format = pdf a pdf file of the phenological plot will be saved within the plot_AeRobiology directory created in the working directory. This option is applicable only for "static" plots. Additional characteristics may be incorporated to the exportation as pdf file (see grDevices package).
If export.plot = TRUE and export.format = png a png file of the phenological plot will be saved within the plot_AeRobiology directory created in the working directory. This option is applicable only for "static" plots. Additional characteristics may be incorporated to the exportation png file (see grDevices package).
If type.plot = dynamic graphical results will be displayed in the active Viewer window as plotly graph. Additional characteristics may be incorporated to the plot plotly syntax (see plotly package).

References

Andersen, T.B., 1991. A model to predict the beginning of the pollen season. Grana, 30(1), pp.269_275.

Cunha, M., Ribeiro, H., Costa, P. and Abreu, I., 2015. A comparative study of vineyard phenology and pollen metrics extracted from airborne pollen time series. Aerobiologia, 31(1), pp.45_56.

Galan, C., Garcia_Mozo, H., Carinanos, P., Alcazar, P. and Dominguez_Vilches, E., 2001. The role of temperature in the onset of the Olea europaea L. pollen season in southwestern Spain. International Journal of Biometeorology, 45(1), pp.8_12.

Nilsson, S. and Persson, S., 1981. Tree pollen spectra in the Stockholm region (Sweden), 1973_1980. Grana, 20(3), pp.179_182.

Pfaar, O., Bastl, K., Berger, U., Buters, J., Calderon, M.A., Clot, B., Darsow, U., Demoly, P., Durham, S.R., Galan, C., Gehrig, R., Gerth van Wijk, R., Jacobsen, L., Klimek, L., Sofiev, M., Thibaudon, M. and Bergmann, K.C., 2017. Defining pollen exposure times for clinical trials of allergen immunotherapy for pollen_induced rhinoconjunctivitis_an EAACI position paper. Allergy, 72(5), pp.713_722.

Ribeiro, H., Cunha, M. and Abreu, I., 2007. Definition of main pollen season using logistic model. Annals of Agricultural and Environmental Medicine, 14(2), pp.259_264.

See Also

calculate_ps, interpollen

Examples

data("munich_pollen")
iplot_pheno (munich_pollen, interpolation = FALSE)