ctrl is a list

R/flight_simulation.R

@@ -1,58 +1,72 @@
-
-#' Implementation of the methods 1 and 2 base on Pennycuick. Both use Breguet's
-#' equations for lift drag ratio calculation.
+#' @title Range Estimation
+#' @description  Practical range estimation of birds using methods in Pennycuik (1975)
+#' Mechanics of Flight. These methods are based on Breguet equations.
+#'
 #' @author Brian Masinde
 #'
 #' @name flysim
 #'
-#' @param data A data frame or a list (for a single bird observation). See example
-#' @param ctrl A list of re-definition of constants (*airDensity*,
-#'             *consume*, *enegry e*, *mechanical efficiency n*).
+#' @param data A data frame.
+#' @param ctrl A list for re-defining constants. See details.
 #'
-#' @include misc_functions.R lookup_table2.R method_1.R method_2.R
+#' @details The option *ctrl takes the folowing arguments
+#' \itemize{
+#'    \item ppcons: Profile power constant
+#'    \item energy: Energy content of fuel from fat
+#'    \item g: Accelaration due to gravity
+#'    \item n: Mechanical conversion efficiency [0,1]
+#'    \item k: Induced power factor
+#'    \item R: Ventilation and circulation power
+#'    \item airDensity: Air density at cruising altitude
+#'    \item bdc: Body drag coefficient
+#'    \item alpha: Basal metabolism factors in passerines and non passerines
+#'    \item delta: Basal metabolism factors in passerines and non passerines
+#'    alpha*bodyMass^delta
+#'    \item consume: Percentage of fuel to be used from fat mass
+#'}
+#' @include misc_functions.R lookup_table2.R input_match.R method_1.R method_2.R
 #' @return S3 class object with range estimates based on methods defined and
 #'        constants
+#' \itemize{
+#'    \item data as a data frame
+#'    \item range estimates
+#'    \item fuel
+#'    \item constants (list)
+#' }
+#'
 #' @importFrom dplyr filter
 #'
 #' @export flysim
 #'
 #' @examples
 #' flysim(data = birds, ctrl = list(energy = 3.89*10^7))
 #' flysim(data = birds,  ctrl = list(airDensity = 0.905))
