New Zealand Bird Band Text Exchange Format (NZBBTEF) v0.1.0

nzbbtef.md

New Zealand Bird Band Text Exchange Format v0.1.0

George Moon
https://orcid.org/0000-0002-7157-8729

Summary

There are many different methodologies worldwide for banding/ringing birds, and there are also many standards for recording this information. However these standards are often heavy handed and complex, and encompass more information than is necessary for the simple sharing of information about the bands currently on a bird.

Hence the New Zealand Bird Band Text Exchange Format ("Format") is a proposed format for being able to relay information about bird bands currently worn by a given bird.

It is:

• A simple format that uses a string of characters found on a standard US style keyboard.
• Designed to be a flexible format that can be used to capture a representation of all bands currently used on NZ birds, but without being overly complex.
• A format that can be 'learned-by-doing' rather than reading long specifications, through the use of simple validation tools.
• A format that can be mostly understood simply by reading it without reference to the specification.
• A format that can be represented in more human-friendly forms (e.g. Black C on Yellow) as well as shorter forms (e.g. K C on Y)

It is not:

• An exhaustive format to capture all given information about a birds' bands (e.g. width, material type).

The idea is that this will be complemented with a series of programmatic tests, and a simple online tool allowing for the visualisation and verification of NZBBTEF strings.

1. Licence and Contributions

Contributions to the Format are encouraged and welcomed. It is made available under a CC BY-SA 4.0 licence.

2. Background

The New Zealand National Bird Banding Scheme ("NZNBBS") is the national office under the Deparment of Conservation tasked with tracking bird information. They maintain a spreadsheet template for the submission of banding data which is able to be downloaded from here: https://www.doc.govt.nz/our-work/bird-banding/how-to-submit-banding-data/

This Format is informed by the information provided in this spreadsheet, other banding schemes used worldwide and other common-practice methodologies.

2.1. Reference Documents

• EURING Exchange Code 2000+: https://euring.org/files/documents/EURING2000%2BCodev112.pdf
• Black-tailed Godwits' Colour Ring Schemes: http://baguage.lpo-anjou.org/prog_baguage_bqn.pdf

2.2. Document Details

• This document is written in Markdown.
• Terms defined in this document are capitalised.

3. Banding Conventions

3.1. Technical Details

1. Band is the term used for a piece of plastic or metal placed on the leg of a bird.
2. Combo is the term used for a string of characters representing the layout of various Bands on a bird.
3. All Combos must be able to be typed with a standard US keyboard layout.
4. Components of Combos are case-sensitive unless otherwise specified.
5. Whitespace (spaces) are part of the syntax.

3.2. Band Placement

     ___ 
    ('v')
   (/   \)
   (_____)
    | ║║ |  Tibia
    /    \  Tarsus
   x     x
   
  Right Left

Figure 1: Definition of conventions relating to bird anatomy.

1. Consistent with typical practice, the legs are labelled as Left and Right when viewed from the perspective of the bird. Hence, viewing a bird facing towards you (Figure 1), the Right leg is on the left and the Left leg is on the right from the perspective of the viewer.
2. Bird legs are labelled in two parts as Tibia and Tarsus. The Tibia is the upper leg Part (above the joint) and the Tarsus is the lower leg Part.
3. It is expected that up to three Bands will have Position on each Part, with the first one being designated as the Top and the last one as the Bottom.

3.3. Band Colours

1. Each species appears to use a different variation of bands and colour nomenclature. However, there is a code specified by the NZNBBS, which will be used for this Format.
2. All Colours use a case-sensitive one or two letter code.
3. One Colour (Light Green/Lime) has two terms, both of which are acceptable.
4. It is possible to have more than one Colour on a Band:
   1. As a secondary colour (e.g. the characters on a Band)
   2. As a striped Band
