nzcrash: New Zealand Motor Vehicle Crash Data

#' Motor vehicle crashes in New Zealand since the year 2000.
#'
#' @description
#' A dataset of 540888 crashes, recorded by the New Zealand Transport Agency 
#' (NZTA).
#' 
#' Other attributes in a many-to-one relationship with the crashes are
#' available in the datasets \code{\link{vehicles}},
#' \code{\link{causes}}, and \code{\link{objects_struck}}.

#' @seealso
#' A comprehensive data dictionary is provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/guide-to-coded-crash-reports/docs/guide-to-coded-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' Details about how crash reports are completed are provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/traffic-crash-reports/docs/traffic-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' @format A data frame with 540888 rows and 30 variables:
#' \describe{
#'   \item{region}{TLA (Territorial Local Authority) where the crash took place.  See \url{http://www.stats.govt.nz/methods/classifications-and-standards/classification-related-stats-standards/territorial-authority.aspx} for more information about TLAs.}
#'   \item{road}{Road name where the crash took place.}
#'   \item{distance_from_landmark}{Distance in metres from a landmark or an intersection as indicated by the columns "landmark" and "side_road".}
#'   \item{direction_from_landmark}{Compass direction, as above.}
#'   \item{landmark}{Whether a landmark or an intersection with a side road.}
#'   \item{side_road}{Landmark or intersection with a side_road, near to the site of the crash.}
#'   \item{id}{Unique number identifying the crash, by which other tables can be joined (\code{\link{vehicles}}, \code{\link{causes}}, and \code{\link{objects_struck}}).}
#'   \item{date}{Date of the crash.  More reliable than \code{datetime}, which is \code{NA} when \code{time} is \code{NA}.}
#'   \item{time}{Time of the crash to the nearest minute.  Not always available.}
#'   \item{direction}{Initial direction of the principal vehicle in the crash.}
#'   \item{street}{Road of the principal vehicle in the crash (first or second, i.e. main or side street).}
#'   \item{curvature}{Severity of the curvature of the road where the crash took place.}
#'   \item{wetness}{How wet the conditions were at the time of the crash.}
#'   \item{light_ambient}{Level of ambient light at the time of the crash.}
#'   \item{light_artificial}{Level of artificial light at the time of the crash.}
#'   \item{weather_1}{One type of weather at the time of the crash.}
#'   \item{weather_2}{Another type of weather at the time of the crash.}
#'   \item{junction_type}{Type of the junction at which the crash took place.}
#'   \item{traffic_control}{Traffic control at the site of the crash (e.g. stop sign).  Only one is given, but there is a hierarchy -- see the data dictionary linked to above.}
#'   \item{road_marking}{Road marking at the site of the crash (e.g.  pedestrian crossing).  Only one is given, but there is a hierarchy -- see the data dictionary linked to above.}
#'   \item{speed_limit}{Speed limit in force at the site of the crash.}
#'   \item{fatalities}{Number of people killed in the crash, or who died within 30 days of injuries suffered in the crash.}
#'   \item{severe_injuries}{Number of people severely injured.}
#'   \item{minor_injuries}{Number of people with minor injuries from the crash.}
#'   \item{pedestrian_age}{Age of the youngest pedestrian under 20, otherwise the oldest one.}
#'   \item{cyclist_age}{Age of the youngest cyclist under 20, otherwise the oldest one.}
#'   \item{datetime}{Date and time of the the crash.}
#'   \item{easting}{Easting of the crash site in EPSG:4326 projection (WGS 84, Gooogle Maps)}
#'   \item{northing}{Northing of the crash site in EPSG:4326 projection (WGS 84, Gooogle Maps)}
#'   \item{movement_category}{General movement happinging in the crash.}
#'   \item{movement_description}{Detail of the movement happinging in the crash.}
#'   \item{severity}{The severity of the worst injury in the crash.}
#' }
#' @source \url{http://www.nzta.govt.nz/resources/crash-analysis-system-data/}
"crashes"