+#'
+#' @usage flysim(data, ctrl = list())
 
 
-flysim <- function(data, ctrl) {
+flysim <- function(data, ctrl = list()) {
   # ... extra arguments to be passed to methods
 
   ##  Error check data #########################################################
   if (is.data.frame(data) == FALSE & is.list(data) == FALSE) {
-    stop("data input allows for dataframe or list")
+    stop(">> data as list or data frame <<")
   }
 
   # check number of columns
   if (is.data.frame(data) == TRUE && ncol(data) < 6) {
-    stop("data should have at least 5 columns")
+    stop(">> at least 5 columns for data <<")
   }
   # check number of fields
   if (is.list(data) == TRUE && length(data) < 6) {
     stop("data list should have at least 4 fields")
   }
 
-  if (is.data.frame(data) == TRUE &&
-      sum(levels(data[, 5]) == levels(factor(c(1, 2)))) != 2) {
-    stop("Order column should be a factor with levels 1 or 2")
-  }
-
-  # # check method
-  # if (missing(method) == TRUE) {
-  #   message("## Default method = 'breguet' \n \n")
-  #   method <- "breguet"
-  # } else if (method != "breguet" & method != "breguet_adj") {
-  #   stop("method = 'breguet' or 'breguet_adj' ")
-  # }
+  # column match
+  cols <- .colnames.match(names(data))
 
   results <- list("data" = data,
-                  "range" = data.frame(),
+                  "range" = vector(),
                   "fuel" = vector(),
                   #"Vmp" = vector(),
                   #"Vmr" = vector(),
@@ -63,30 +77,31 @@ flysim <- function(data, ctrl) {
 
   if (is.data.frame(data)  == TRUE) {
     smallPasserines <-
-      dplyr::filter(data, data[, 5] == 1 & data[, 2] <= 0.05)
+      dplyr::filter(data, cols$order == 1 & cols$bodyMass <= 0.05)
 
-    id_sp <- which(data[, 5] == 1 & data[, 2] <= 0.05)
+    id_sp <- which(cols$order == 1 & cols$bodyMass <= 0.05)
 
     nonSmallPasserines <-
-      dplyr::filter(data, data[, 5] == 2 | data[, 2] >= 0.05)
+      dplyr::filter(data, cols$order == 2 | cols$bodyMass >= 0.05)
 
-    id_np <- which(data[, 5] == 2 | data[, 2] >= 0.05)
+    id_np <- which(cols$order == 2 | cols$bodyMass >= 0.05)
     # args small passerines
-    argsSmallBird <- list("bodyMass" = smallPasserines[, 2],
-                   "wingSpan" = smallPasserines[, 3],
-                   "fatMass" = smallPasserines[, 4],
-                   "ordo" = smallPasserines[, 5],
-                   "wingArea" = smallPasserines[, 6],
-                   "name" = as.vector(smallPasserines[ ,1])
-    )
+    argsSmallBird <- list("bodyMass" = smallPasserines[, cols$bodyMass],
+                   "wingSpan" = smallPasserines[, cols$wingSpan],
+                   "fatMass" = smallPasserines[, cols$fatMass],
+                   "ordo" = smallPasserines[, cols$order],
+                   "wingArea" = smallPasserines[, cols$wingArea]
+                   #"name" = as.vector(smallPasserines[ ,1]
+                   )
 
     # args big birds
-    argsBigBird <- list("bodyMass" = nonSmallPasserines[, 2],
-                   "wingSpan" = nonSmallPasserines[, 3],
-                   "fatMass" = nonSmallPasserines[, 4],
-                   "ordo" = nonSmallPasserines[, 5],
-                   "wingArea" = nonSmallPasserines[, 6],
-                   "name" = as.vector(nonSmallPasserines[ ,1]))
+    argsBigBird <- list("bodyMass" = nonSmallPasserines[, cols$bodyMass],
+                   "wingSpan" = nonSmallPasserines[, cols$wingSpan],
+                   "fatMass" = nonSmallPasserines[, cols$fatMass],
+                   "ordo" = nonSmallPasserines[, cols$order],
+                   "wingArea" = nonSmallPasserines[, cols$wingArea]
+                   #"name" = as.vector(nonSmallPasserines[ ,1])
+                   )
 
     if (nrow(smallPasserines) > 0 & nrow(nonSmallPasserines) > 0) {
 
@@ -105,12 +120,12 @@ flysim <- function(data, ctrl) {
         results$constants <- bigBirds[[3]]
       }
       # consitent order of results and input data
-      rownames(smallBirds[[1]]) <- id_sp
+      names(smallBirds[[1]]) <- id_sp
       results$fuel[id_sp] <- smallBirds[[2]]
-      rownames(bigBirds[[1]]) <- id_np
+      names(bigBirds[[1]]) <- id_np
       results$fuel[id_np] <- bigBirds[[2]]
-      range <- rbind(smallBirds[[1]],bigBirds[[1]])
-      results$range <- range[order(as.numeric(row.names(range))), ]
+      range <- c(smallBirds[[1]],bigBirds[[1]])
+      results$range <- range[order(as.numeric(names(range)))]
     }else if(nrow(smallPasserines) == 0) {
 
       if(missing(ctrl) == TRUE){
@@ -141,12 +156,12 @@ flysim <- function(data, ctrl) {
     }
 
   } else {
-    args <- list("bodyMass" = data[[2]],
-                 "wingSpan" = data[[3]],
-                 "fatMass" = data[[4]],
-                 "ordo" = data[[5]],
-                 "wingArea" = data[[6]],
-                 "name" =  data[[1]])
+    args <- list("bodyMass" = data[[cols$bodyMass]],
+                 "wingSpan" = data[[cols$wingSpan]],
+                 "fatMass" = data[[cols$fatMass]],
+                 "ordo" = data[[cols$order]],
+                 "wingArea" = data[[cols$wingArea]]
+                 )
 
     if (args$ordo == 1) {
       if (missing(ctrl) == TRUE) {
@@ -173,12 +188,8 @@ flysim <- function(data, ctrl) {
     results$constant <- bigBirds[[3]]
   }
 
-
-  #results$constants <- constants
-
   # return object of class flysim
   class(results) <- append(class(results), "flysim")
-
   # return class object
   return(results)
 }