pollen_calendar: Pollen Calendar by Different Methods from a Historical Pollen...
In AeRobiology: A Computational Tool for Aerobiological Data

Description Usage Arguments Details Value References See Also Examples

Function to calculate the pollen calendar from a historical database of several pollen types and using the most commonly used methods in the generation of the pollen calendars in the aerobiology field.

pollen_calendar(data, method = "heatplot", n.types = 15,
  start.month = 1, y.start = NULL, y.end = NULL, perc1 = 80,
  perc2 = 99, th.pollen = 1, average.method = "avg_before",
  period = "daily", method.classes = "exponential", n.classes = 5,
  classes = c(25, 50, 100, 300), color = "green",
  interpolation = TRUE, int.method = "lineal", na.remove = TRUE,
  result = "plot", export.plot = FALSE, export.format = "pdf",
  legendname = "Pollen grains / m3", ...)

`data`	A `data.frame` object including the general database where calculation of the pollen calendar 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 and generate the pollen calendar. The implemented methods that can be used are: `"heatplot"`, `"violinplot"` or `"phenological"`. A more detailed information about the different methods for defining the pollen season may be consulted in Details. The `method` argument will be `heatplot` by default.
`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.
`start.month`	A `numeric` (`integer`) value ranging `1_12` specifying the number of the month (January_December) when the beginning of the pollen calendar must be considered. This argument is only applicable for the `"heatplot"` method with `"daily"` period, for the `"phenological"` method with `"avg_before"` `average.method`, and for the `"violinplot"` method, and the rest of methods only may be generated from the January (`start.month = 1`). The `start.month` argument will be `1` (month of January) by default.
`y.start, y.end`	A `numeric` (`integer`) value specifying the period selected to calculate the pollen calendar (start year _ end year). If `y.start` and `y.end` are not specified (`NULL`), the entire database will be used to generate the pollen calendar. The `y.start` and `y.end` arguments will be `NULL` by default.
`perc1, perc2`	A `numeric` value ranging `0_100`. These arguments are valid only for the `"phenological"` method. These values represent the percentage of the total annual pollen included in the pollen season, removing `(100_percentage)/2%` of the total pollen before and after of the pollen season. Two percentages must be specified because of the definition of the "main pollination period" (`perc1`) and "early/late pollination" (`perc2`) based on the `"phenological"` method proposed by Werchan et al. (2018). The `perc1` argument will be `80` and `perc2` argument will be `99` by default. A more detailed information about the `phenological` method to generate the pollen calendar may be consulted in Details.
`th.pollen`	A `numeric` value specifying the minimum threshold of the average pollen concentration which will be used to generate the pollen calendar. Days below this threshold will not be considered. For the `"phenological"` method this value limits the "possible occurrence" period as proposed by Werchan et al. (2018). The `th.pollen` argument will be `1` by default. A more detailed information about the methods to generate the pollen calendar may be consulted in Details.
`average.method`	A `character` string specifying the moment of the application of the average. This argument is valid only for the `"phenological"` method. The implemented methods that can be used are: `"avg_before"` or `"avg_after"`. `"avg_before"` produces the average to the daily concentrations and then pollen season are calculated for all pollen types, this method is recommended as it is a more concordant method with respect to the rest of implemented methods. Otherwise, `"avg_after"` determines the pollen season for all years and all pollen types, and then a circular average is calculated for the start_dates and end_dates. The `average.method` argument will be `"avg_before"` by default.
`period`	A `character` string specifying the interval time considered to generate the pollen calendar. This argument is valid only for the `"heatplot"` method. The implemented periods that can be used are: `"daily"` or `"weekly"`. `"daily"` selection produces a pollen calendar using daily averages during the year and `"weekly"` selection produces a pollen calendar using weekly averages during the year. The `period` argument will be `"daily"` by default.
`method.classes`	A `character` string specifying the method to define the classes used for classifying the average pollen concentrations to generate the pollen calendar. This argument is valid only for the `"heatplot"` method. The implemented methods for defining classes are: `"exponential"` and `"custom"`. The `method.classes` argument will be `"exponential"` by default. A more detailed information about the methods to classify the average pollen concentrations to generate the pollen calendar may be consulted in Details.
`n.classes`	A `numeric` (`integer`) value specifying the number of classes that will be used for classifying the average pollen concentrations to generate the pollen calendar. This argument is valid only for the `"heatplot"` method and the classification by `method.classes = "custom"`. The `n.classes` argument will be `5` by default. A more detailed information about the methods to classify the average pollen concentrations to generate the pollen calendar may be consulted in Details.
`classes`	A `numeric` vector specifying the threshold established to define the different classes that will be used for classifying the average pollen concentrations to generate the pollen calendar. This argument is valid only for the `"heatplot"` method and the classification by `method.classes = "custom"`. The `classes` argument will be `c(25, 50, 100, 300)` by default. The number of specified classes must be equal to `n.classes _ 1` because of the maximum threshold will be automatically specified by the maximum value. A more detailed information about the methods to classify the average pollen concentrations to generate the pollen calendar may be consulted in Details.
`color`	A `character` string specifying the color to generate the graph showing the pollen calendar. This argument is valid only for the `"heatplot"` method. The implemented color palettes to generate the pollen calendar are: `"green"`, `"red"`, `"blue"`, `"purple"` or `"black"`. The `color` argument will be `"green"` 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 before the calculation of the pollen calendar. 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.
`na.remove`	A `logical` value specifying if `na` values must be remove for the pollen calendar or not. `n.remove = TRUE` by default.
`result`	A `character` string specifying the output for the function. The implemented outputs that may be obtained are: `"plot"` and `"table"`. The argument `result` will be `"plot"` by default.
`export.plot`	A `logical` value specifying if a plot with the pollen calendar 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 file will be saved within the plot_AeRobiology directory automatically created in the working directory. The `export.plot` will be `FALSE` by default.
`export.format`	A `character` string specifying the format selected to save the pollen calendar plot. The implemented formats that may be used are: `"pdf"` and `"png"`. The `export.format` will be `"pdf"` by default.
`legendname`	A `character` string specifying the title of the legend. By default is `"Pollen / m3"`.
`...`	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...`

