calculate_ps: Estimation of the Main Parameters of the Pollen Season
In AeRobiology: A Computational Tool for Aerobiological Data

Description Usage Arguments Details Value References See Also Examples

Function to calculate the main parameters of the pollen season with regard to phenology and pollen intensity from a historical database of several pollen types. The function can use the most common methods in the definition of the pollen season.

calculate_ps(data, method = "percentage", 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", maxdays = 30, result = "table",
  plot = TRUE, export.plot = FALSE, export.result = FALSE)

`data`	A `data.frame` object including the general database where calculation of the pollen season must be applied. 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 Details.
`th.day`	A `numeric` value. The number of days whose pollen concentration is bigger than this threshold is calculated for each year and 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 between two years. 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 Details.
`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 Details.
`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. More information may be consulted in Details.
`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.
`maxdays`	A `numeric` (`integer` value) specifying the maximum number of consecutive days with missing data that the algorithm is going to interpolate. If the gap is bigger than the argument value, the gap will not be interpolated. Not valid with `int.method = "tseries"`. The `maxdays` argument will be `30` by default.
`result`	A `character` string specifying the output for the function. The implemented outputs that may be obtained are: `"table"` and `"list"`. The argument `result` will be `"table"` by default.
`plot`	A `logical` value specifying if a set of plots based on the definition of the pollen season will be shown in the plot history or not. If `FALSE` graphical results will not be shown. If `TRUE` a set of plots will be shown in the plot history. The `plot` argument will be `TRUE` by default.
`export.plot`	A `logical` value specifying if a set of plots based on the definition of the pollen season will be saved in the workspace. If `TRUE` a pdf file for each pollen type showing graphically the definition of the pollen season for each studied year will be saved within the plot_AeRobiology directory created in the working directory. The `plot` argument will be `FALSE` by default.
`export.result`	A `logical` value specifying if a excel file including all parameters for the definition of the pollen season saved in the working directoty will be required or not. If `FALSE` the results will not exported. If `TRUE` the results will be exported as xlsx file including all parameters calculated from the definition of the pollen season within the table_AeRobiology directory created in the working directory. The `export.result` argument will be `FALSE` by default.

This function allows to calculate the pollen season using five different methods which are described below. After calculating the start_date, end_date and peak_date for the pollen season all rest of parameters have been calculated as detailed in Value section.

"percentage" method. This is a commonly used method for defining the pollen season based on the elimination of a certain percentage in the beginning and the end of the pollen season (Nilsson and Persson, 1981; Andersen, 1991). For example if the pollen season is based on the 95% of the total annual pollen ("perc" = 95), the start_date of the pollen season is marked as the day in which 2.5% of the total pollen is registered and the end_date of the pollen season is marked as the day in which 97.5% of the total pollen is registered.
"logistic" method. This method was developed by Ribeiro et al. (2007) and modified by Cunha et al. (2015). It is based on fitting annually a non_linear logistic regression model to the daily accumulated curve for each pollen type. This logistic function and the different derivatives were considered to calculate the start_date and end_date of the pollen season, based on the asymptotes when pollen amounts are stabilized on the beginning and the end of the accumulated curve. For more information about the method to see Ribeiro et al. (2007) and Cunha et al. (2015). Three different derivatives may be used (derivative argument) 4, 5 or 6 that represent from higher to lower restrictive criterion for defining the pollen season. This method may be complemented with an optional method for reduction the peaks values (reduction = TRUE), thus avoiding the effect of the great influence of extreme peaks. In this sense, peaks values will be cut below a certain level that the user may select based on a percentile analysis of peaks. For example, red.level = 0.90 will cut all peaks above the percentile 90.
"moving" method. This method is proposed the first time by the authors of this package. The definition of the pollen season is based on the application of a moving average to the pollen series in order to obtain the general seasonality of the pollen curve avoiding the great variability of the daily fluctuations. Thus, the start_date and the end_date will be established when the curve of the moving average reaches a given pollen threshold (th.ma argument). Also the order of the moving average may be customized by the user (man argument). By default, man = 11 and th.ma = 5.
"clinical" method. This method was proposed by Pfaar et al. (2017). It is based on the expert consensus in relation to pollen exposure and the relationship with allergic symptoms derived of the literature. Different periods may be defined by this method: the pollen season, the high pollen season and the high pollen days. The start_date and end_date of the pollen season were defined as a certain number of days (n.clinical argument) within a time window period (window.clinical argument) exceeding a certain pollen threshold (th.pollen argument) which summation is above a certain pollen sum (th.sum argument). All these parameters are established for each pollen type according to Pfaar et al. (2017) and using the type argument these parameters may be automatically adjusted for the specific pollen types ("birch", "grasses", "cypress", "olive" or "ragweed"). Furthermore, the user may change all parameters to do a customized definition of the pollen season. The start_date and end_date of the high pollen season were defined as three consecutive days exceeding a certain pollen threshold (th.day argument). The number of high pollen days will also be calculated exceeding this pollen threshold (th.day). For more information about the method to see Pfaar et al. (2017).
"grains" method. This method was proposed by Galan et al. (2001) originally in olive pollen but after also applied in other pollen types. The start_date and end_date of the pollen season were defined as a certain number of days (window.grains argument) exceeding a certain pollen threshold (th.pollen argument). For more information about the method to see Galan et al. (2001).

The pollen season of the species may occur during the natural year (Calendar year: from 1. January to 31. December) or the start_date and the end_date of the pollen season may happen in two different natural years (or calendar years). This consideration has been taken into account and in this package different method for defining the period for calculating the pollen season have been implemented. In this sense, the def.season argument has been incorporated in three options:

"natural": considering the pollination year as natural year from 1st January to 31th December for defining the start_dates and end_dates of the pollen season for each pollen types.
"interannual": considering the pollination year from 1st June to 31th May for defining the start_dates and end_dates of the pollen season for each pollen types.
"peak": considering a customized pollination year for each pollen types calculated as 6 previous months and 6 later months from the average peak_date.

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.

This function returns different results:
data.frame when result = "table" including the main parameters of the pollen season with regard to phenology and pollen intensity as:

type: pollen type
seasons: year of the beginning of the season
st.dt: start_date (date)
st.jd: start_date (day of the year)
en.dt: end_date (date)
en.jd: end_date (day of the year)
ln.ps: length of the season
sm.tt: total sum
sm.ps: pollen integral
pk.val: peak value
pk.dt: peak_date (date)
pk.jd: peak_date (day of year)
ln.prpk: length of the pre_peak period
sm.prpk: pollen integral of the pre_peak period
ln.pspk: length of the post_peak period
sm.pspk: pollen integral of the post_peak period
daysth: number of days with more than 100 pollen grains
st.dt.hs: start_date of the High pollen season (date, only for clinical method)
st.jd.hs: start_date of the High pollen season (day of the year, only for clinical method)
en.dt.hs: end_date of the High pollen season (date, only for clinical method)
en.jd.hs: end_date of the High pollen season (day of the year, only for clinical method)

list when result = "list" including the main parameters of the pollen season, one pollen type by element plots when plot = TRUE showing graphically the definition of the pollen season for each studied year in the plot history. If export.result = TRUE this data.frame will also be exported as xlsx file within the table_AeRobiology directory created in the working directory. If export.result = FALSE the results will also be showed as list object named list.ps.
If export.plot = TRUE a pdf file for each pollen type showing graphically the definition of the pollen season for each studied year will be saved within the plot_AeRobiology directory created in the working directory.

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.

interpollen, plot_ps