5. Colours are defined as follows:

  M       Metal/Uncoloured
  K       Black
  Gr      Grey
  W       White
  R       Red
  O       Orange
  PO      Pale Orange
  NO      Neon Orange/Fluoro Orange
  Y       Yellow
  PP      Pale Pink
  P       Pink
  NP      Neon Pink/Fluoro Pink/Hot Pink
  CP      Crimson/Dark Pink
  LPu     Light Purple
  Pu      Purple
  PB      Pale Blue
  LB      Light Blue
  B       Medium Blue/Blue
  DB      Dark Blue
  NG      Neon Green/Fluoro Green
  LG      Light Green/Lime Green
  PG      Pale Green
  G       Medium Green/Green
  DG      Dark Green
  Br      Brown
  
Special cases:
  S       Striped designator
  F       Flag designator
  x       Null band

3.4. Band Style

1. Bands vary a lot in terms of style and can include:
   • Uncoloured metal bands with engraved numbers
   • Powder coated metal bands
   • Powder coated metal bands with engraved numbers
   • Single colour plastic bands
   • Multi-colour plastic bands (striped)
   • Single colour plastic bands with one or more letters or symbols
   • Bands with flags
2. Bands can vary in width and diameter depending on species.
3. Combos can be made up of any combination of the above.
4. All characters are assumed to be capital letters.
5. For the purposes of this Format, the following components will be captured:
   1. The Colour(s) (or absence of, i.e. uncoloured metal)
   2. The presence of character(s)
   3. The presence of a flag
   4. The presence of an engraved Band ID

3.5. Special Cases

1. The some special cases that must be considered with regards to the functioning of the format.
2. Assumptions about the absence of characters:
   1. It is assumed that no Band uses a bracket as a character or part of its Band ID ( or )
   2. It is assumed that no Band uses a backtick `, slash / or backslash \ as a character or part of its Band ID
3. Non-typable characters:
   1. Some Band characters are known to be characters not represented on the keyboard, such as a capital Sigma or a Diamond.
   2. These characters may be represented by their HTML named entity.
   3. Examples:
      1. Σ Σ
      2. ◊ ◊
      3. ☰ ☰
4. For the avoidance of doubt, there is a difference between on (a special term) and ON which could feasibly be two characters on a band.

4. Format specification

4.1. General specifications

1. A Combo is between 1 and 250 characters in length.
2. Order is important.
3. Whitespace is important.
4. The Format is case-sensitive.
5. Character definitions (with regex representation)
   1. Not permitted:
      1. /\t/ Tab
      2. /\s{2,}/ More than two spaces in a row
      3. ` Backtick
   2. Special characters (permitted):
      1. /\// Slash: over separator
      2. /-/ Dash: leg separator
      3. /\(\)/ Brackets: metadata separator
   3. Normal characters (permitted):
      1. 1234567890=qwertyuiop[]asdfghjkl;'zxcvbnm,. ~!@#$%^&*_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?

4.2. Band specifications

1. At its shortest, a Band has a single Colour:
   1. A Colour must be one of the Colours designated in this standard.
      • Example: Y (Yellow)
   2. Striped Colours are represented by two Colours separated by an S with no whitespace.
      • Example: LPuSK (Light Purple/Black Striped)
   3. Colours can be represented by their full name with no separating white space.
      • Example: LightBlueSBlack (Light Blue/Black Striped)
      • Example: NeonGreen C on Yellow (Neon Green C on Yellow)
      • Example: Pink(C-1234) (Pink with C-1234)
2. If a Band has characters:
   1. This must be expressed in the ordered form:
      1. Colour of Character(s)
      2. Character(s)
      3. on
      4. Colour(s) of Band
   2. The presence of characters is recognised by the presence of the lowercase keyword on.
   3. Example:
      • K C on Y (Black C on Yellow)
      • Y ON on K (Yellow ON on Black)
      • K - on G (Black - on Medium Green)
      • Black Z on PPSPu (Black Z on Striped Pale Pink/Purple)
3. The presence of a flag is denoted by an F prefixing the Band Colour.
   1. Examples:
      • FO (Orange Flag)
      • K C on FY (Black C on Yellow Flag)
      • K C on FLPuSK (Black C on Striped Light Purple/Black Flag)
