updated comments

R/add_ghost_trips.R

@@ -1,34 +1,52 @@
 #' Addition of ghost trips
 #'
-#' Add trips that do not get assigned any physical activity component, used as proxy for vehicle distances
+#' Add trips that do not get assigned any physical activity component, 
+#' often used as proxy for vehicle distances.
 #' 
 #' This function creates trips based on distance relative to another (reference) mode, 
 #' without altering the synthetic population. I.e. it adds trips that do not get assigned any physical 
-#' activity component. 
-#' 
-#' This function can be used to add e.g. car_driver and bus_driver trips which are used as proxy for
-#' vehicle distances needed for the injury and the CO2 pathways. It can also used to add truck
-#' and commercial motorcycle trips that are not included in any travel surveys.
-#' 
+#' activity component. This function can be used to add e.g. car_driver and bus_driver trips 
+#' which are used as proxy for vehicle distances needed for the injury and the CO2 pathways. 
+#' It can also used to add truck and commercial motorcycle trips that are not included in any travel surveys.
 #' As needed for the injury pathway, these newly added trips are assigned as trips made by a males or 
 #' females based on the proportion of males given as input parameter. The age ranges of males and females
 #' taking those newly added trips can also be defined. 
+#' 
 #' The new mode distance is equally split by the number of people times the number of trips per people to 
 #' be added. This is used as the distance for new male trips. As the proportion of female trips tends to be
-#' very low, the distance calculated for male trips is split by 10 and proportionally 10 times as many female trips are added,
-#' E.g. if the number of people to be added is 100 with 1 trip per person and only 98% of those trips are made by males,
-#' then 98 male trips and 10 * 2 = 20 female trips with a 10th of the distance of male trips are added 
-#' This is to ensure a better representation of the demographics of female trips whilst keeping the number
-#' of newly added trips as small as possible to reduce the run time of the script. 
+#' very low, the distance calculated for male trips is split by 10 and using a 10th of the distance
+#' for male trips, 10 times as many female trips are added compared with the very low number of female
+#' trips that would have been added had the same distance been used as for male trips. 
+#' E.g. if the number of people to be added is 100 with 1 trip per person and 98% of 
+#' those trips are made by males, then we add 98 male trips but 10 * 2 = 20 female trips 
+#' with a 10th of the distance of male trips. This is to ensure a better representation of 
+#' the demographics of female trips whilst keeping the number of newly added trips as 
+#' small as possible to reduce the run time of the model.
 #' 
-#' @param raw_trip_set data frame of trips.
-#' @param trip_mode which mode to add.
-#' @param distance_ratio fraction of reference distance to create.
-#' @param reference_mode name of reference mode.
-#' @param prop_male proportion of newly added mode that are assigned to a male.
-#' @param agerange_male age range of males associated with newly added mode.
-#' @param agerange_female age range of female drivers associated with newly added mode.
-#' @param scenario name of scenario for which mode is to be added.
+#' The function performs the following steps:
+#' 
+#' - set up the number of people (with regards to males) and trips per per person to be added
+#' - find the total distance of the reference mode
+#' - find the age ranges for male and female trips
+#' - find the number of male and female participants
+#' - calculate the total distance of the new mode to be added based on the reference distance and
+#'   find the speed of the new mode
+#' - for male trips:
+#'   - define the distance range for each male trip to be added, assume that each trip is of equal length
+#'   - add new male trips sampling from the given age range (add_trips.R)
+#'   - add age and distance categories plus scenario name
+#' - repeat for female trips (assuming female trips are a 10th of the distance
+#'   of male trips and adding proportionally 10 times as many female trips)
+#'   
+#' 
+#' @param raw_trip_set data frame of trips
+#' @param trip_mode which mode to add
+#' @param distance_ratio fraction of reference distance to use to calculate new mode distance
+#' @param reference_mode name of reference mode
+#' @param prop_male proportion of newly added mode that are assigned to males
+#' @param agerange_male age range of males associated with newly added mode
+#' @param agerange_female age range of female drivers associated with newly added mode
+#' @param scenario name of scenario for which mode is to be added
 #' 
 #' @return data frame of trips
 #' 
@@ -47,6 +65,7 @@ add_ghost_trips <- function(raw_trip_set,
   ## values for new ghost journeys
   nPeople <- 100   # number of people to be added
   nTrips <- 1 # number of trips per person
+
   # find the sum of distances for all trips made by the reference mode -> reference distance
   total_ref_distance <- sum(raw_trip_set[raw_trip_set$stage_mode==reference_mode,]$stage_distance,na.rm=T)