# 1.3) The preload() function

#### Hugo Flávio

#### 2020-08-01

## Index

1. Preparing your data
   1. Structuring the study area
   2. Creating a distances matrix
   3. The preload() function
2. explore()
   1. Processes behind explore()
   2. Inspecting the explore() results
3. migration()
   1. Processes behind migration()
   2. Inspecting the migration() results
   3. One-way efficiency estimations
4. residency()
   1. Processes behind residency()
   2. Inspecting the residency() results
   3. Multi-way efficiency estimations
5. Manual mode
6. Beyond the three main analyses

## Note!

The content on this page assumes that 1) You are familiar with handling R objects and 2) you are familiar with the the traditional input files for actel. If you do not know which inputs are necessary to run actel, you can find more information about them in the first page of the manual.

## The preload() function

If you are working with large databases, or retrieving your detection data from a server (such as ETN or OTN), it may be impractical to have to save all the data into CSV files to be able to run actel analyses. To help you out, I have created the function `preload()`, which pre-compiles R objects into a format that is actel-compatible.

Note:
  The main functions will not accept a datapack that does not originate from a `preload()` call run during the same R session. This is to ensure that the data is correctly formatted and up to date.

To run the `preload()` function, you must first create four R objects, equal in structure to their CSV counterparts: biometrics, spatial, deployments and detections. Additionally, you also need to set the `tz` argument.

Once you have these four objects, you can run `preload()`:

    x <- preload(biometrics = biometrics, spatial = spatial, deployments = deployments,
        detections = detections, tz = "Europe/Copenhagen")

You can then use the resulting object to run an actel analysis:

    results <- explore(datapack = x)

## What about the optional files?

If you want to use `preload()` and include a distances matrix or the equivalent of a ‘spatial.txt’ file, you must use the `distances` and `dot` arguments (respectively). I recommend that you calculate the distances matrix using the actel functions provided for that (more details in this page). As for the dot argument, simply create a string that looks like what your ‘spatial.txt’ file would have looked like. e.g:

    # You can create multiple lines, just like in the spatial.txt case:
    dot <-
    "River0 -- River1 -- River3 -- River4 -- River5 -- River6 -- Fjord1 -- Fjord2 -- Sea1
    River1 -- River2 -- River3"

    x <- preload(biometrics = biometrics, spatial = spatial, deployments = deployments,
        detections = detections, distances = distances, dot = dot, tz = "Europe/Copenhagen")

## migration/residency-compatible datapacks

If your final goal is to run a `migration()` or `residency()` analysis, remember to have a ‘Section’ column in your spatial input.

    x <- preload(biometrics = biometrics, spatial = spatial, deployments = deployments,
        detections = detections, distances = distances, dot = dot, tz = "Europe/Copenhagen")

You can then run residency and migration simply sourcing the datapack!

    results <- migration(datapack = x)

    # or

    results <- residency(datapack = x)

## Remaining arguments

The `preload()` function also contains the following arguments: `exclude.tags`, `disregard.parallels`, `discard.orphans`, `start.time` and `stop.time`. These perform exactly the same tasks as their counterparts on the main functions.

Note:
  If you are using preloaded data, these arguments will be disregarded in the main analysis call, so make sure to set them correctly in the `preload()` call!

## Final notes on the detections

If you load detections through `preload()`, they will be required to have four specific columns: Timestamp, Receiver, CodeSpace and Signal. You can use the functions `extractCodeSpaces()` and `extractSignals()` to help you out if needed. On top of these four columns, you can include two columns for sensor data: Sensor.Value and Sensor.Unit (notice the capital first letters). On top of these six columns, you can include as many columns as you want! These extra columns will be carried through the main analyses and exported in the `detections` and `valid.detections` objects.

Note:
  Because, at this point, the detections are no longer influenced by the manufacturer, actel will not convert code-spaces. This means that whichever CodeSpace you selected for your tags, is the one that will be displayed at the end of the analyses!

Return to previous page

Back to top.