preprocessLight: Interactively derive twilight

In SWotherspoon/BAStag: Basic data processing for light based geolocation archival tags

Description

Interactively derive and edit twilight times.

Usage

preprocessLight(
  tagdata,
  threshold,
  offset = 0,
  lmax = 64,
  zlim = c(0, lmax),
  extend = 0,
  dark.min = 0,
  zenith = 96,
  fixed = NULL,
  map = FALSE,
  plotMap = NULL,
  twilights = NULL,
  stage = 1,
  point.cex = 0.8,
  width = 12,
  height = 4,
  palette = defaultPalette[c(5, 2, 9, 3, 4, 1, 13)]
)

Arguments

tagdata	a dataframe with columns Date and Light that are the sequence of sample times (as POSIXct)
threshold	the light threshold that defines twilight.
offset	the starting hour for the vertical axes.
lmax	the maximum light level to plot.
zlim	the range of light levels to plot in images.
extend	a time in minutes. The function seeks periods of darkness that differ from one another by 24 hours plus or minus this interval.
dark.min	a time in minutes. Periods of darkness shorter than this interval will be excluded.
zenith	the solar zenith angle that defines twilight.
fixed	a two column array of fixed locations
map	whether to plot an approximate path
plotMap	a function to plot a background map when map=TRUE.
twilights	a result of a previous run to re-edit
stage	when re-editing, the stage to commence at
point.cex	expansion factor for plot points.
width	width of the interface windows.
height	height of the interface windows.
palette	a colour palette of 7 colours.

Details

This function allows the user to interactively search for and edit twilight times corresponding to a given light threshold. The process consists of four stages,

1. Subset – selection of a subset of the data for processing

2. Search – semi-automated search for the twilights

3. Insert – optionally, twilights are inserted where the light record is incomplete

4. Edit – optioanlly, individual twilights are manually adjusted based on the light profiles.

At each stage, user is presented with two windows. The first shows the data in its entirety and allows the user to select a subset of the data to be manipulated in the second window.

In the first stage the user can restrict the data to a subset for processing. The first window shows a light image and a coloured rectangle above the image shows the selected subset of data. In the first window, clicking with either mouse button produces a zoomed image of the clicked region in the second window. In either window, left mouse clicks define the start of the selected subset and right mouse clicks defines the end of the selected subset. The "a" key accepts the current selection an proceeds to the next stage.

In either window

'q'	Quits
'a'	Accepts any changes and advances to the next stage
'+'/'-'	Zoom in or out

In the second stage the user guides an semi-automated search for the twilight times. Again, a right mouse click in the first window produces a zoomed image of the clicked region in the second. In the second window, the user must click in periods of nights. Left mouse clicks select regions to be searched for twilights, right mouse clicks select regions that should not be searched. The "u" key provides an undo facility, allowing mouse clicks to be deleted, and the "a" key terminates the search and proceeds to the next stage.

In either window

'q'	Quits, returning the dataframe of edited twilights
'a'	Accepts any changes and advances to the next stage
'b'	Returns back to the previous stage
'u'	Removes the most recent search point
'+'/'-'	Zoom in or out

In the third stage the user may insert additional twilights where the light record is incomplete. As for the first two stages, right mouse clicks in the first window produce a zoomed image of the clicked region in the second window. In the second window, the user may ad times of sunrise or sunset. A left mouse click adds a sunset, and a right mouse click adds a sunrise. The numeric keys on the keyboard mark the most recent inerted point with a "mark" 0 to 9. If the user provides both the zenith argument and a two column matrix of locations for the fixed argument, marking a point with the digit n replaces the marked twilight with the computed twilight time for the n-th fixed location. Again "u" provides an undo facility and the "a" key proceeds to the next stage.

In either window

'q'	Quits, returning the dataframe of edited twilight segments
'a'	Accepts any changes and advances to the next stage
'b'	Returns back to the previous stage
'u'	Removes the most recent insertion
'+'/'-'	Zoom in or out
'0'-'9'	Mark the most recent addition

In the fourth stage, the user may adjust individual twilights based on the observed light profile. The first window now shows the sequence of twilights. A right mouse click on any twilight shows the light profile for that twilight in the second window, together with the profiles for the preceeding and following days. A left click in the second window proposes a new location for the current twilight, but no change is made until the edit is accepted with the "a" key. A right click in the second window marks the twilight as deleted, and the numeric keys mark the twilight with a "mark" 0 to 9. If the user provides both the zenith argument and a two column matrix of locations for the fixed argument, marking a point with the digit n replaces the marked twilight with the computed twilight time for the n-th fixed location. The "u" key reverts the edits to the current twilight.

In either window

'q'	Quits, returning the dataframe of edited twilight segments
'a'	Accepts the candidate edit
'b'	Returns back to the previous stage
'd'	Toggle deletion of this twilight
'i'	Toggles the display of the light image
'p'	Toggles the display of individual points
'p'	Toggles the display of surrounding profiles
'r'	Resets the selection
'u'	Revert changes to this twilight
'+'/'-'	Zoom in or out
'Left arrow'	Jump to previous twilight
'Right arrow'	Jump to ext twilight
'0'-'9'	Mark this twilight

If map=TRUE an additional window is constructed that shows the approximate track based on hte current estimated twilights. A function to draw a background map for this window can be supplied with the plotMap argument. This must be ia function of two arguments xlim and ylim the determine the extent of the plot. A left mouse click in this window selects the twilight associated with the nearest location, a right mouse click in this window displays the time of twilight at the selected location for the currently selected date as an edit in the light profile window, and this edit can be accepted with the "a" key.

The results of a previous call of preprocessLight can be updated by providing the dataframe generated by the previous call as the twilights argument, and using the stage argument to determine to point from which to restart the process.

Value

A dataframe with columns

Twilight	times of twilight
Rise	logical indicating sunrise
Deleted	logical indentifying deleted twilights
Marker	integer vector of marks
Inserted	logical vector of marks
Twilight3	Twilight from stage 3
Marker3	Marker from stage 3

where each row corresponds to a single twilight.

SWotherspoon/BAStag documentation built on March 29, 2021, 2:47 a.m.