4. The presence of an engraved Band ID can optionally be denoted using brackets, optionally attached as a suffix to a Colour.
   1. If no Colour is given, it is assumed to be Uncoloured/Metal.
   2. Any - symbol used within brackets is not treated as a separator (see 4.3. Combo specifications).
   3. Examples:
      • LB(C-9542) (Light Blue with C-9542)
      • M(C-9542) (Metal with C-9542)
      • (C-9452) (Metal with C-9452)
5. A null band is denoted by a lower case x which is the equivalent of no band. It is included in the specification as it is sometimes used in band notation (e.g x / Black - White / Red)

4.3. Combo specifications

1. For the purposes of Combo specifications, x represents any valid Band.
2. Full string x / x / x // x / x / x - x / x / x // x / x / x in which:
   1. / represents the separation between a single Band on the same Part (order: Top to Bottom).
   2. // represents the separation between two Parts (order: Tibia, Tarsus).
   3. - represents the separation between the legs (order: Left, Right).
3. Strings can be abbreviated as per the following assumptions:
   1. A single Part is assumed to be the Tarsus.
   2. A single Band with no other information is assumed to have no Leg/Part/Position.
   3. A position can be given to a Band through using -, / or //.
   4. Two Bands on a given Part are assumed to have the Positions Top and Bottom.
   5. Three Bands or more on a given Part are assumed to have the order of Positions from Top to Bottom.
4. Examples:
   1. x represents: a Band with an Undefined Part/Leg/Position
   2. x - represents: a Band on the Left Tarsus
   3. - x represents: a Band on the Right Tarsus
   4. x - x represents: a Band on the Left Tarsus; a Band on the Right Tarsus
   5. x / x represents: a Top Band on the Left Tarsus; a Bottom Band on the Left Tarsus
   6. x // represents: a Band on the Left Tibia
   7. x // - x represents: a Band on the Left Tibia; a Band on the Right Tarsus
   8. x // x / x - // x represents: a Band on the Left Tibia, a Top Band on the Left Tarsus; a Bottom Band on the Left Tarsus; a Band on the Right Tarsus

5. Putting it Together

Some examples demonstrating the use of the Format:

1. B / FO / Y - L / (M-1234)
   • Left Tarsus: Blue; Orange Flag; Yellow
   • Right Tarsus: Light Green; Metal with M-1234
2. (B-5673) // DG - W A12 on FB // R / Pu
   • Left
     • Tibia: Metal with B-5673
     • Tarsus: Dark Green
   • Right
     • Tibia: White A12 on Medium Blue Flag
     • Tarsus: Red; Purple
3. LightBlue(C-9542) - Black DEF on White
   • Left Tarsus: Light Blue with C-9542
   • Right Tarsus: Black DEF on White
4. Black Σ on Yellow
   • Undefined: Black Σ on Yellow
5. W ◊ on B -
   • Left Tarsus: White ◊ on Medium Blue
6. M(V-12345) - W ☰☰ on Br
   • Left Tarsus: Metal with V-12345
   • Right Tarsus: White ☰☰ on Brown
7. White / Red - x / Blue
   • Left Tarsus: White; Red
   • Right Tarsus: Blue

6. Technical Implementation

It is through the use of ordering, special characters and whitespace that otherwise ambiguous components can be differentiated. For example:

• Distinguishing on as a keyword and ON as a series of characters (e.g. Black ON on Green) through lack of capitals
• Distinguishing -, / or // as separators or as a character on a Band (e.g. Black / on White // Green - on Black / K Y on Y)
• Distinguishing P as Pink and PP as Pale Pink
• Distinguishing the two - characters as being a Band ID and a Leg separator (e.g. in (V-12345) - B)

The Combo shall be invalid if:

• There is more than one - as a separator character
• There is more than one // as a separator charcter per Leg (therefore, maximum of two in a Combo)