nyctaxi: Accessing New York City Taxi Data

#' NYC Taxi trip data from NYC's Taxi and Limousine Commission (TLC)
#' @author Wencong (Priscilla) Li
#' @description There are three data tables containing information about NYC Taxi trips attached to this package. 
#' 
#' @details NYC's Taxi and Limousine Commission (TLC) Trip Data is a collection of trip records 
#' including fields capturing pick-up and drop-off locations, times, trip distances, fares, rate types, 
#' and driver-reported passenger counts. The data was collected and provided to the NYC TLC by 
#' technology providers under the Taxicab & Livery Passenger Enhancement Programs. 
#' The fist two tables are random samples of 100 observations generated by the \code{\link{sample}} function 
#' from the 2016 January green and yellow taxi trip data.
#' 
#' @docType data
#' @format \code{yellow_2016_01_sample} datatable (\code{\link[dplyr]{tbl_df}}) has 10,000 rows and 19 variables.
#' \code{green_2016_01_sample} datatable (\code{\link[dplyr]{tbl_df}}) has 10,000 rows and 21 variables. 
#' The following variables are in \code{yellow_2016_01_sample} or \code{green_2016_01_sample}.
#' \describe{
#'   \item{vendorid}{A code indicating the LPEP provider that provided the record.1= Creative Mobile Technologies, LLC; 2= VeriFone Inc.}
#'   \item{tpep_pickup_datetime}{The date and time when the meter was engaged.}
#'   \item{tpep_dropoff_datetime}{The date and time when the meter was disengaged.}
#'   \item{passenger_count}{The number of passengers in the vehicle. This is a driver-entered value.}
#'   \item{trip_distance}{The elapsed trip distance in miles reported by the taximeter.}
#'   \item{pickup_longitude}{Longitude where the meter was engaged.}
#'   \item{pickup_latitude}{Latitude where the meter was engaged.}
#'   \item{ratecodeid}{The final rate code in effect at the end of the trip. 1= Standard rate, 2=JFK, 3=Newark, 4=Nassau or Westchester, 5=Negotiated fare, 6=Group ride}
#'   \item{store_and_fwd_flag}{This flag indicates whether the trip record was held in vehicle memory before sending to the vendor, aka "store and forward," because the vehicle did not have a connection to the server. Y= store and forward trip, N= not a store and forward trip}
#'   \item{dropoff_longtitude}{Longitude where the meter was timed off.}
#'   \item{dropoff_latitude}{Latitude where the meter was timed off.}
#'   \item{payment_type}{A numeric code signifying how the passenger paid for the trip. 1= Credit card, 2= Cash, 3= No charge, 4= Dispute, 5= Unknown, 6= Voided trip}
#'   \item{fare_amount}{The time-and-distance fare calculated by the meter.}
#'   \item{extra}{Miscellaneous extras and surcharges. Currently, this only includes the $0.50 and $1 rush hour and overnight charges.}
#'   \item{mta_tax}{$0.50 MTA tax that is automatically triggered based on the metered rate in use.}
#'   \item{tip_amount}{Tip amount - This field is automatically populated for credit card tips. Cash tips are not included.}
#'   \item{tolls_amount}{Total amount of all tolls paid in trip.}
#'   \item{improvement_surcharge}{$0.30 improvement surcharge assessed on hailed trips at the flag drop. The improvement surcharge began being levied in 2015.}
#'   \item{total_amount}{The total amount charged to passengers. Does not include cash tips.}
#'   \item{ehail_fee}{The description of this variable is not available on TLC website.}
#'   \item{trip_type}{A code indicating whether the trip was a street-hail or a dispatch that is automatically assigned based on the metered rate in use but can be altered by the driver. 1= Street-hail, 2= Dispatch}
#' }
#' 
#' @source These data are recorded at \url{http://www.nyc.gov/html/tlc/html/about/trip_record_data.shtml} 
#' @references The description of the data is available on \url{http://www.nyc.gov/html/tlc/html/about/trip_record_data.shtml} 
"green_2016_01_sample"

#' @rdname green_2016_01_sample
#' @examples 
#' \dontrun{
#' #' # 
#' if (require(dplyr) & require(ggplot2)) {
#'  green_2016_01_sample %>%
#'  filter(Trip_distance <= 1) %>%
#'    ggplot(aes(x = Dropoff_longtitude, y = Pickup_latitude))
#' }
#' }
#' 
"yellow_2016_01_sample"




#' TLC taxi zone location IDs and corresponding boroughs and zone
#' @description #' The third table `taxi-zone-lookup` shows the taxi `Zone` and `Borough` 
#' for each `locationID`. For trip record data including TLC taxi zone location IDs, 
#' location names and corresponding boroughs for each ID can be found in this data table.
#'
#' @format TLC taxi zone information.
#' \describe{
#'   \item{LocationID}{TLC taxi zone LocationID.}
#'   \item{Borough}{Borough corresponding to a TLC taxi zone LocationID.}
#'   \item{Zone}{Zone corresponding to a TLC taxi zone LocationID.}
#' }
#' @source The data is available at \url{http://www.nyc.gov/html/tlc/html/about/trip_record_data.shtml}  
"taxi_zone_lookup"


#' NYC Taxi Zone spatial data
#' @format Spatial shapefiles of NYC Taxi Zones.
#' 
#' \describe{
#'   \item{OBJECTID}{Object ID}
#'   \item{Shape_Leng}{The length of the shape corresponding to a TLC taxi zone LocationID.}
#'   \item{Shape_Area}{The area of the shape corresponding to a TLC taxi zone LocationID.}
#'   \item{zone}{Zone corresponding to a TLC taxi zone LocationID.}
#'   \item{LocationID}{TLC taxi zone LocationID.}
#'   \item{borough}{Borough corresponding to a TLC taxi zone LocationID.}
#' }
#' @source https://s3.amazonaws.com/nyc-tlc/misc/taxi_zones.zip
"taxi_zones"