edits on vignettes

vignettes/package_usage.Rmd

@@ -22,9 +22,9 @@ knitr::opts_chunk$set(
 
 ## Introduction
 
-This document demonstrate the usage of package functions in analysis. Since most of the functions are parts of a workflow, it's better to explain them together than giving separate code examples in function help.
+This document demonstrates the usage of package functions in the analysis of animal tracking data. As a complete analysis consists of a series of sequential steps, it is more informative to show how the package's functions fit into this workflow than giving separate code examples in function help files.
 
-First we load the libraries and prepare the data. Note a sample was generated so that the model fitting process can finish in seconds instead of minutes.
+First we load the libraries and prepare the data. Note that a subsample was taken so that the model fitting process can finish in seconds instead of minutes.
 
 ```{r libraries and data, eval=TRUE}
 library(ctmm)
@@ -36,89 +36,92 @@ data_sample <- sample_tele_list(buffalo, 100)
 
 ### Basic data structure
 
-To plot multiple animals location with `ggplot2`, we need to merge all location data into a single `data.frame`. `merge_tele` will merge `ctmm` `telemetry` object/list into a list of location `data.table` and information `data.table`. `data.table` is compatible with `data.frame` but has much better performance.
+To plot the locations of multiple animals simultaneously with `ggplot2`, we need to merge all location data into a single `data.frame`. `merge_tele` will merge `ctmm` `telemetry` objects/lists into a list of two `data.table`s: `data` for animal location, `info` for some summaries of the data. 
+
+`data.table` has much better performance than `data.frame` though uses a different syntax. You can still use `data.frame` syntax on `data.table` if you are not familiar with it.
 
 ```{r basic data structure}
 # basic data structure
 merged_data <- merge_tele(buffalo)
 # a list of locations data.table/data.frame and information table
-dt <- merged_data$data
+loc_data <- merged_data$data
 info <- merged_data$info
 ```
 
-In `dt`: 
+In `loc_data`: 
 
 - `identity` are animal names
 - `id` are animal names as a factor. We will need this when we want to maintain the level information.
 
-```{r dt}
-knitr::kable(head(dt))
+```{r loc_data}
+knitr::kable(head(loc_data))
 ```
 
-You can calculate distance and speed outliers on `dt`.
+You can calculate distance and speed outliers in the data via:
 
 ```{r outlier}
 # distance_center column is added
-dt_distance <- calculate_distance(dt)
-knitr::kable(head(dt_distance))
+loc_data_distance <- calculate_distance(loc_data)
+knitr::kable(head(loc_data_distance))
 # always calculate distance first then calculate speed outlier with distance columns added
-knitr::kable(head(calculate_speed(dt_distance)))
+loc_data_speed <- calculate_speed(loc_data_distance)
+knitr::kable(head(loc_data_speed))
 ```
 
+`info` summarize some basic information on data.
 
 ```{r info}
 knitr::kable(info)
 ```
 
+## Selecting a subset
 
-In app we can select a subset of full data by slecting rows in the data summary table 1.
-
-![](pic/01_summary_table.png){ width=75% }
-
+In the app we can select a subset of the full data by slecting rows in the data summary table.
 
-To select a subset in script, we can select animal names for `identity` column or numbers for `id` factor column in `dt` with `data.table` syntax. `data.table` is also `data.frame` so you can use `data.frame` synatax too.
+To perform the same selection via package functions, we can select animal names from the `identity` column or numbers from the `id` factor column in `loc_data` using either `data.table` or `data.frame` syntax.
 
-It's suggested to always select a subset from full data like this, because the subset will carry the `id` column which still hold all animal names in levels, then a consistent color mapping can be maintained(otherwise `ggplot2` will always draw first animal in same color).
+We suggest to always select a subset from full data instead of creating separate data objects for individuals, because the subset will carry the `id` column which still holds all animal names as levels so that a consistent color mapping can be maintained (otherwise `ggplot2` will always draw the first animal in same color).
 
 ```{r select subset}
 # select by identity column
-dt_sub1 <- dt[identity %in% c("Gabs", "Queen")]
+loc_data_sub1 <- loc_data[identity %in% c("Gabs", "Queen")]
 # select by id factor column value
-dt[as.numeric(id) %in% c(1, 3)]
+loc_data[as.numeric(id) %in% c(1, 3)]
 ```
 
 ## Visualization
 
-You can reproduce most of the plots in `Visualization` page with functions. 
+You can reproduce most of the plots in the `Visualization` page of the webapp with package functions, for example: 
 
 ```{r plot location and time, eval=TRUE}
 # plot animal locations
-plot_loc(dt)
-# plot a subset only. Note the color mapping is consistent because dt_sub1 id column hold all animal names in levels.
-plot_loc(dt_sub1)
+plot_loc(loc_data)
+# plot a subset only. Note the color mapping is consistent because loc_data_sub1 id column hold all animal names in levels.
+plot_loc(loc_data_sub1)
 # with subset and full data set both provided, subset will be drawn with full data as background. 
-plot_loc(dt_sub1, dt)
+plot_loc(loc_data_sub1, loc_data)
 # location in facet
-plot_loc_facet(dt_sub1)
+plot_loc_facet(loc_data_sub1)
 # sampling time
-plot_time(dt_sub1)
+plot_time(loc_data_sub1)
 # take the ggplot2 object to further customize it
-plot_loc(dt_sub1, dt) +
+plot_loc(loc_data_sub1, loc_data) +
   ggplot2::ggtitle("Locations of Buffalos") +
   # override the default left alignment of title and make it bigger
   ctmmweb:::CENTER_TITLE
 # export plot
-g <- plot_loc(dt_sub1, dt)
+g <- plot_loc(loc_data_sub1, loc_data)
 ggplot2::ggsave("pic/test.png", g)
 ```
 
 
 
 ## Variogram
 
-We can plot variograms in various modes. 
+We can plot both empirical variograms alone and empirical variograms with fitted theoretical semi-variance functions superimposed on them. 
+
+For example, to plot empirical variograms from telemetry data, one would do:
 
-Empirical variograms based on telemetry data
 ```{r variogram 1, fig.height=8}
 vario_list <- lapply(data_sample, ctmm::variogram)
 # names of vario_list are needed for figure titles
@@ -129,7 +132,7 @@ plot_vario(vario_list)
 # plot_vario(vario_list, cex = 0.55)
 ```
 
-Variogram of guesstimated models from `ctmm::ctmm.guess` on telemetry data.
+Similarly, we can compare initial movement model parameter guesses to the data via variograms:
 
 ```{r variogram 2, fig.height=8}
 guess_list <- lapply(data_sample,
@@ -140,23 +143,23 @@ plot_vario(vario_list, guess_list)
 
 ## Model summary table
 
-Fit models on data in parallel.
+We can fit models with multiple animals in parallel. 
 
 ```{r model summary, eval=TRUE}
-# fit models in parallel.
+# fit models in parallel. parallel mode can be turned off with par_fit_tele(data_sample, fallback = TRUE)
 model_fit_res <- par_fit_tele(data_sample)
 # a data.table of models information summary
-model_summary_dt <- summary_model_fit(model_fit_res)
+model_summary <- summary_model_fit(model_fit_res)
 # you can also open it with RStudio's data.frame viewer
-knitr::kable(model_summary_dt)
+knitr::kable(model_summary)
 ```
 
-There could be multiple models fitted for each animal if they are validate candidates. In the app you can select a subset of models then check their variograms, home ranges and occurrences. You will aslo need to select a subset of models in R script.
+There could be multiple models fitted for each animal. In the webapp you can select a subset of models then check their variograms, home ranges and occurrences. You can also select a subset of fitted models via in a script as:
 
-`model_fit_res` hold every model for same animal under a list item of animal name. 
+`model_fit_res` holds every model for each animal under a list item associated with each animal's name. 
 ![](pic/05_model_res_structure.png){ width=50% }
 
-We need to convert it into a flat list to make the selection easier.
+To make selecting a subset easier, we first convert this nested list structure to a flat list:
 
 ```{r flat model list}
 # the nested structure of model fit result
@@ -167,31 +170,31 @@ model_list <- list_model_fit(model_fit_res)
 names(model_list)
 ```
 
-Then we can find the model names in model summary table by `model_no` or `model_type`. The code here is in `data.table` syntax, but you can use the table as `data.frame` if you want.
+Then we can find the model names in the model summary table by `model_no` or `model_type`. The code here uses `data.table` syntax, but you can also use the table as `data.frame` if you want.
 
 ```{r select models in summary table}
 # select subset in model summary table by model_no
-knitr::kable(model_summary_dt[model_no %in% c(1, 3, 10, 11, 12, 13)])
+knitr::kable(model_summary[model_no %in% c(1, 3, 10, 11, 12, 13)])
 # select by model type
-knitr::kable(model_summary_dt[model_type == "OU anisotropic"])
+knitr::kable(model_summary[model_type == "OU anisotropic"])
 # select first(best) model for each animal using the smallest AICc value
-knitr::kable(model_summary_dt[dAICc == 0])
+knitr::kable(model_summary[dAICc == 0])
 # Because each model have 3 rows, the `estimte == "ML"` filter can make sure each model only be selected once. 
-knitr::kable(model_summary_dt[estimate == "ML"])
+knitr::kable(model_summary[estimate == "ML"])
 # Combine this condition with filter above to select models
 # The expression is enclosed with () to enable automatical printing of result. Both model_name and identity are selected in same filter. We need the model_name to filter the model list, and the animal name to filter the variograms
-(names_sub2 <- model_summary_dt[(estimate == "ML") &
+(names_sub2 <- model_summary[(estimate == "ML") &
   (model_no %in% c(1, 3, 10, 11, 12, 13)), .(model_name, identity)])
 ```
 
-Once you have selected the models in summary table, you can filter the actual models list with model names. Note this is a different subset from `dt_sub1` above.
+Once you have selected the models in summary table, you can filter the actual models list with model names. Note this is a different subset from `loc_data_sub1` above.
 
 ```{r filter model list}
 # filter model list by model names to get subset of model list.
 model_list_sub2 <- model_list[names_sub2$model_name]
 ```
 
-Now we can plot variograms with selected models. Note the `vario_list_sub2` need to match with `model_list_sub2` in length and animal, so they are based on same data.
+Now we can plot variograms with the fitted SVFs of the selected models. Note the `vario_list_sub2` needs to match with `model_list_sub2` in length and animal name, so they are based on same data.
 
 ```{r variogram 3, fig.height=8}
 # get corresponding variograms by animal names.
@@ -202,8 +205,10 @@ plot_vario(vario_list_sub2, model_list_sub2, model_color = "purple")
 
 ## Home range
 
+We can calculate home range UD objects with the telemetry data and the fitted models. Note parallel mode is not used because we want to calculate all animals together to put them in same grid.
+
 ```{r home range, fig.height=10}
-# calculate home range with ctmm::akde. Note we didn't use parallel here because we want to calculate all animals together to put them in same grid.
+# calculate home range with ctmm::akde. 
 tele_list_sub2 <- data_sample[names_sub2$identity]
 hrange_list_sub2 <- akde(tele_list_sub2, CTMM = model_list_sub2)
 # name by model name
@@ -220,33 +225,42 @@ plot_ud(hrange_list_sub2, level_vec = c(0.50, 0.95), tele_list = tele_list_sub2)
 
 ## Occurrence
 
+Occurrence can be calculated from the telemetry data and the fitted models in parallel.
+
 ```{r occurrence, fig.height=10}
-# calculate occurrence in parallel
+# calculate occurrence in parallel. parallel can be disabled with fallback = TRUE
 occur_list_sub2 <- par_occur(tele_list_sub2, model_list_sub2)
 # plot occurrence. Note tele_list is not needed here because the location overlay usually interfere with occurrence plot.
 plot_ud(occur_list_sub2, level_vec = c(0.50, 0.95))
 ```
 
-## Map
+## Maps
 
-We can build an interactive online map.
+We can then build interactive online maps of the data and fitted Home Range and Occurrence distributions. For example, one can display the location data on a map via:
 
 ```{r point map, eval=TRUE}
 # this is needed for using pipe operator
 library(leaflet)
-# selecte_dt1 is used for visualization plot. all the model selections above are based on a different subset. We need to get corresponding dt subset for model selections
-dt_sub2 <- dt[identity %in% names(tele_list_sub2)]
-point_map(dt_sub2)
-point_map(dt)
-# save map to html. It will be self contained single html and can be shared.
-htmlwidgets::saveWidget(point_map(dt_sub2), file = "point_map.html")
+# loc_data_sub1 is used for visualization plot. all the model selections above are based on a different subset. We need to get corresponding loc_data subset for model selections
+loc_data_sub2 <- loc_data[identity %in% names(tele_list_sub2)]
+point_map(loc_data_sub2)
+point_map(loc_data)
 ```
 
-Home range map need more parameters. See their help documents for detailed explanations.
+The map can be saved as a self contained html file.
+
+```{r save map}
+# save map to single html file. 
+htmlwidgets::saveWidget(point_map(loc_data_sub2), file = "point_map.html")
+```
+
+
+Displaying home range estimates requires more input. See their help documents for detailed explanations.
 
 ```{r home range map, eval=TRUE}
+# A map with home range estimates need: list of home range UD object, vector of level.UD in ctmm::plot.telemetry, a vector of color names for each home range estimate.
 range_map(hrange_list_sub2, 0.95, rainbow(length(hrange_list_sub2)))
-# note dt_sub2 is corresponding to hrange_list_sub2
-point_range_map(dt_sub2, hrange_list_sub2, 0.95,
+# To overlay home range estimates with animal locations, the corresponding animal location data is needed.
+point_range_map(loc_data_sub2, hrange_list_sub2, 0.95,
                 rainbow(length(hrange_list_sub2)))
 ```