Skip to contents

The datras_raw object

Source: vignettes/articles/datras-raw-object.Rmd
datras-raw-object.Rmd

This article describes the datras_raw object, the data structure used throughout DATRASextra. We use the example data set dab (dab, Limanda limanda, from NS-IBTS in 2020-2023).

## Load the package
library(DATRASextra)

## Load the example data
data(dab)

Structure

A datras_raw object is a list of three data frames, with classes datras_raw and DATRASraw:

## Class and elements
class(dab)
#> [1] "datras_raw" "DATRASraw"
names(dab)
#> [1] "CA" "HH" "HL"

The DATRASraw class is kept for backward compatibility with the DATRAS R package, so its functions keep working on a datras_raw object.

The three tables follow the DATRAS exchange format:

  • HH: haul data. One row per haul (position, time, depth, gear, environment).
  • HL: length data. Catch-at-length per species and length class.
  • CA: age-length data. Individual length, weight, sex, maturity, age.

They are linked by haul.id, which is present in all three tables.

Printing the object gives a survey overview:

## Survey overview
dab
#> Object of class 'datras_raw'
#> ===========================
#> Number of hauls: 2660 
#> Number of species: 1 [Limanda limanda (127139)]
#> Number of surveys: 1 [NS-IBTS]
#> Number of gears: 1 [GOV]
#> Number of countries: 8 
#> Years: 2020 - 2023 
#> Quarters: 1 3 
#> Longitude range: -3.96 - 12.61 deg
#> Latitude range: 49.57 - 61.75 deg
#> Depth range: 14 - 257 m
#> Haul duration: 5 - 34 minutes
#> Valid hauls: 2660
#> Hauls with catch: 2263 (zero catch: 397)
#> Extraction: 8 source(s), extracted 2026-10-09, ICES calculation 2022-01-25 to 2025-04-04

Indexing

Use [[ ]] to reach a table:

## The haul table
hh <- dab[["HH"]]
dim(hh)
#> [1] 2660   77

Within a table, columns are accessed and assigned with $ as usual:

## A single column and a few columns
head(dab[["HH"]]$Depth)
#> [1] 35 45 33 36 73 98
head(dab[["HH"]][, c("Year", "Quarter", "Gear", "Depth")])
#>   Year Quarter Gear Depth
#> 1 2020       1  GOV    35
#> 2 2020       1  GOV    45
#> 3 2020       1  GOV    33
#> 4 2020       1  GOV    36
#> 5 2020       1  GOV    73
#> 6 2020       1  GOV    98

## Add or modify a column
dab[["HH"]]$DepthLog <- log(dab[["HH"]]$Depth)
head(dab[["HH"]]$DepthLog)
#> [1] 3.555348 3.806662 3.496508 3.583519 4.290459 4.584967

subset() filters the whole object and keeps the three tables consistent (dropping a haul from HH also drops its HL and CA records):

## Keep valid hauls from quarter 1
q1 <- subset(dab, Quarter == 1 & HaulVal == "V")
q1
#> Object of class 'datras_raw'
#> ===========================
#> Number of hauls: 1268 
#> Number of species: 1 [Limanda limanda (127139)]
#> Number of surveys: 1 [NS-IBTS]
#> Number of gears: 1 [GOV]
#> Number of countries: 7 
#> Years: 2020 - 2023 
#> Quarters: 1 
#> Longitude range: -3.96 - 12.61 deg
#> Latitude range: 49.57 - 61.74 deg
#> Depth range: 14 - 257 m
#> Haul duration: 15 - 34 minutes
#> Valid hauls: 1268
#> Hauls with catch: 1133 (zero catch: 135)
#> Extraction: 4 source(s), extracted 2026-10-09, ICES calculation 2022-01-25 to 2024-04-09

Coded variables (ICES vocabulary)

Many variables are stored as codes (Gear, Country, Ship, StatRec), and species as a WoRMS AphiaID in Valid_Aphia:

## Gear codes and species AphiaID
levels(factor(as.character(dab[["HH"]][["Gear"]])))
#> [1] "GOV"
unique(dab[["HL"]][["Valid_Aphia"]])
#> [1] 127139

Definitions for these codes are in the ICES vocabulary and the DATRAS data resources. The species_info table also maps AphiaIDs to scientific names and ecological groups.

Numbers-at-length: the N matrix

add_numbers_at_length() raises the HL counts to the haul level and stores the result as a matrix N in HH, one row per haul and one column per length class:

## Add numbers-at-length
dab <- add_numbers_at_length(dab)

## One row per haul, one column per length class
## (showing the five largest catches and a few length classes)
big <- head(order(rowSums(dab[["HH"]][["N"]]), decreasing = TRUE), 5)
dab[["HH"]][["N"]][big, 13:17]
#>                                    sizeGroup
#> haul.id                             [15,16) [16,17) [17,18) [18,19) [19,20)
#>   NS-IBTS:2021:3:DE:26D4:GOV:140:15    1452    1340    2345    1005     782
#>   NS-IBTS:2020:1:SE:77SE:GOV:3:3       4454    3093    2846    1485     495
#>   NS-IBTS:2021:3:GB:74E9:GOV:6:7        662     993     794     728     331
#>   NS-IBTS:2020:3:DK:26D4:GOV:175:55     490    2082    2817     857     245
#>   NS-IBTS:2022:3:GB:74E9:GOV:29:25      607     700     677     443     513

Length classes can be changed with cm_breaks or by; see vignette("articles/custom-length-classes").

Weight-at-length: the Wgt matrix

add_weight_at_length() converts numbers to weight using a length-weight relationship and adds a matrix Wgt to HH with the same shape as N:

## Add weight-at-length
dab <- add_weight_at_length(dab)

## Same hauls and length classes as above, now in weight
dab[["HH"]][["Wgt"]][big, 13:17]
#>                                    sizeGroup
#> haul.id                               [15,16)   [16,17)   [17,18)   [18,19)
#>   NS-IBTS:2021:3:DE:26D4:GOV:140:15  52445.62  58821.39 123673.47  63033.69
#>   NS-IBTS:2020:1:SE:77SE:GOV:3:3    160876.58 135772.05 150095.82  93139.33
#>   NS-IBTS:2021:3:GB:74E9:GOV:6:7     23911.16  43589.28  41874.94  45660.22
#>   NS-IBTS:2020:3:DK:26D4:GOV:175:55  17698.59  91392.63 148566.39  53751.12
#>   NS-IBTS:2022:3:GB:74E9:GOV:29:25   21924.58  30727.59  35704.45  27785.00
#>                                    sizeGroup
#> haul.id                               [19,20)
#>   NS-IBTS:2021:3:DE:26D4:GOV:140:15  57799.32
#>   NS-IBTS:2020:1:SE:77SE:GOV:3:3     36586.53
#>   NS-IBTS:2021:3:GB:74E9:GOV:6:7     24464.93
#>   NS-IBTS:2020:3:DK:26D4:GOV:175:55  18108.48
#>   NS-IBTS:2022:3:GB:74E9:GOV:29:25   37916.95

Summing these matrices over their columns gives total numbers and weight per haul, via add_total_numbers_by_haul() and add_total_weight_by_haul() (see the step-by-step guide).