In TomVuod/overwintering: Materials supporting publication

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(overwintering)

Introduction

This vignettes replicates the data workflow used to generate the results shown in the following publication:

Włodarczyk T. 2021. Functional spatial distribution and sociometric characteristics of Formica fusca ants during winter dormancy. Ecological Entomology 46, 419–427.

I also provide the additional data, which have not previously been published in any form and regarding spatial distribution of ants.

Colony spatial distribution during the winter dormacy

The spatial_distribution dataset contains the raw data collected in the field. As the ants were excavated the position of ant cluster was determined in two ways: measuring the depth range occupied by an ant cluster, and measuring the distance from the cluster center to the three reference points arranged around the nest site. The cluster center was projected upwards to the ground level so that the points were assumed to lie on the same plane. To account for the dimensions of the cluster on the horizontal plane, the radius from the cluster center was also measures (taking rather the upper estimate of it). Thus, the whole cluster was represented as a vertically positioned cylinder.

data("spatial_distribution")
head(spatial_distribution)

As we can see from the head of the dataset it also contains the date indicating when a given cluster was found. The whole excavation took usually several days.

res <- split(spatial_distribution, spatial_distribution$Colony) |>
  lapply(function(x) cat(sprintf("Excavation period for the colony %s: %d days\n", x$Colony[1], as.integer(max(x$Date)-min(x$Date)+1))))

To transform the distances of projected cluster positions to their coordinates on the horizontal plane we need the coordinates of the reference points. They can be easily calculated having the mutual distances among them. The problem reduces to finding triangle vertices given the side lengths.

# load the data on the distances among reference points for each colony
data("reference_points")

# calculate the reference points coordinates
reference_points_coords <- distances_to_coordinates(reference_points)

Now we can add to the spatial_distribution dataset the columns with the cluster center coordinates on the horizontal plane. Note that this is available for the samples in which distances to the reference points have been determined. This was not the case for some of the colonies and samples with low number of ants or ants whose intact position could not be determined. Since the measurements inevitably entail the error component, the exact solution from geometric calculation are usually not available. This is why the solution is obtained through the optimization function, which looks for the position of the cluster center such that the distances to the reference points are close to the reported ones.

spatial_distribution <- add_point_coordinates(spatial_distribution, reference_points_coords)

Vertical distribution plot

To construct the plot showing the vertical distribution of plot we should first prepare a correct data representation. We will divide each cluster into segments, each of which will cover the depth of one centimeter. Ants are assumed to be evenly distributed across these segments and lastly, segments representing the same depth are summed up across the clusters.

vertical_distribution_plot <- determine_vertical_distribution(spatial_distribution)

# load dataset with colony metadata
data("colony_metadata")

# render the main part of the Fig 3 from the publication
vertical_distribution_plot(vertical_distribution_plot, colony_metadata)

We can plot separately the legend to the Figure 3.

plot_legend_fig_3()

Forager removal experiment

The dataset time_series_results presents the outcome of the experiment in which part of workers were marked with the color used being dependent on whether ant occipied the upper or lower part of the excavated nest. In the laboratory ants penetrating the area outside the aritifical nests were collected on a daily basis producing the time series data. The dataset presents the cumulative results as the experiment was going on. The paint colors used to differentiate between both categories of ants were swept across colonies.

data("time_series_results")
head(time_series_results)

We can check the final experiment output for each colony.

for(colony in unique(time_series_results$colony)){
  max_ind <- which.max(time_series_results[time_series_results$colony==colony,"Date"])
  print(time_series_results[time_series_results$colony==colony,][max_ind,,drop=FALSE])
}

To perform statistical calculations we need some quantitative data related to the ant marking. They are included in the colony_stats dataset.

data("colony_stats")
colony_stats

With these numbers we can calculate the probability for each possible proportion of ants from upper (or lower) part of the nest among all the ants which have been removed. Let's make the calculations for colony 18-59 with the use of data from the whole experiment.

library(dplyr)
library(ggplot2)
ant_numbers <- time_series_results %>% 
  filter(colony=="18-59") %>% 
  filter(Date==max(Date)) 

# We need also the information about numbers and proportion of marked ants in the colony.
data(colony_stats)
colony_params <- colony_stats[colony_stats$colony == "18-59",]
prob_mass <- do.call(get_prob_mass, c(ant_numbers, colony_params[,c("N1", "N2", "marked_1", "marked_2")]))
ggplot(prob_mass, aes(x = upper_part_proportion, y = prob))+
  geom_bar(stat = "identity")+
  ggtitle("Probability distribution")+
  xlab("Proportion of ants from the upper nest segment")+
  ylab("Probability")

Based on these results we can determine the credible interval and point estimate for the proportion of ants from the upper nest segment.

calculate_CI(prob_mass, alpha=0.05)

Figure 4

We can also calculate the confidence interval for the null hypothesis which assumes that each ant, regardless its location in the nest, has the same probability of becoming a forager. Thus, the proportion of the foragers which come from the upper nest segment can be modeled using hypergeometric distribution, taking as parameters the total number of foragers, and the numbers of ants occupying the upper and lower segment of the nest. The evidenced and inferred attribution of the foragers to the nest segment can be compared to the whole colony data, as shown on Figure 4 in the publication.

# retrieve the time series results on the last day of experiment
results_on_completion <- time_series_results %>%
  group_by(colony) %>%
  filter(Date == max(Date)) %>%
  ungroup()

# add colony-level data on the number of marked ants and the sizes of the spatial groups
colony_stats <- merge(colony_stats, results_on_completion)

# calculate credible and confidence intervals 
CI <- purrr::pmap(colony_stats, get_prob_mass) %>%
  lapply(function(x) calculate_CI(x, alpha = 0.05)) %>% 
  {function(x) do.call(rbind,x)}()
colnames(CI) <- c("CI_min", "max_prob", "CI_max")
CI_null <- purrr::pmap(colony_stats, get_prob_mass, null_model = TRUE) %>%
  lapply(function(x) calculate_CI(x, alpha = 0.05)) %>% 
  {function(x) do.call(rbind,x)}()
colnames(CI_null) <- c("CI_min_null", "max_prob_null", "CI_max_null")
colony_stats <- cbind(colony_stats, CI, CI_null)

figure_4(colony_stats)

Figure 5

The function generating Figure 5 repeates the above procedure over the whole dataset.

figure_5()

Figure 6

To see whether the proportion of ants from the upper segment of nest changes over time, we can fit a linear model with the time elapsed from the experiment start as an explanatory variable. We can be sure about the occupied nest segment only in the case of marked workers. For all the workers, including unmarked ones, we have to rely on the posterior distribution which is returned by the get_prob_mass function. To have the reliable estimate of the temporal trend the probability distribution should be sampled many times, producing the data for multiple linear regressions. The null model is generated by shuffling proportion of ants across time points. See publication for more details.