Skip to content

Commit d210ba2

Browse files
committed
Specification: Added well-known fields: Hardware Version, Firmware Version, Temperature, Humidity. Clarified Loc Position description. Added vendor disclaimer.
1 parent 37324a0 commit d210ba2

File tree

1 file changed

+48
-28
lines changed

1 file changed

+48
-28
lines changed

doc/guano_specification.md

Lines changed: 48 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ string "\n" as a newline. At this time, this specification makes no attempt
7373
to define an escape for encoding the literal string "\n" with a meaning apart
7474
from "newline".
7575

76-
**TODO:** Binary field values should be encoded as Base64. However, Base64 enforces
76+
Binary field values should be encoded as Base64. However, Base64 enforces
7777
a maximum line length, and the GUANO metadata format thus far delimits fields
7878
by newline. Enforcing a short line length for potentially-large binary values
7979
would ease the development of reading implementations which must allocate
@@ -192,26 +192,26 @@ The following namespaces have been reserved or registered. Any manufacturer who
192192
utilizes their own custom GUANO fields is encouraged to add their namespace to
193193
this list so that it isn't accidentally used by another manufacturer.
194194

195-
**GUANO**
195+
**GUANO**
196196
This reserved namespace is for meta-metadata pertaining specifically to the
197197
GUANO metadata in use.
198198

199-
**BAT**
199+
**BAT**
200200
Binary Acoustic Technologies
201201

202-
**MSFT**
202+
**MSFT**
203203
Myotisoft
204204

205-
**PET**
205+
**PET**
206206
Pettersson
207207

208-
**SB**
208+
**SB**
209209
SonoBat
210210

211-
**Anabat**
211+
**Anabat**
212212
Titley Scientific
213213

214-
**WAC**
214+
**WAC**
215215
Wildlife Acoustics
216216

217217

@@ -258,60 +258,80 @@ fields from the following defined or "well-known" list.
258258
Reading implementations should expect to encounter any of the following
259259
fields in a compliant GUANO file.
260260

261-
**GUANO|Version**
261+
**GUANO|Version**
262262
required, float. GUANO metadata version in use. This specification defines version `1.0`.
263263

264-
**GUANO|Size**
264+
**GUANO|Size**
265265
optional, integer. Total size, in bytes, of pre-allocated GUANO metadata space. Pre-allocating whitespace within the `guan` subchunk allows for writing/editing metadata without re-writing the entirety of the file back to disk. This field should only be used if pre-allocating space, so that writing (editing) implementations may check to see if their changes overflow the bounds of pre-allocated metadata space.
266266

267-
**Filter HP**
267+
**Filter HP**
268268
optional, float. High-pass filter frequency, in kHz.
269269

270-
**Filter LP**
270+
**Filter LP**
271271
optional, float. Low-pass filter frequency, in kHz.
272272

273-
**Length**
273+
**Firmware Version**
274+
optional, string. Device's firmware version, in manufacturer's own descriptive format.
275+
276+
**Hardware Version**
277+
optional, string. Device's hardware revision or hardware options, in manufacturer's own descriptive format.
278+
279+
**Humidity**
280+
optional, float. Relative humidity as a percentage in the range 0.0 - 100.0.
281+
282+
**Length**
274283
optional, float. Recording length, in seconds. This should be the "actual length", which will be identical to the .WAV length for direct-recorded files, but will be calculated for time-expanded recordings (.WAV length divided by TE factor).
275284

276-
**Loc Accuracy**
277-
optional, float. Location accuracy, in meters.
285+
**Loc Accuracy**
286+
optional, float. Location accuracy, in meters. This should be the Estimated Position Error (EPE); this statistical range states that 68% of measurements will fall within this radius, 95% of measurements will fall within twice this radius. EPE is calculated differently by different GPS receiver manufacturers, therefore it should be stressed that this value is merely an *estimate* of accuracy. Detector manufacturers may opt to estimate accuracy more coarsely if EPE is not available directly from their GPS receiver, but should express the value in the same one-sigma fashion.
278287

279-
**Loc Elevation**
288+
**Loc Elevation**
280289
optional, float. Elevation / altitude above mean sea level, in meters.
281290

282-
**Loc Position**
291+
**Loc Position**
283292
optional, (float float). Location that the recording was made, as a WGS84 latitude longitude tuple.
284293

285-
**Make**
294+
**Make**
286295
optional, string. Manufacturer of the recording hardware.
287296

288-
**Model**
297+
**Model**
289298
optional, string. Model name or number of the recording hardware.
290299

291-
**Note**
300+
**Note**
292301
optional, multiline string. Freeform textual note associated with the recording.
293302

294-
**Samplerate**
303+
**Samplerate**
295304
optional, integer. Recording samplerate, in Hz. This should be equal to the .WAV samplerate for direct-recording detectors, but should be a product of ``TE`` and the .WAV samplerate for time-expansion detectors.
296305

297-
**Species Auto ID**
306+
**Species Auto ID**
298307
optional, string. Species or guild classification, as determined by automated classification.
299308

300-
**Species Manual ID**
309+
**Species Manual ID**
301310
optional, string. Species or guild classification, as determined by a human.
302311

303-
**Tags**
312+
**Tags**
304313
optional, list of strings. A comma-separated list of arbitrary strings so that end users may easily apply any tags / labels that they see appropriate.
305314

306-
**TE**
315+
**TE**
307316
optional, integer. Time-expansion factor. If not specified, then 1 (*no* time-expansion, aka direct-recording) is assumed.
308317

309-
**Timestamp**
318+
**Temperature**
319+
optional, float. Temperature in degrees Celsius. This is assumed to be the "outside temperature"; if a device records temperature inside its housing and that temperature is not an accurate proxy for outside temperature, a vendor-specific field should be used instead.
320+
321+
**Timestamp**
310322
required, datetime. Date and time of the start of the recording, in ISO 8601 compatible format (see datetime specification above). It is very strongly recommended that, if UTC offset is known, it is explicitly specified rather than recording the timestamp only in UTC "zulu" time. This is because local time is overwhelmingly more important when it comes to bat echolocation data than is absolute UTC time; unfortunately GPS receivers provide only UTC time, and the local UTC offset for a location may vary according to political boundaries.
311323

312324

313325
Specification History
314326
---------------------
315327

316-
2015-10-12 0.0.1 Initial public release of draft GUANO specification with
317-
reference Python implementation
328+
2016-01-30 | 0.0.2 | Added well-known fields: Hardware Version, Firmware Version, Temperature, Humidity.
329+
Clarified Loc Position description.
330+
331+
2015-10-12 | 0.0.1 | Initial public release of draft GUANO specification with reference Python implementation
332+
333+
334+
Notes
335+
-----
336+
337+
* The use of manufacturer or product names in this specification does not imply endorsement, support, or any other association by those manufacturers or products; nor does it imply compliance with the GUANO specification.

0 commit comments

Comments
 (0)