This function allows to calculate and generate the pollen calendar using three different methods which are described below. The pollen calendar will be calculated and generated only for the period specified by the user using the y.start and y.end arguments, and for the specified number of the most abundant pollen types using the n.types argument by the user. The most abundant pollen types will be selected according to the highest average annual amounts of pollen registered by the pollen types during the considered period.

"heatplot" method. This pollen calendar is constructed based on the daily or weekly average of pollen concentrations, depending of the preferences of the user that may select "daily" or "weekly" as period argument. Then, these averages may be classified in different categories following different methods selected by the user according to the method.classes argument. If method.classes = "exponential" the user will apply the classification based on exponential classes proposed by Stix and Ferreti (1974), which has been commonly used in aerobiology for the generation of pollen calendars. The classification based on exponential method considers 11 classes (1_2, 3_5, 6_11, 12_24, 25_49, 50_99, 100_199, 200_399, 400_799, 800_1600, >1600). An example of this pollen calendar may be consulted in Rojo et al. (2016). This method to design pollen calendars is an adaptation from the pollen calendar proposed by Spieksma (1991) who considered 10_day periods instead of daily or weekly periods. Otherwise, if method.classes = "custom" the user may customize the classification according to the number of classes selected (n.classes argument) and the thresholds of the pollen concentrations used to define the classes (classes argument). Average values below the level of the th.pollen argument will be removed from the pollen calendar.
"phenological" method. This pollen calendar is based on phenological definition of the pollen season and adapted from the methodology proposed by Werchan et al. (2018). After to obtain daily average pollen concentrations for the most abundant pollen types different pollination periods were calculated using the daily averages. The main pollination period was calculated based on the percentage defined by perc1 argument (selected by the user, 80% by default) of the annual total pollen. For example, if perc1 = 80 the beginning of the high season was marked when 10% of the annual value was reached and the end was selected when 90% was reached. In the case of the early/late pollination a total of the percentage defined by perc2 argument (selected by the user, 99% by default) of the annual total pollen will be registered during this period. For this kind of pollen calendar the th.pollen argument will define the "possible occurrence" period as adapted by Werchan et al. (2018), considering the entire period between the first and the last day when this pollen level is reached. In an alternative way the average may be carried out after to define the pollen seasons using method_average = "avg_after" (instead of "avg_before" by default). "avg_after" determines the pollen season for all years and all pollen types, and then an average for circular data is calculated from the start_dates and end_dates.
"violinplot" method. This pollen calendar is based on the pollen intensity and adapted from the pollen calendar published by ORourke (1990). In first time the daily averages of the pollen concentrations are calculated and then these averages are represented using the violin plot graph. The shape of the violin plot display the pollen intensity of the pollen types in a relative way i.e. the values will be calculated as relative measurements regarding to the most abundant pollen type in annual amounts. Therefore, this pollen calendar shows a relative comparison between the pollen intensity of the pollen types but without scales and units. Average values below the level of the th.pollen argument will be removed from the pollen calendar.

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 generate the pollen calendar. For more information to see the interpollen function.

This function returns different results:
plot in the active graphics window displaying the pollen calendar generated by the user when result = "plot". This plot may be included in an object by assignment operators.
data.frame including the daily or weekly average pollen concentrations (according to the selection of the user) used to generate the pollen calendar. This data.frame will be returned when result = "table".
If export.plot = TRUE this plot displaying the pollen calendar will also be exported as file within the Plot_AeRobiology" directory created in the working directory.
If export.plot = TRUE and export.format = pdf a pdf file of the pollen calendar will be saved within the plot_AeRobiology directory created in the working directory. 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 pollen calendar will be saved within the plot_AeRobiology directory created in the working directory. Additional characteristics may be incorporated to the exportation as png file (see grDevices package).

ORourke, M.K., 1990. Comparative pollen calendars from Tucson, Arizona: Durhamvs. Burkard samplers. Aerobiologia, 6(2), p.136_140.

Rojo, J., Rapp, A., Lara, B., Sabariego, S., Fernandez_Gonzalez, F. and Perez_Badia, R., 2016. Characterisation of the airborne pollen spectrum in Guadalajara (central Spain) and estimation of the potential allergy risk. Environmental Monitoring and Assessment, 188(3), p.130.

Spieksma, F.T.M., 1991. Regional European pollen calendars. Allergenic pollen and pollinosis in Europe, pp.49_65.

Stix, E. and Ferretti, M.L., 1974. Pollen calendars of three locations in Western Germany. Atlas European des Pollens Allergisants, pp.85_94.

Werchan, M., Werchan, B. and Bergmann, K.C., 2018. German pollen calendar 4.0_update based on 2011_2016 pollen data. Allergo Journal International, 27, pp.69_71.

interpollen, calculate_ps

1 2	data("munich_pollen") pollen_calendar(munich_pollen, method = "heatplot", interplation = FALSE)

Warning messages:
1: In pollen_calendar(munich_pollen, method = "heatplot", interplation = FALSE) :
  WARNING: the number of columns is smaller than 'n.types' argument. 'n.types' adjusted to 8
2: In interpollen(data, method = int.method, plot = F) :
  WARNING: Gaps with more than 30 missing data have not been interpolated