array_config: Restructure the configuration of arrays

In InStreamFisheries/PITR: Functions to collate, manage and summarize PIT telemetry data

Description

Function allows users to combine unique readers into an array, split readers with multiple antennas into single readers, and rename antennas. Use of this function allows users to manage data for further analysis using det_eff, direction, direction_total, and first_last functions.

Usage

array_config(data, configuration, array_name = NULL, r1 = NULL,
  r2 = NULL, r3 = NULL, r4 = NULL, reader_name = NULL,
  new_reader_1_antennas = NULL, ao1 = NULL, ao2 = NULL, ao3 = NULL,
  ao4 = NULL, an1 = NULL, an2 = NULL, an3 = NULL, an4 = NULL)

Arguments

data	telemetry dataset created using old_pit or new_pit function
configuration	either "combine", "split" or "rename_antennas"
array_name	name of array
r1	name of reader 1
r2	name of reader 2
r3	name of reader 3
r4	name of reader 4
reader_name	name of reader to split or for renaming antennas
new_reader_1_antennas	specific antennas to be grouped into reader 1
ao1	old antenna 1
ao2	old antenna 2
ao3	old antenna 3
ao4	old antenna 4
an1	new antenna 1
an2	new antenna 2
an3	new antenna 3
an4	new antenna 4

Details

This function allows complex antenna arrangements to be organized into arrays, or antennas in single arrays to be renamed sequentially. The array_config function is iterative and the user may need to run the function several times to reach the desired study configuration (see examples).

Function is dependent on what the user defines in the configuration argument:

1. configuration = "split": Used to split multi readers into two or more single readers to allow the combination of single readers into a user-specified array (see Example 1). The arguments reader_name and new_reader_1_antennas are required for "split". Argument new_reader_1_antennas is used to define the antennas to group into reader 1. All other antennas are grouped into reader 2.

2. configuration = "combine": Used to combine up to four single readers into one array (see Example 2). Arguments array_name and r1 through rx are required for "combine". If a user wants to combine a multi reader with another reader (either a multi or single reader), the user first must split the multi reader into two or more single readers and then combine them together into an array. If a user needed to split a multi reader with four single readers for use in "combine", they would need to run configuration "split" four times.

3. configuration = "rename_antennas": Used to either rename antennas part of an array (if array_name is specified) or antennas part of a reader (if reader_name is specified) (see Example 3). Arguments ao1 through aox and an1 through anx are require for "rename_antennas". Arguments with the prefix ao correspond to the old (or current) antenna numbering scheme, whereas arguments with the prefix an correspond to the new antenna numbering scheme. Users can rename up to four antennas for one reader or one array.

Value

Updated dataset for further analysis using det_eff, direction, direction_total and first_last functions.

Examples

# Load test dataset containing detections from a multi reader with two antennas
oregon_rfid <- new_pit(data = "oregon_rfid", test_tags = NULL, print_to_file = FALSE, time_zone = "America/Vancouver")

# Example 1: Split a multi reader with two antennas into two single readers
# Users can split multi readers with two or more antennas into two or more single readers that can later be combined into user-defined arrays
split <- array_config(data = oregon_rfid, configuration = "split", reader_name = "dam", new_reader_1_antennas = "1")

# Example 2: Combine two single readers into an array called fishway
# Users can combine two or more single readers (using a raw or split dataset) into arrays
# If there is an existing dataset with two or more readers (multi or single readers or a combination), the user can start by combining the readers into arrays
combine <- array_config(data = split, configuration = "combine", array_name = "fishway", r1 = "dam_1", r2 = "dam_2")

# Example 3: Rename the two antennas. Antenna 1 becomes antenna 3, and antenna 2 becomes antenna 4.
rename_one <- array_config(data = combine, configuration = "rename_antennas", array_name = "fishway", ao1 = 1, an1 = 3)
rename_two <- array_config(data = rename_one, configuration = "rename_antennas", array_name = "fishway", ao1 = 2, an1 = 4)
# The above calls could be combined:
rename_multiple <- array_config(data = combine, configuration = "rename_antennas", array_name = "fishway", ao1 = 1, an1 = 3, ao2 = 2, an2 = 4)

InStreamFisheries/PITR documentation built on Jan. 7, 2021, 1:02 p.m.