Attempts to extract meaningful information from a filename, typically the date and time a recording started.
Arguments
- file
A filename, or several filenames as either a list or a character vector (the shape returned by
list.files()).- format
Optionally force a given format (see Details). If NULL (default) an attempt is made to automatically detect the format for each file. If "match" and a list of filenames is given then an attempt will be made to find a format that matches all files. This may give incorrect results if the filename is ambiguous (see Details).
- timezone
The timezone the clock of the recorder was set to, defaults to "UTC" (see Details).
Value
A list of file, type of match, datetime. If a list of filenames is
given then a list of such lists is returned.
It is possible to determine additional properties from some files, these will
be added to the list. Which properties those are depends on the format: a
Wildlife Acoustics name gives a model, a prefix, a microphone and a
deployment, a TSA name gives a collection, a taxon, an accession number and a
hash, and a reading the name left in doubt gives ambiguous and
alternatives. A format carrying no time, which TSA names do not, reports
datetime as NA rather than leaving it out.
A name whose digits are not a date
A format is matched on the shape of the digits, and 20240230_120000
satisfies the shape of YYYYMMDD_HHMMSS while spelling a day that does not
exist. Such a name reports datetime as NA, names datetime in unparsed,
and warns, with a class of unparsedDatetime and unparsedField.
unparsed is what tells that apart from a format carrying no time, which
reports NA and names nothing: the first is a date this could not read and
the second is a name with no date in it, and before this they were the same
answer. match is not moved, since 20240230_120000 does follow the
YYYYMMDD_HHMMSS convention — what it does not do is spell a real date.
The same goes for a format the caller names that the name cannot be in, as
parseFilename("recording.wav", format="YYYYMMDD").
readMetadata() silences this one warning, since it takes no date from such
a name in any case and says so, and reports the rest of what the name holds.
Details
Determining the format
It is sometimes impossible to accurately determine the format of a filename, e.g. when an eight-digit 'AudioMoth HEX' only contains numbers it could be confused with a YYYYMMDD format. If a list of filenames is given and the "match" format is specified then an effort will be made to determine the most likely format that applies to all filenames.
A reading that could not be settled from the name says so: ambiguous is
TRUE and alternatives names every format the filename could be in, the one
that was picked included. Neither field is present where the format was not
in doubt. A name of nothing but digits is the case that matters, because a
collection that numbers its records gives names of exactly that shape: eight
digits are read as a date and ten as a count of seconds, and both read just
as well as a record number. readMetadata() therefore takes no date from
such a name, as a confident wrong date is worse than none, though it is
reported here for a caller that knows what its own files are named by.
Asking for a format by name settles it: a format given in format is not a
guess and carries no alternatives. Finding one that fits every name in a
list, with format = "match", does not settle it, since a list of record
numbers agrees with itself exactly as readily as a list of dates does.
Timezones
Most supported formats write a wall clock (e.g. 20200609_191730) into the
filename, with no indication of the timezone the clock of the recorder was
set to. The timezone argument states which timezone that wall clock
belongs to, and defaults to UTC, which is what AudioMoth devices use unless
they are configured otherwise. The datetime returned is therefore the same
instant whatever timezone the machine running the analysis is set to.
The 'AudioMoth HEX' and 'timestamp' formats are exceptions: these encode an
instant rather than a wall clock, so for them timezone only sets the
timezone the datetime is displayed in.
Supported formats
AudioMoth - The newer format for AudioMoth devices consists of a standard YYYYMMDD_HHMMSS.wav format. An eight character hexadecimal filename given this format is treated as 'AudioMoth HEX'.
AudioMoth HEX - Older format for AudioMoth devices consisting of eight hexadecimal characters giving the number of seconds since 1970-01-01 00:00:00 UTC. Conversion is handled by a call to the
audiomoth()function from theseewavepackage (Sueur et al. 2008) .timestamp - A standard date-time format. Uses the R standard origin of 1970-01-01 00:00:00 UTC.
TSA - The convention of the TSA corpus and the collections distributed with it, as
TSA-Porzana_parva_DIG_104_26_1-ee281ac7afd44e08.wav: a collection, the taxon or common name of the animal recorded with the accession number the collection gave it, and a hash of the file. Givescollection,taxon,accessionandhash, and no datetime, as these names carry no time. Much of that corpus holds no embedded metadata at all, so for those recordings the name is the only record of what was recorded.A
taxonis read only where the name carries a scientific name, which is a capitalised genus and a lowercase specific epithet joined by an underscore or a hyphen. Part of the corpus is named by a German common name and a German word for the kind of call instead; no taxon is read from those, as reporting their first words as a genus and a species would invent one. A subspecies cannot be told from an accession number that happens to be a bare word, so the first two parts of a scientific name are taken as the name and the rest as the accession number.Wildlife Acoustics SM2 - Can also be used for Wildlife Acoustics SM4 devices. The filename is split by a call to
seewave::songmeter().Wildlife Acoustics SM3 - The filename is split by a call to
seewave::songmeter().YYYYMMDD_HHMMSS - A standard date-time format.
YYYYMMDD - A standard date format, the time is taken to be midnight.
References
Sueur J, Aubin T, Simonis C (2008). “Seewave, a free modular tool for sound analysis and synthesis.” Bioacoustics, 18(2), 213–226.
See also
readMetadata() reads a file's own embedded metadata and puts what
its name says beside it.
Examples
parseFilename("5E90A4D4.wav")
#> $filename
#> [1] "5E90A4D4.wav"
#>
#> $match
#> [1] "AudioMoth HEX"
#>
#> $datetime
#> [1] "2020-04-10 16:54:44 UTC"
#>
parseFilename("TSA-Porzana_parva_DIG_104_26_1-ee281ac7afd44e08.wav")$taxon
#> [1] "Porzana parva"
# Eight digits could be a date or a record number, and the reading says so.
parseFilename("20240220.wav")$alternatives
#> [1] "YYYYMMDD" "AudioMoth HEX" "record number"
