afscgap.model

   1"""
   2Definition of common library data with its structures and interfaces.
   3
   4(c) 2023 Regents of University of California / The Eric and Wendy Schmidt Center
   5for Data Science and the Environment at UC Berkeley.
   6
   7This file is part of afscgap released under the BSD 3-Clause License. See
   8LICENSE.md.
   9"""
  10from afscgap.typesdef import OPT_FLOAT
  11from afscgap.typesdef import OPT_INT
  12
  13OPT_RECORD = 'typing.Optional[Record]'
  14
  15
  16class HaulKeyable:
  17    """Interface for objects which can be associated to a specific haul.
  18
  19    Interface for objects which have enough information to be associated to a
  20    specific haul but may not be the only data associated with that haul.
  21    """
  22
  23    def get_srvy(self) -> str:
  24        """Get the field labeled as srvy in the API.
  25
  26        Returns:
  27            The name of the survey with which this data point is associated.
  28            Examples: NBS (N Bearing Sea), EBS (SE Bearing Sea), BSS (Bearing
  29            Sea Slope), or GOA (Gulf of Alaska)
  30        """
  31        raise NotImplementedError('Use implementor.')
  32
  33    def get_year(self) -> float:
  34        """Get the year in which or for which this data point was made.
  35
  36        Returns:
  37            The four digit year like 2023 with which this data point is
  38            associated.
  39        """
  40        raise NotImplementedError('Use implementor.')
  41
  42    def get_vessel_id(self) -> float:
  43        """Get the ID of the vessel with which this data point is associated.
  44
  45        Returns:
  46            Name of the vessel at the time the observation or inference was made
  47            with multiple names potentially associated with a vessel ID.
  48        """
  49        raise NotImplementedError('Use implementor.')
  50
  51    def get_cruise(self) -> float:
  52        """Get the ID of the cruise with which this data point is associated.
  53
  54        Returns:
  55            An ID uniquely identifying the cruise in which or for which this
  56            data point was made. Multiple cruises in a survey.
  57        """
  58        raise NotImplementedError('Use implementor.')
  59
  60    def get_haul(self) -> float:
  61        """Get the ID of the haul with which this data point is associated.
  62
  63        Returns:
  64            Unique ID for the haul with which this data point is associated.
  65        """
  66        raise NotImplementedError('Use implementor.')
  67
  68
  69class Record(HaulKeyable):
  70    """Interface describing a single record.
  71
  72    Interface describing a single record of an observtion. Note that, in
  73    practice, this "observation" can be a presence obervation where a species
  74    was found or an "absence" / "zero catch" observation where a sepcies was
  75    not observed in a haul.
  76    """
  77
  78    def get_year(self) -> float:
  79        """Get the field labeled as year in the API.
  80
  81        Returns:
  82            Year for the survey in which this observation was made or for which
  83            an inferred zero catch record was generated.
  84        """
  85        raise NotImplementedError('Use implementor.')
  86
  87    def get_srvy(self) -> str:
  88        """Get the field labeled as srvy in the API.
  89
  90        Returns:
  91            The name of the survey in which this observation or inference was
  92            made. NBS (N Bearing Sea), EBS (SE Bearing Sea), BSS (Bearing Sea
  93            Slope), or GOA (Gulf of Alaska)
  94        """
  95        raise NotImplementedError('Use implementor.')
  96
  97    def get_survey(self) -> str:
  98        """Get the field labeled as survey in the API.
  99
 100        Returns:
 101            Long form description of the survey in which the observation was
 102            made or for which an inferred zero catch record was made.
 103        """
 104        raise NotImplementedError('Use implementor.')
 105
 106    def get_survey_id(self) -> float:
 107        """Get the field labeled as survey_id in the API.
 108
 109        Returns:
 110            Unique numeric ID for the survey.
 111        """
 112        raise NotImplementedError('Use implementor.')
 113
 114    def get_cruise(self) -> float:
 115        """Get the field labeled as cruise in the API.
 116
 117        Returns:
 118            An ID uniquely identifying the cruise in which the observation or
 119            inferrence was made. Multiple cruises in a survey.
 120        """
 121        raise NotImplementedError('Use implementor.')
 122
 123    def get_haul(self) -> float:
 124        """Get the field labeled as haul in the API.
 125
 126        Returns:
 127            An ID uniquely identifying the haul in which this observation or
 128            inference was made. Multiple hauls per cruises.
 129        """
 130        raise NotImplementedError('Use implementor.')
 131
 132    def get_stratum(self) -> float:
 133        """Get the field labeled as stratum in the API.
 134
 135        Returns:
 136            Unique ID for statistical area / survey combination as described in
 137            the metadata or 0 if an experimental tow.
 138        """
 139        raise NotImplementedError('Use implementor.')
 140
 141    def get_station(self) -> str:
 142        """Get the field labeled as station in the API.
 143
 144        Returns:
 145            Station associated with the survey.
 146        """
 147        raise NotImplementedError('Use implementor.')
 148
 149    def get_vessel_name(self) -> str:
 150        """Get the field labeled as vessel_name in the API.
 151
 152        Returns:
 153            Unique ID describing the vessel that made this observation or
 154            inference.
 155        """
 156        raise NotImplementedError('Use implementor.')
 157
 158    def get_vessel_id(self) -> float:
 159        """Get the field labeled as vessel_id in the API.
 160
 161        Returns:
 162            Name of the vessel at the time the observation was made with
 163            multiple names potentially associated with a vessel ID. May be
 164            emulated in the case of inferred records
 165        """
 166        raise NotImplementedError('Use implementor.')
 167
 168    def get_date_time(self) -> str:
 169        """Get the field labeled as date_time in the API.
 170
 171        Returns:
 172            The date and time of the haul which has been attempted to be
 173            transformed to an ISO 8601 string without timezone info. If it
 174            couldn’t be transformed, the original string is reported.
 175        """
 176        raise NotImplementedError('Use implementor.')
 177
 178    def get_latitude(self, units: str = 'dd') -> float:
 179        """Get the field labeled as latitude_dd in the API.
 180
 181        Args:
 182            units: The units to return this value in. Only supported is dd for
 183                degrees. Deafults to dd.
 184
 185        Returns:
 186            Latitude in decimal degrees associated with the haul.
 187        """
 188        raise NotImplementedError('Use implementor.')
 189
 190    def get_longitude(self, units: str = 'dd') -> float:
 191        """Get the field labeled as longitude_dd in the API.
 192
 193        Args:
 194            units: The units to return this value in. Only supported is dd for
 195                degrees. Deafults to dd.
 196
 197        Returns:
 198            Longitude in decimal degrees associated with the haul.
 199        """
 200        raise NotImplementedError('Use implementor.')
 201
 202    def get_species_code(self) -> float:
 203        """Get the field labeled as species_code in the API.
 204
 205        Returns:
 206            Unique ID associated with the species observed or for which a zero
 207            catch record was inferred.
 208        """
 209        raise NotImplementedError('Use implementor.')
 210
 211    def get_common_name(self) -> str:
 212        """Get the field labeled as common_name in the API.
 213
 214        Returns:
 215            The “common name” associated with the species observed or for which
 216            a zero catch record was inferred. Example: Pacific glass shrimp.
 217        """
 218        raise NotImplementedError('Use implementor.')
 219
 220    def get_scientific_name(self) -> str:
 221        """Get the field labeled as scientific_name in the API.
 222
 223        Returns:
 224            The “scientific name” associated with the species observed or for
 225            which a zero catch record was inferred. Example: Pasiphaea pacifica.
 226        """
 227        raise NotImplementedError('Use implementor.')
 228
 229    def get_taxon_confidence(self) -> str:
 230        """Get the field labeled as taxon_confidence in the API.
 231
 232        Returns:
 233            Confidence flag regarding ability to identify species (High,
 234            Moderate, Low). In practice, this can also be Unassessed.
 235        """
 236        raise NotImplementedError('Use implementor.')
 237
 238    def get_cpue_weight_maybe(self, units: str = 'kg/ha') -> OPT_FLOAT:
 239        """Get a field labeled as cpue_* in the API.
 240
 241        Args:
 242            units: The desired units for the catch per unit effort. Options:
 243                kg/ha, kg/km2, kg1000/km2. Defaults to kg/ha.
 244
 245        Returns:
 246            Catch weight divided by net area (in given units) if available. See
 247            metadata. None if could not interpret as a float. If an inferred
 248            zero catch record, will be zero.
 249        """
 250        raise NotImplementedError('Use implementor.')
 251
 252    def get_cpue_count_maybe(self, units: str = 'count/ha') -> OPT_FLOAT:
 253        """Get the field labeled as cpue_* in the API.
 254
 255        Get the catch per unit effort from the record with one of the following
 256        units: kg/ha, kg/km2, kg1000/km2.
 257
 258        Args:
 259            units: The desired units for the catch per unit effort. Options:
 260                count/ha, count/km2, and count1000/km2. Defaults to count/ha.
 261
 262        Returns:
 263            Catch weight divided by net area (in given units) if available. See
 264            metadata. None if could not interpret as a float. If an inferred
 265            zero catch record, will be zero.
 266        """
 267        raise NotImplementedError('Use implementor.')
 268
 269    def get_weight_maybe(self, units: str = 'kg') -> OPT_FLOAT:
 270        """Get the field labeled as weight_kg in the API.
 271
 272        Args:
 273            units: The units in which the weight should be returned. Options are
 274                g, kg for grams and kilograms respectively. Deafults to kg.
 275
 276        Returns:
 277            Taxon weight if available. See metadata. None if could not
 278            interpret as a float. If an inferred zero catch record, will be
 279            zero.
 280        """
 281        raise NotImplementedError('Use implementor.')
 282
 283    def get_count_maybe(self) -> OPT_FLOAT:
 284        """Get the field labeled as count in the API.
 285
 286        Returns:
 287            Total number of organism individuals in haul. None if could not
 288            interpret as a float. If an inferred zero catch record, will be
 289            zero.
 290        """
 291        raise NotImplementedError('Use implementor.')
 292
 293    def get_bottom_temperature_maybe(self, units: str = 'c') -> OPT_FLOAT:
 294        """Get the field labeled as bottom_temperature_c in the API.
 295
 296        Args:
 297            units: The units in which the temperature should be returned.
 298                Options: c or f for Celcius and Fahrenheit respectively.
 299                Defaults to c.
 300
 301        Returns:
 302            Bottom temperature associated with observation / inferrence if
 303            available in desired units. None if not given or could not interpret
 304            as a float.
 305        """
 306        raise NotImplementedError('Use implementor.')
 307
 308    def get_surface_temperature_maybe(self, units: str = 'c') -> OPT_FLOAT:
 309        """Get the field labeled as surface_temperature_c in the API.
 310
 311        Args:
 312            units: The units in which the temperature should be returned.
 313                Options: c or f for Celcius and Fahrenheit respectively.
 314                Defaults to c.
 315
 316        Returns:
 317            Surface temperature associated with observation / inferrence if
 318            available. None if not given or could not interpret as a float.
 319        """
 320        raise NotImplementedError('Use implementor.')
 321
 322    def get_depth(self, units: str = 'm') -> float:
 323        """Get the field labeled as depth_m in the API.
 324
 325        Args:
 326            units: The units in which the distance should be returned. Options:
 327                m or km for meters and kilometers respectively. Defaults to m.
 328
 329        Returns:
 330            Depth of the bottom.
 331        """
 332        raise NotImplementedError('Use implementor.')
 333
 334    def get_distance_fished(self, units: str = 'm') -> float:
 335        """Get the field labeled as distance_fished_km in the API.
 336
 337        Args:
 338            units: The units in which the distance should be returned. Options:
 339                m or km for meters and kilometers respectively. Defaults to m.
 340
 341        Returns:
 342            Distance of the net fished.
 343        """
 344        raise NotImplementedError('Use implementor.')
 345
 346    def get_net_width(self, units: str = 'm') -> float:
 347        """Get the field labeled as net_width_m in the API.
 348
 349        Args:
 350            units: The units in which the distance should be returned. Options:
 351                m or km for meters and kilometers respectively. Defaults to m.
 352
 353        Returns:
 354            Distance of the net fished after asserting it is given.
 355        """
 356        raise NotImplementedError('Use implementor.')
 357
 358    def get_net_height(self, units: str = 'm') -> float:
 359        """Get the field labeled as net_height_m in the API.
 360
 361        Args:
 362            units: The units in which the distance should be returned. Options:
 363                m or km for meters and kilometers respectively. Defaults to m.
 364
 365        Returns:
 366            Height of the net fished after asserting it is given.
 367        """
 368        raise NotImplementedError('Use implementor.')
 369
 370    def get_net_width_maybe(self, units: str = 'm') -> OPT_FLOAT:
 371        """Get the field labeled as net_width_m in the API.
 372
 373        Args:
 374            units: The units in which the distance should be returned. Options:
 375                m or km for meters and kilometers respectively. Defaults to m.
 376
 377        Returns:
 378            Distance of the net fished or None if not given.
 379        """
 380        raise NotImplementedError('Use implementor.')
 381
 382    def get_net_height_maybe(self, units: str = 'm') -> OPT_FLOAT:
 383        """Get the field labeled as net_height_m in the API.
 384
 385        Args:
 386            units: The units in which the distance should be returned. Options:
 387                m or km for meters and kilometers respectively. Defaults to m.
 388
 389        Returns:
 390            Height of the net fished or None if not given.
 391        """
 392        raise NotImplementedError('Use implementor.')
 393
 394    def get_area_swept(self, units: str = 'ha') -> float:
 395        """Get the field labeled as area_swept_ha in the API.
 396
 397        Args:
 398            units: The units in which the area should be returned. Options:
 399                ha, m2, km2. Defaults to ha.
 400
 401        Returns:
 402            Area covered by the net while fishing in desired units.
 403        """
 404        raise NotImplementedError('Use implementor.')
 405
 406    def get_duration(self, units: str = 'hr') -> float:
 407        """Get the field labeled as duration_hr in the API.
 408
 409        Args:
 410            units: The units in which the duration should be returned. Options:
 411                day, hr, min. Defaults to hr.
 412
 413        Returns:
 414            Duration of the haul.
 415        """
 416        raise NotImplementedError('Use implementor.')
 417
 418    def get_tsn(self) -> int:
 419        """Get the field labeled as tsn in the API.
 420
 421        Returns:
 422            Taxonomic information system species code.
 423        """
 424        raise NotImplementedError('Use implementor.')
 425
 426    def get_tsn_maybe(self) -> OPT_INT:
 427        """Get the field labeled as tsn in the API or None.
 428
 429        Returns:
 430            Taxonomic information system species code if it could be parsed as
 431            an int and None otherwise.
 432        """
 433        raise NotImplementedError('Use implementor.')
 434
 435    def get_ak_survey_id(self) -> int:
 436        """Get the field labeled as ak_survey_id in the API.
 437
 438        Returns:
 439            AK identifier for the survey.
 440        """
 441        raise NotImplementedError('Use implementor.')
 442
 443    def get_ak_survey_id_maybe(self) -> OPT_INT:
 444        """Get the field labeled as ak_survey_id in the API.
 445
 446        Returns:
 447            AK identifier for the survey or None if not given.
 448        """
 449        raise NotImplementedError('Use implementor.')
 450
 451    def get_cpue_weight(self, units: str = 'kg/ha') -> float:
 452        """Get the value of field cpue_kgha with validity assert.
 453
 454        Args:
 455            units: The desired units for the catch per unit effort. Options:
 456                kg/ha, kg/km2, kg1000/km2. Defaults to kg/ha.
 457
 458        Raises:
 459            AssertionError: Raised if this field was not given by the API or
 460            could not be parsed as expected.
 461
 462        Returns:
 463            Catch weight divided by net area (kg / hectares) if available. See
 464            metadata. Will be zero if a zero catch record.
 465        """
 466        raise NotImplementedError('Use implementor.')
 467
 468    def get_cpue_count(self, units: str = 'count/ha') -> float:
 469        """Get the value of field cpue_noha with validity assert.
 470
 471        Args:
 472            units: The desired units for the catch per unit effort. Options:
 473                count/ha, count/km2, and count1000/km2. Defaults to count/ha.
 474
 475        Raises:
 476            AssertionError: Raised if this field was not given by the API or
 477            could not be parsed as expected.
 478
 479        Returns:
 480            Catch number divided by net sweep area if available (count /
 481            hectares). See metadata. Will be zero if a zero catch record.
 482        """
 483        raise NotImplementedError('Use implementor.')
 484
 485    def get_weight(self, units: str = 'kg') -> float:
 486        """Get the value of field weight_kg with validity assert.
 487
 488        Args:
 489            units: The units in which the weight should be returned. Options are
 490                g, kg for grams and kilograms respectively. Deafults to kg.
 491
 492        Raises:
 493            AssertionError: Raised if this field was not given by the API or
 494            could not be parsed as expected.
 495
 496        Returns:
 497            Taxon weight (kg) if available. See metadata. Will be zero if a zero
 498            catch record.
 499        """
 500        raise NotImplementedError('Use implementor.')
 501
 502    def get_count(self) -> float:
 503        """Get the value of field count with validity assert.
 504
 505        Raises:
 506            AssertionError: Raised if this field was not given by the API or
 507            could not be parsed as expected.
 508
 509        Returns:
 510            Total number of organism individuals in haul. Will be zero if a zero
 511            catch record.
 512        """
 513        raise NotImplementedError('Use implementor.')
 514
 515    def get_bottom_temperature(self, units='c') -> float:
 516        """Get the value of field bottom_temperature_c with validity assert.
 517
 518        Args:
 519            units: The units in which the temperature should be returned.
 520                Options: c or f for Celcius and Fahrenheit respectively.
 521                Defaults to c.
 522
 523        Raises:
 524            AssertionError: Raised if this field was not given by the API or
 525            could not be parsed as expected.
 526
 527        Returns:
 528            Bottom temperature associated with observation / inferrence if
 529            available.
 530        """
 531        raise NotImplementedError('Use implementor.')
 532
 533    def get_surface_temperature(self, units='c') -> float:
 534        """Get the value of field surface_temperature_c with validity assert.
 535
 536        Args:
 537            units: The units in which the temperature should be returned.
 538                Options: c or f for Celcius and Fahrenheit respectively.
 539                Defaults to c.
 540
 541        Raises:
 542            AssertionError: Raised if this field was not given by the API or
 543            could not be parsed as expected.
 544
 545        Returns:
 546            Surface temperature associated with observation / inferrence if
 547            available.
 548        """
 549        raise NotImplementedError('Use implementor.')
 550
 551    def is_complete(self) -> bool:
 552        """Determine if this record has all of its values filled in.
 553
 554        Returns:
 555            True if all optional fields have a parsed value with the expected
 556            type and false otherwise.
 557        """
 558        raise NotImplementedError('Use implementor.')
 559
 560    def to_dict(self) -> dict:
 561        """Serialize this Record to a dictionary form.
 562
 563        Serialize this Record to a dictionary form, including only field names
 564        that would be found on records returned from the API service.
 565
 566        Returns:
 567            Dictionary with field names matching those found in the API results
 568            with incomplete records having some values as None.
 569        """
 570        return {
 571            'year': self.get_year(),
 572            'srvy': self.get_srvy(),
 573            'survey': self.get_survey(),
 574            'survey_id': self.get_survey_id(),
 575            'cruise': self.get_cruise(),
 576            'haul': self.get_haul(),
 577            'stratum': self.get_stratum(),
 578            'station': self.get_station(),
 579            'vessel_name': self.get_vessel_name(),
 580            'vessel_id': self.get_vessel_id(),
 581            'date_time': self.get_date_time(),
 582            'latitude_dd': self.get_latitude(),
 583            'longitude_dd': self.get_longitude(),
 584            'species_code': self.get_species_code(),
 585            'common_name': self.get_common_name(),
 586            'scientific_name': self.get_scientific_name(),
 587            'taxon_confidence': self.get_taxon_confidence(),
 588            'cpue_kgha': self.get_cpue_weight_maybe(units='kg/ha'),
 589            'cpue_kgkm2': self.get_cpue_weight_maybe(units='kg/km2'),
 590            'cpue_kg1000km2': self.get_cpue_weight_maybe(units='kg1000/km2'),
 591            'cpue_noha': self.get_cpue_count_maybe(units='count/ha'),
 592            'cpue_nokm2': self.get_cpue_count_maybe(units='count/km2'),
 593            'cpue_no1000km2': self.get_cpue_count_maybe(units='count1000/km2'),
 594            'weight_kg': self.get_weight(units='kg'),
 595            'count': self.get_count(),
 596            'bottom_temperature_c': self.get_bottom_temperature_maybe(
 597                units='c'
 598            ),
 599            'surface_temperature_c': self.get_surface_temperature_maybe(
 600                units='c'
 601            ),
 602            'depth_m': self.get_depth(units='m'),
 603            'distance_fished_km': self.get_distance_fished(units='km'),
 604            'net_width_m': self.get_net_width(units='m'),
 605            'net_height_m': self.get_net_height(units='m'),
 606            'area_swept_ha': self.get_area_swept(units='ha'),
 607            'duration_hr': self.get_duration(units='hr'),
 608            'tsn': self.get_tsn_maybe(),
 609            'ak_survey_id': self.get_ak_survey_id()
 610        }
 611
 612
 613class Haul(HaulKeyable):
 614    """Metadata about a haul performed in a survey.
 615
 616    Metadata about a haul performed in a survey which is typically maintained
 617    for record inferrence and which does not typically leave the internals of
 618    the afscgap library.
 619    """
 620
 621    def __init__(self, srvy: str, survey: str, survey_id: float, cruise: float,
 622        haul: float, stratum: float, station: str, vessel_name: str,
 623        vessel_id: float, date_time: str, latitude_dd: float,
 624        longitude_dd: float, bottom_temperature_c: OPT_FLOAT,
 625        surface_temperature_c: OPT_FLOAT, depth_m: float,
 626        distance_fished_km: float, net_width_m: OPT_FLOAT,
 627        net_height_m: OPT_FLOAT, area_swept_ha: float, duration_hr: float):
 628        """Create a new Haul record.
 629
 630        Args:
 631            srvy: The name of the survey in which this observation was made
 632                like NBS.
 633            survey: Long form description of the survey in which the haul was
 634                made like Gulf of Alaska.
 635            survey_id: Unique numeric ID for the survey.
 636            cruise: An ID uniquely identifying the cruise in which the haul was
 637                made.
 638            haul: An ID uniquely identifying the haul.
 639            stratum: Unique ID for statistical area / survey combination as
 640                described in the metadata or 0 if an experimental tow.
 641            station: Station associated with the survey.
 642            vessel_name: Unique ID describing the vessel that made this haul.
 643                Note this is left as a string but, in practice, is likely
 644                numeric.
 645            vessel_id: ID of the vessel at the time the haul was made.
 646            date_time: The date and time of the haul which has been attempted to
 647                be transformed to an ISO 8601 string without timezone info.
 648            latitude_dd: Latitude in decimal degrees associated with the haul.
 649            longitude_dd: Longitude in decimal degrees associated with the haul.
 650            bottom_temperature_c: Bottom temperature associated with haul if
 651                available in Celsius.
 652            surface_temperature_c: Surface temperature associated with haul if
 653                available in Celsius.
 654            depth_m: Depth of the bottom in meters.
 655            distance_fished_km: Distance of the net fished as km.
 656            net_width_m: Distance of the net fished as m or None if not given.
 657            net_height_m: Height of the net fished as m or None if not given.
 658            area_swept_ha: Area covered by the net while fishing in hectares.
 659            duration_hr: Duration of the haul as number of hours.
 660        """
 661        self._srvy = srvy
 662        self._survey = survey
 663        self._survey_id = survey_id
 664        self._cruise = cruise
 665        self._haul = haul
 666        self._stratum = stratum
 667        self._station = station
 668        self._vessel_name = vessel_name
 669        self._vessel_id = vessel_id
 670        self._date_time = date_time
 671        self._latitude_dd = latitude_dd
 672        self._longitude_dd = longitude_dd
 673        self._bottom_temperature_c = bottom_temperature_c
 674        self._surface_temperature_c = surface_temperature_c
 675        self._depth_m = depth_m
 676        self._distance_fished_km = distance_fished_km
 677        self._net_width_m = net_width_m
 678        self._net_height_m = net_height_m
 679        self._area_swept_ha = area_swept_ha
 680        self._duration_hr = duration_hr
 681
 682    def get_year(self) -> float:
 683        """Get year inferred from get_date_time().
 684
 685        Returns:
 686            Year for the survey in which this observation was made.
 687        """
 688        return int(self.get_date_time().split('-')[0])
 689
 690    def get_srvy(self) -> str:
 691        """Get the field labeled as Srvy in the dataset.
 692
 693        Returns:
 694            The name of the survey in which this observation was made. NBS (N
 695            Bearing Sea), EBS (SE Bearing Sea), BSS (Bearing Sea Slope), or GOA
 696            (Gulf of Alaska)
 697        """
 698        return self._srvy
 699
 700    def get_survey(self) -> str:
 701        """Get the field labeled as Survey in the dataset.
 702
 703        Returns:
 704            Long form description of the survey in which the haul was made.
 705        """
 706        return self._survey
 707
 708    def get_survey_id(self) -> float:
 709        """Get the field labeled as Survey Id in the dataset.
 710
 711        Returns:
 712            Unique numeric ID for the survey.
 713        """
 714        return self._survey_id
 715
 716    def get_cruise(self) -> float:
 717        """Get the field labeled as Cruise in the dataset.
 718
 719        Returns:
 720            An ID uniquely identifying the cruise in which the haul was made.
 721            Multiple cruises in a survey.
 722        """
 723        return self._cruise
 724
 725    def get_haul(self) -> float:
 726        """Get the field labeled as Haul in the dataset.
 727
 728        Returns:
 729            An ID uniquely identifying the haul. Multiple hauls per cruises.
 730        """
 731        return self._haul
 732
 733    def get_stratum(self) -> float:
 734        """Get the field labeled as Stratum in the dataset.
 735
 736        Returns:
 737            Unique ID for statistical area / survey combination as described in
 738            the metadata or 0 if an experimental tow.
 739        """
 740        return self._stratum
 741
 742    def get_station(self) -> str:
 743        """Get the field labeled as Station in the dataset.
 744
 745        Returns:
 746            Station associated with the survey.
 747        """
 748        return self._station
 749
 750    def get_vessel_name(self) -> str:
 751        """Get the field labeled as Vessel Name in the dataset.
 752
 753        Returns:
 754            Unique ID describing the vessel that made this haul. Note this is
 755            left as a string but, in practice, is likely numeric.
 756        """
 757        return self._vessel_name
 758
 759    def get_vessel_id(self) -> float:
 760        """Get the field labeled as Vessel ID in the dataset.
 761
 762        Returns:
 763            ID of the vessel at the time the haul was made.
 764        """
 765        return self._vessel_id
 766
 767    def get_date_time(self) -> str:
 768        """Get the field labeled as Date Time in the dataset.
 769
 770        Returns:
 771            The date and time of the haul which has been attempted to be
 772            transformed to an ISO 8601 string without timezone info. If it
 773            couldn’t be transformed, the original string is reported.
 774        """
 775        return self._date_time
 776
 777    def get_latitude_dd(self) -> float:
 778        """Get the field labeled as Latitude Dd in the dataset.
 779
 780        Returns:
 781            Latitude in decimal degrees associated with the haul.
 782        """
 783        return self._latitude_dd
 784
 785    def get_longitude_dd(self) -> float:
 786        """Get the field labeled as Longitude Dd in the dataset.
 787
 788        Returns:
 789            Longitude in decimal degrees associated with the haul.
 790        """
 791        return self._longitude_dd
 792
 793    def get_bottom_temperature_c_maybe(self) -> OPT_FLOAT:
 794        """Get the field labeled as Bottom Temperature C in the dataset.
 795
 796        Returns:
 797            Bottom temperature associated with haul if available in
 798            Celsius. None if not given or could not interpret as a float.
 799        """
 800        return self._bottom_temperature_c
 801
 802    def get_surface_temperature_c_maybe(self) -> OPT_FLOAT:
 803        """Get the field labeled as Surface Temperature C in the dataset.
 804
 805        Returns:
 806
 807            Surface temperature associated with haul if available in
 808            Celsius. None if not given or could not interpret as a float.
 809        """
 810        return self._surface_temperature_c
 811
 812    def get_depth_m(self) -> float:
 813        """Get the field labeled as Depth N in the dataset.
 814
 815        Returns:
 816            Depth of the bottom in meters.
 817        """
 818        return self._depth_m
 819
 820    def get_distance_fished_km(self) -> float:
 821        """Get the field labeled as Distance Fished Km in the dataset.
 822
 823        Returns:
 824            Distance of the net fished as km.
 825        """
 826        return self._distance_fished_km
 827
 828    def get_net_width_m_maybe(self) -> OPT_FLOAT:
 829        """Get the field labeled as Net Width M in the dataset.
 830
 831        Returns:
 832            Distance of the net fished as m if given or None.
 833        """
 834        return self._net_width_m
 835
 836    def get_net_height_m_maybe(self) -> OPT_FLOAT:
 837        """Get the field labeled as Net Height M in the dataset.
 838
 839        Returns:
 840            Height of the net fished as m if given or None.
 841        """
 842        return self._net_height_m
 843
 844    def get_net_width_m(self) -> float:
 845        """Get the field labeled as Net Width M in the dataset.
 846
 847        Returns:
 848            Distance of the net fished as m after asserting it is given.
 849        """
 850        return assert_float_present(self._net_width_m)
 851
 852    def get_net_height_m(self) -> float:
 853        """Get the field labeled as Net Height M in the dataset.
 854
 855        Returns:
 856            Height of the net fished as m after asserting it is given.
 857        """
 858        return assert_float_present(self._net_height_m)
 859
 860    def get_area_swept_ha(self) -> float:
 861        """Get the field labeled as Area Swept Ha in the dataset.
 862
 863        Returns:
 864            Area covered by the net while fishing in hectares.
 865        """
 866        return self._area_swept_ha
 867
 868    def get_duration_hr(self) -> float:
 869        """Get the field labeled as Duration Hr in the dataset.
 870
 871        Returns:
 872            Duration of the haul as number of hours.
 873        """
 874        return self._duration_hr
 875
 876    def get_bottom_temperature_c(self) -> float:
 877        """Get the value of field Bottom Temperature C with validity assert.
 878
 879        Raises:
 880            AssertionError: Raised if this field was not given by the API or
 881            could not be parsed as expected.
 882
 883        Returns:
 884            Bottom temperature associated with haul if available in Celsius.
 885        """
 886        return assert_float_present(self._bottom_temperature_c)
 887
 888    def get_surface_temperature_c(self) -> float:
 889        """Get the value of field Surface Temperature C with validity assert.
 890
 891        Raises:
 892            AssertionError: Raised if this field was not given by the API or
 893            could not be parsed as expected.
 894
 895        Returns:
 896            Surface temperature associated with haul if available in Celsius.
 897        """
 898        return assert_float_present(self._surface_temperature_c)
 899
 900    def is_complete(self) -> bool:
 901        """Determine if this Haul has all optional fields set.
 902
 903        Returns:
 904            True if all optional fields are non-None and false otherwise.
 905        """
 906        bottom_valid = self._bottom_temperature_c is not None
 907        surface_valid = self._surface_temperature_c is not None
 908        return bottom_valid and surface_valid
 909
 910    def to_dict(self) -> dict:
 911        """Convert this object to a primitive dictionary representation.
 912
 913        Returns:
 914            Dictionary representation which may have Nones.
 915        """
 916        return {
 917            'year': self.get_year(),
 918            'srvy': self._srvy,
 919            'survey': self._survey,
 920            'survey_id': self._survey_id,
 921            'cruise': self._cruise,
 922            'haul': self._haul,
 923            'stratum': self._stratum,
 924            'station': self._station,
 925            'vessel_name': self._vessel_name,
 926            'vessel_id': self._vessel_id,
 927            'date_time': self._date_time,
 928            'latitude_dd': self._latitude_dd,
 929            'longitude_dd': self._longitude_dd,
 930            'bottom_temperature_c': self._bottom_temperature_c,
 931            'surface_temperature_c': self._surface_temperature_c,
 932            'depth_m': self._depth_m,
 933            'distance_fished_km': self._distance_fished_km,
 934            'net_width_m': self._net_width_m,
 935            'net_height_m': self._net_height_m,
 936            'area_swept_ha': self._area_swept_ha,
 937            'duration_hr': self._duration_hr
 938        }
 939
 940
 941class SpeciesRecord:
 942    """Record of a species found within a dataset.
 943
 944    Largely used for internal record keeping inside the library, this record of
 945    a species found within a dataset houses basic species metadata. Note that
 946    this is not expected to leave the internals of the library.
 947    """
 948
 949    def __init__(self, scientific_name: str, common_name: str,
 950        species_code: float, tsn: OPT_INT):
 951        """Create a new record of a species found in a datset.
 952
 953        Args:
 954            scientific_name: The “scientific name” associated with the species
 955                observed.
 956            common_name: The “common name” associated with the species observed.
 957            species_code: Unique ID associated with the species observed.
 958            tsn: Taxonomic information system species code.
 959        """
 960        self._scientific_name = scientific_name
 961        self._common_name = common_name
 962        self._species_code = species_code
 963        self._tsn = tsn
 964
 965    def get_scientific_name(self) -> str:
 966        """Get the “scientific name” associated with the species.
 967
 968        Returns:
 969            The “scientific name” associated with the species.
 970        """
 971        return self._scientific_name
 972
 973    def get_common_name(self) -> str:
 974        """Get the “common name” associated with the species observed.
 975
 976        Returns:
 977            The “common name” associated with the species observed.
 978        """
 979        return self._common_name
 980
 981    def get_species_code(self) -> float:
 982        """Get the unique ID associated with the species observed.
 983
 984        Returns:
 985            Unique ID associated with the species observed.
 986        """
 987        return self._species_code
 988
 989    def get_tsn(self) -> OPT_INT:
 990        """Get the taxonomic information system species code.
 991
 992        Returns:
 993            Taxonomic information system species code.
 994        """
 995        return self._tsn
 996
 997
 998def get_opt_float(target) -> OPT_FLOAT:
 999    """Attempt to parse a value as a float, returning None if there is an error.
1000
1001    Args:
1002        target: The value to try to interpret as a float.
1003
1004    Returns:
1005        The value of target as a float or None if there was an issue in parsing
1006        like that target is None.
1007    """
1008    if target:
1009        try:
1010            return float(target)
1011        except ValueError:
1012            return None
1013    else:
1014        return None
1015
1016
1017def get_opt_int(target) -> OPT_INT:
1018    """Attempt to parse a value as an int, returning None if there is an error.
1019
1020    Args:
1021        target: The value to try to interpret as an int.
1022
1023    Returns:
1024        The value of target as an int or None if there was an issue in parsing
1025        like that target is None.
1026    """
1027    if target:
1028        try:
1029            return int(target)
1030        except ValueError:
1031            return None
1032    else:
1033        return None
1034
1035
1036def assert_float_present(target: OPT_FLOAT) -> float:
1037    """Assert that a value is non-None before returning that value.
1038
1039    Args:
1040        target: The value to check if not None.
1041
1042    Raises:
1043        AssertionError: Raised if target is None.
1044
1045    Returns:
1046        The value of target if not None.
1047    """
1048    assert target is not None
1049    return target
1050
1051
1052def assert_int_present(target: OPT_INT) -> int:
1053    """Assert that a value is non-None before returning that value.
1054
1055    Args:
1056        target: The value to check if not None.
1057
1058    Raises:
1059        AssertionError: Raised if target is None.
1060
1061    Returns:
1062        The value of target if not None.
1063    """
1064    assert target is not None
1065    return target