sample.yml

title: Sample
description: >
  Information about a sampling event during a campaign.
  Use separate sample records for different dates, platform sides, methodologies, or observers 
  recording concurrent but independent data streams.
fields:
  - name: RecordType
    description: >
      Record type.
      Use `ES` for sample records.
    type: string
    constraints:
      required: true
      pattern: 'ES'

  - name: CampaignID
    description: >
      Identifier of the campaign the sample belongs to.
    type: string
    constraints:
      required: true
      maxLength: 50

  - name: SampleID
    description: >
      Identifier of the sample.
      Must be unique within the campaign.
    type: string
    constraints:
      required: true
      unique: true
      maxLength: 50

  - name: Date
    description: >
      Sampling date, formatted as `YYYY-MM-DD`.
    type: date
    constraints:
      required: true

  - name: PlatformCode
    description: >
      Platform from which sampling took place.
      Use `ZZ99` for unknown.
    type: string
    vocabulary:
      text: SHIPC
      href: https://vocab.ices.dk/?ref=315
    constraints:
      required: true

  - name: PlatformClass
    description: |
      Type of the platform.

      - `30` [Ship](https://vocab.ices.dk/?CodeID=120897)
      - `62` [Aeroplane](https://vocab.ices.dk/?CodeID=137773)
      - `67` [Helicopter](https://vocab.ices.dk/?CodeID=120899)
    type: string
    vocabulary:
      text: Platform Class
      href: https://vocab.ices.dk/?ref=311
    constraints:
      required: true
      enum:
        - '30' # Previously: 1
        - '62' # Previously: 3 and 4
        - '67' # Previously: 2

  - name: PlatformSide
    description: |
      Side of the platform from which sampling took place.

      - `right` Starboard
      - `right_front`
      - `right_back`
      - `left` Port
      - `left_front`
      - `left_back`
      - `both` Observers on both sides producing one collective data stream
    type: string
    vocabulary:
      text: PlatformSide
      href: http://vocab.ices.dk/?ref=1688
    constraints:
      required: false
      enum:
        - right       # Previously: 6
        - right_front # Previously: 1
        - right_back  # Previously: 3
        - left        # Previously: 5
        - left_front  # Previously: 4
        - left_back   # Previously: 2
        - both        # Previously: 9

  - name: PlatformHeight
    description: >
      Height (in m) of the platform during sampling (e.g. average flying height of airplane).
    type: number
    constraints:
      required: false

  - name: TransectWidth
    description: >
      Width (in m) of the sampling transect.
    type: integer
    constraints:
      required: true
 
  - name: SamplingMethod
    description: |
      Sampling method.

      - `1` Ship-based transect method with distance estimation and snapshot for flying birds
      - `2` Ship-based transect method with distance estimation, no snapshot for flying birds
      - `3` All observations, but no transect operated
      - `4` Presence/absence data only
      - `5` Ship-based transect method with distance estimation and snapshot for flying birds, but no scan data for outside the transect
      - `6` Ship-based strip transect, no snapshot, no distance estimation
      - `7` Ship-based strip transect, with snapshot, no distance estimation
      - `8` Visual aerial line transect method with distance sampling
      - `9` Visual aerial strip transect, no distance estimation
      - `10` Visual aerial total counts
      - `11` Digital aerial - video
      - `12` Digital aerial - stills
    type: string
    vocabulary:
      text: BD_CountMethod
      href: http://vocab.ices.dk/?ref=1440
    constraints:
      required: true
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
        - '7'
        - '8'
        - '9'
        - '10'
        - '11'
        - '12'

  - name: PrimarySampling
    description: >
      Whether the sample should be considered primary (`True`) or ancillary (`False`) in the case 
      of observers recording concurrent but independent data streams.
    type: boolean
    vocabulary:
      text: Boolean
      href: http://vocab.ices.dk/?ref=1690
    constraints:
      required: false

  - name: TargetTaxa
    description: |
      Species (groups) that were counted during sampling.

      - `1` All species recorded (standard)
      - `2` All species except Larus gulls
      - `3` All species except fulmars
      - `4` All species except Larus gulls, fulmars and kittiwakes
      - `5` Auks only
      - `6` Auks and seaduck only
      - `7` All species except eiders and gulls
      - `8` All species except gannets
      - `9` Auks and unusual seabirds only
      - `10` All species except auks and divers
      - `11` All species except small gulls (Little, Black-headed & Common Gull/Black-legged Kittiwake)
      - `12` All species except Lesser Black-backed Gulls
      - `13` All species except seaduck and divers
      - `14` All species except gannets, fulmars and kittiwakes
      - `15` All species except fulmars and gannets
      - `16` Cetaceans only
      - `17` Auks, divers, grebes and seaduck only
      - `18` Cetaceans and rare birds only
      - `99` Other
    type: string
    vocabulary:
      text: TargetTaxa
      href: http://vocab.ices.dk/?ref=1713
    constraints:
      required: true
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
        - '7'
        - '8'
        - '9'
        - '10'
        - '11'
        - '12'
        - '13'
        - '14'
        - '15'
        - '16'
        - '17'
        - '18'
        - '99'

  - name: DistanceBins
    description: >
      List of distance bin boundaries applied during sampling and to be used for distance analyses, 
      formatted as `x|x|...|x`.
      For a typical ship-based sample using a 300 m wide transect this would be `0|50|100|200|300`.
    type: string
    constraints:
      required: false
      maxLength: 100
      pattern: '(\d+\|)+\d+'

  - name: UseOfBinoculars
    description: |
      Extent to which binoculars were used during sampling.
      
      - `1` No binoculars used
      - `2` Binoculars used for scanning far ahead of the platform (e.g. for seaduck and diver monitoring)
      - `3` Binoculars used extensively for scanning ahead and to the side, naked eye used for close observations (e.g. for cetacean monitoring)
    type: string
    vocabulary:
      text: UseOfBinoculars
      href: http://vocab.ices.dk/?ref=1719
    constraints:
      required: false
      enum:
        - '1'
        - '2'
        - '3'

  - name: NumberOfObservers
    description: >
      Number of observers that contributed to the sample.
    type: integer
    constraints:
      required: false

  - name: Notes
    description: >
      Additional details about the sample, such as the name of the ship in case it has no `SHIPC` 
      code.
    type: string
    constraints:
      required: false
      maxLength: 300

missingValues:
  - ''
  - NA
primaryKey: SampleID
foreignKeys:
  - fields: CampaignID
    reference:
      resource: campaigns
      fields: CampaignID