Read all buzzdetect result files in a directory (recursively).

Applies read_results to every buzzdetect result file found recursively under dir_results and row-binds the results into a single data.table. All arguments are forwarded to read_results.

Usage

read_directory(
  dir_results,
  posix_formats = NA,
  first_match = FALSE,
  drop_filetime = TRUE,
  dir_nesting = NULL,
  return_ident = FALSE,
  tz = NA
)

Arguments

dir_results: The directory holding all buzzdetect results to be read.
posix_formats: Character vector of POSIX format strings (see base::strptime) describing the timestamp embedded in each file name (e.g. '%y%m%d_%H%M' for 230809_0600). Supply multiple strings when recordings from different logger types are mixed in one directory. If NA (default), results are left in file-time. See file_start_time.
first_match: Controls behaviour when multiple formats produce different times for the same file. FALSE (default) returns NA with a warning; TRUE accepts the time from the first matching format with a message.
drop_filetime: If TRUE (default), the start_filetime / bin_filetime column is removed once start_datetime / bin_datetime has been added. Set FALSE to keep both. Ignored if no POSIX formats are given.
dir_nesting: A character vector used to name the directory levels above the results file. Each element becomes a column in the output, storing the components of the path. For example, dir_nesting = c('site', 'recorder') for the path data/2026/siteA/recorder_4/250704_11343_buzzdetect.csv would add a site column (holding the value 'siteA') and a recorder column (holding the value 'recorder_4').
return_ident: The 'ident' is the relative path from your data directory to the results file, without the _buzzdetect tag or file extension. Useful for finding corresponding audio files or annotations. Set TRUE to add an ident column as the first column of the output.
tz: Time zone string passed to base::as.POSIXct (e.g. 'America/New_York'). See OlsonNames() for valid values.. Ignored if the results already contain a start_datetime or bin_datetime column.

Value

A data.table combining all files, with the same columns as read_results plus an optional ident column.

Details

Returns an empty data.frame (with a warning) if no result files are found, which allows safe use in pipelines with data.table::rbindlist or similar.

Examples

dir <- system.file('extdata/five_flowers', package = 'buzzr')

# Read all five files and combine into one data.table
read_directory(
  dir,
  posix_formats = '%y%m%d_%H%M',
  tz            = 'America/New_York',
  dir_nesting   = c('flower', 'recorder')
)
#>             flower recorder      start_datetime activation_ins_buzz
#>             <char>   <char>              <POSc>               <num>
#>      1:    chicory    1_104 2025-07-04 00:00:00                -1.7
#>      2:    chicory    1_104 2025-07-04 00:00:00                -2.0
#>      3:    chicory    1_104 2025-07-04 00:00:01                -2.1
#>      4:    chicory    1_104 2025-07-04 00:00:02                -2.0
#>      5:    chicory    1_104 2025-07-04 00:00:03                -2.0
#>     ---                                                            
#> 449996: watermelon     1_73 2024-07-27 23:59:55                -1.7
#> 449997: watermelon     1_73 2024-07-27 23:59:56                -1.6
#> 449998: watermelon     1_73 2024-07-27 23:59:57                -1.7
#> 449999: watermelon     1_73 2024-07-27 23:59:58                -1.3
#> 450000: watermelon     1_73 2024-07-27 23:59:59                -1.6
#>         activation_ambient_rain activation_ins_trill activation_mech_plane
#>                           <num>                <num>                 <num>
#>      1:                    -2.0                 -1.9                  -2.2
#>      2:                    -2.0                 -1.9                  -2.4
#>      3:                    -2.8                 -2.8                  -3.4
#>      4:                    -2.6                 -2.4                  -3.2
#>      5:                    -2.3                 -2.4                  -2.5
#>     ---                                                                   
#> 449996:                    -1.8                 -1.9                  -2.0
#> 449997:                    -2.2                 -2.3                  -2.5
#> 449998:                    -2.1                 -2.1                  -2.4
#> 449999:                    -1.9                 -2.0                  -1.8
#> 450000:                    -2.2                 -2.1                  -2.2

# Also include the ident column for tracing results back to their source file
read_directory(dir, return_ident = TRUE)
#>                               ident start_filetime activation_ins_buzz
#>                              <char>          <num>               <num>
#>      1:   chicory/1_104/250704_0000           0.00                -1.7
#>      2:   chicory/1_104/250704_0000           0.96                -2.0
#>      3:   chicory/1_104/250704_0000           1.92                -2.1
#>      4:   chicory/1_104/250704_0000           2.88                -2.0
#>      5:   chicory/1_104/250704_0000           3.84                -2.0
#>     ---                                                               
#> 449996: watermelon/1_73/240727_0000       86395.20                -1.7
#> 449997: watermelon/1_73/240727_0000       86396.16                -1.6
#> 449998: watermelon/1_73/240727_0000       86397.12                -1.7
#> 449999: watermelon/1_73/240727_0000       86398.08                -1.3
#> 450000: watermelon/1_73/240727_0000       86399.04                -1.6
#>         activation_ambient_rain activation_ins_trill activation_mech_plane
#>                           <num>                <num>                 <num>
#>      1:                    -2.0                 -1.9                  -2.2
#>      2:                    -2.0                 -1.9                  -2.4
#>      3:                    -2.8                 -2.8                  -3.4
#>      4:                    -2.6                 -2.4                  -3.2
#>      5:                    -2.3                 -2.4                  -2.5
#>     ---                                                                   
#> 449996:                    -1.8                 -1.9                  -2.0
#> 449997:                    -2.2                 -2.3                  -2.5
#> 449998:                    -2.1                 -2.1                  -2.4
#> 449999:                    -1.9                 -2.0                  -1.8
#> 450000:                    -2.2                 -2.1                  -2.2