formatFields {track2KBA}

Format tracking data

Description

formatFields formats the column names of a data frame so that they are accepted by track2KBA functions.

Usage

formatFields(
  dataGroup,
  formatBL = FALSE,
  fieldID,
  fieldLat,
  fieldLon,
  fieldDateTime = NULL,
  fieldDate = NULL,
  fieldTime = NULL,
  formatDT = NULL,
  cleanDF = FALSE
)

Arguments

dataGroup

data.frame or data.table.

formatBL

logical. Is data set already in format of BirdLife Seabird tracking database? If so, indicate TRUE. fieldID must still be specified and other fields may be ignored. arguments.

fieldID

character. Unique identifier; e.g. for individuals or dataGroup.

fieldLat

numeric. Name of column corresponding to the LATITUDINAL positions.

fieldLon

numeric. Name of column corresponding to the LONGITUDINAL positions.

fieldDateTime

character. If existing, this is the name of the column corresponding to the combined DATE & TIME.

fieldDate

character. Name of column corresponding to the DATE only.

fieldTime

character. Name of column corresponding to the TIME only.

formatDT

character. What is the format of the data in your DateTime, Date, and Time columns (e.g. "ymd_HMS")? Specify the format following the standard in parse_date_time.

cleanDF

logical scalar (T/F). Should columns which are non-essential for track2KBA analysis be removed from dataframe, or not? Removal will speed analysis up a bit.

Details

If data are already in format of BirdLife Seabird tracking database (http://www.seabirdtracking.org/), use formatBL = TRUE and formatting conversion will occur automatically. I.e., data have following columns: "latitude", "latitude", "date_gmt", "time_gmt". You must still specify the ID column as either the track or animal identifier.

By matching up the names of your existing columns with those recognized by track2KBA functions, formatFields re-formats the data frame, and converts the date/date-time fields into a singe date-time field of class POSIXct.

If date-time is combined in a single column, please use fieldDateTime instead of fieldDate and fieldTime.

Value

Returns a data.frame, with 'ID', 'Latitude', 'Longitude', and 'DateTime' (class POSIXct) columns.

Examples

## Load example dataset
tracks_raw <- track2KBA::boobies
## using data with user-custom format i.e. with separate Date and Time fields
tracks_formatted <- formatFields(
  dataGroup = tracks_raw,
  fieldID   = "track_id",
  fieldLat  ="latitude",
  fieldLon  ="longitude",
  fieldDate ="date_gmt",
  fieldTime ="time_gmt"
  )
## using data with only single Date field
tracks_formatted <- formatFields(
  dataGroup = tracks_raw,
  fieldID   = "track_id",
  fieldLat  ="latitude",
  fieldLon  ="longitude",
  fieldDate ="date_gmt",
  formatDT = "ymd"
  )
## Not run: 
## if data were downloaded from Seabird Tracking Database
tracks_formatted <- formatFields(
  dataGroup=tracks_raw,
  formatBL,
  fieldID = "bird_id")
  
## End(Not run)