#' Vehicles involved in crashes.
#'
#' @description
#' A dataset of 979930 vehicles, recorded by the New Zealand Transport Agency 
#' (NZTA) as being involved in crashes in the \code{\link{crashes}} dataset.
#' There is a many-to-one relationship between vehicles and crashes.  They can
#' be joined by the common column \code{id} (see the example below).
#' 
#' Other attributes in a many-to-one relationship with the crashes are
#' available in the datasets \code{\link{causes}}, and
#' \code{\link{objects_struck}}.

#' @seealso
#' A comprehensive data dictionary is provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/guide-to-coded-crash-reports/docs/guide-to-coded-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' Details about how crash reports are completed are provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/traffic-crash-reports/docs/traffic-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' @format A data frame with 979930 rows and three variables:
#' \describe{
#'   \item{id}{Unique number identifying the crash, by which the \code{link{crashes}} table can be joined.}
#'   \item{vehicle_id}{Unique identifier of the vehicle in each crash (unique in combination with \code{id}.}
#'   \item{vehicle}{Type of vehicle (car, truck, etc.).}
#' }
#' @source \url{http://www.nzta.govt.nz/resources/crash-analysis-system-data/}
"vehicles"

#' Causes of crashes.
#'
#' @description
#' A dataset of 888072 crash causes, recorded by the New Zealand Transport
#' Agency (NZTA) as being causes of crashes in the \code{\link{crashes}}
#' dataset.  There is a many-to-one relationship between causes and crashes.
#' They can be joined by the common column \code{id} (see the example below).
#' Alternatively, each cause can be associated with a specific vehicle in each
#' crash, by first joining the \code{\link{vehicles}} dataset to the
#' \code{\link{crashes}} one, and then joining the \code{causess} dataset by the
#' two common columns \code{id} and \code{vehicle_id}.
#' 
#' Other attributes in a many-to-one relationship with the crashes are
#' available in the datasets \code{\link{vehicles}}, and
#' \code{\link{objects_struck}}.

#' @seealso
#' A comprehensive data dictionary is provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/guide-to-coded-crash-reports/docs/guide-to-coded-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' Details about how crash reports are completed are provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/traffic-crash-reports/docs/traffic-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' @format A data frame with 888072 rows and 7 variables:
#' \describe{
#'   \item{id}{Unique number identifying the crash, by which the \code{link{crashes}} table can be joined.}
#'   \item{index}{Unique identifier of the cause of each crash (unique in combination with \code{id}.}
#'   \item{code}{Identifier of cause in the data dictionary.}
#'   \item{vehicle_id}{Vehicle in the crash with which the cause is associated.}
#'   \item{cause}{Description of the cause.}
#'   \item{cause_category}{Highest-level group to which the cause belongs.}
#'   \item{cause_subcategory}{Lowest-level group to which the cause belongs.}
#' }
#' @source \url{http://www.nzta.govt.nz/resources/crash-analysis-system-data/}
"causes"

#' Objects struck in crashes.
#'
#' @description
#' A dataset of 261276 objects, recorded by the New Zealand Transport
#' Agency (NZTA) as being struck during crashes in the \code{\link{crashes}}
#' dataset.  There is a many-to-one relationship between objects and crashes.
#' They can be joined by the common column \code{id} (see the example below).
#' 
#' Other attributes in a many-to-one relationship with the crashes are
#' available in the datasets \code{\link{vehicles}}, and
#' \code{\link{causes}}.

#' @seealso
#' A comprehensive data dictionary is provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/guide-to-coded-crash-reports/docs/guide-to-coded-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' Details about how crash reports are completed are provided by the NZTA at
#' \url{http://www.nzta.govt.nz/assets/resources/traffic-crash-reports/docs/traffic-crash-reports.pdf}.
#' A copy of it is distributed with this package in the \code{extdata}
#' directory.
#'
#' @format A data frame with 261276 rows and three variables:
#' \describe{
#'   \item{id}{Unique number identifying the crash, by which the \code{link{crashes}} table can be joined.}
#'   \item{object_order}{The order in which the object was struck in each crash (unique in combination with \code{id}.}
#'   \item{object}{The type object struck.}
#' }
#' @source \url{http://www.nzta.govt.nz/resources/crash-analysis-system-data/}
"objects_struck"