afscgap.model

  1"""
  2Definition of common library data with its structures and interfaces.
  3
  4(c) 2025 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_STR
 12
 13OPT_RECORD = 'typing.Optional[Record]'
 14
 15
 16class Record:
 17    """Interface describing a single record.
 18
 19    Interface describing a single record of an observtion. Note that, in
 20    practice, this "observation" can be a presence obervation where a species
 21    was found or an "absence" / "zero catch" observation where a sepcies was
 22    not observed in a haul.
 23    """
 24
 25    def get_year(self) -> float:
 26        """Get the field labeled as year in the API.
 27
 28        Returns:
 29            Year for the survey in which this observation was made or for which
 30            an inferred zero catch record was generated.
 31        """
 32        raise NotImplementedError('Use implementor.')
 33
 34    def get_srvy(self) -> str:
 35        """Get the field labeled as srvy in the API.
 36
 37        Returns:
 38            The name of the survey in which this observation or inference was
 39            made. NBS (N Bearing Sea), EBS (SE Bearing Sea), BSS (Bearing Sea
 40            Slope), or GOA (Gulf of Alaska)
 41        """
 42        raise NotImplementedError('Use implementor.')
 43
 44    def get_survey(self) -> str:
 45        """Get the field labeled as survey in the API.
 46
 47        Returns:
 48            Long form description of the survey in which the observation was
 49            made or for which an inferred zero catch record was made.
 50        """
 51        raise NotImplementedError('Use implementor.')
 52
 53    def get_survey_id(self) -> float:
 54        """Get the field labeled as survey_id in the API.
 55
 56        Returns:
 57            Unique numeric ID for the survey.
 58        """
 59        raise NotImplementedError('Use implementor.')
 60
 61    def get_cruise(self) -> float:
 62        """Get the field labeled as cruise in the API.
 63
 64        Returns:
 65            An ID uniquely identifying the cruise in which the observation or
 66            inferrence was made. Multiple cruises in a survey.
 67        """
 68        raise NotImplementedError('Use implementor.')
 69
 70    def get_haul(self) -> float:
 71        """Get the field labeled as haul in the API.
 72
 73        Returns:
 74            An ID uniquely identifying the haul in which this observation or
 75            inference was made. Multiple hauls per cruises.
 76        """
 77        raise NotImplementedError('Use implementor.')
 78
 79    def get_stratum(self) -> float:
 80        """Get the field labeled as stratum in the API.
 81
 82        Returns:
 83            Unique ID for statistical area / survey combination as described in
 84            the metadata or 0 if an experimental tow.
 85        """
 86        raise NotImplementedError('Use implementor.')
 87
 88    def get_station(self) -> str:
 89        """Get the field labeled as station in the API.
 90
 91        Returns:
 92            Station associated with the survey.
 93        """
 94        raise NotImplementedError('Use implementor.')
 95
 96    def get_vessel_name(self) -> str:
 97        """Get the field labeled as vessel_name in the API.
 98
 99        Returns:
100            Unique ID describing the vessel that made this observation or
101            inference.
102        """
103        raise NotImplementedError('Use implementor.')
104
105    def get_vessel_id(self) -> float:
106        """Get the field labeled as vessel_id in the API.
107
108        Returns:
109            Name of the vessel at the time the observation was made with
110            multiple names potentially associated with a vessel ID. May be
111            emulated in the case of inferred records
112        """
113        raise NotImplementedError('Use implementor.')
114
115    def get_date_time(self) -> str:
116        """Get the field labeled as date_time in the API.
117
118        Returns:
119            The date and time of the haul which has been attempted to be
120            transformed to an ISO 8601 string without timezone info. If it
121            couldn’t be transformed, the original string is reported.
122        """
123        raise NotImplementedError('Use implementor.')
124
125    def get_latitude_start(self, units: str = 'dd') -> float:
126        """Get the field labeled as latitude_dd_start in the API.
127
128        Args:
129            units: The units to return this value in. Only supported is dd for
130                degrees. Deafults to dd.
131
132        Returns:
133            Latitude in decimal degrees associated with the haul.
134        """
135        raise NotImplementedError('Use implementor.')
136
137    def get_longitude_start(self, units: str = 'dd') -> float:
138        """Get the field labeled as longitude_dd_start in the API.
139
140        Args:
141            units: The units to return this value in. Only supported is dd for
142                degrees. Deafults to dd.
143
144        Returns:
145            Longitude in decimal degrees associated with the haul.
146        """
147        raise NotImplementedError('Use implementor.')
148
149    def get_latitude(self, units: str = 'dd') -> float:
150        """Get midpoint of the haul, approximating deprecated latitude_dd field in the API.
151
152        Args:
153            units: The units to return this value in. Only supported is dd for
154                degrees. Deafults to dd.
155
156        Returns:
157            Latitude in decimal degrees associated with the haul.
158        """
159        raise NotImplementedError('Use implementor.')
160
161    def get_longitude(self, units: str = 'dd') -> float:
162        """Get midpoint of the haul, approximating deprecated longitude_dd field in the API.
163
164        Args:
165            units: The units to return this value in. Only supported is dd for
166                degrees. Deafults to dd.
167
168        Returns:
169            Longitude in decimal degrees associated with the haul.
170        """
171        raise NotImplementedError('Use implementor.')
172
173    def get_latitude_end(self, units: str = 'dd') -> float:
174        """Get the field labeled as latitude_dd_end in the API.
175
176        Args:
177            units: The units to return this value in. Only supported is dd for
178                degrees. Deafults to dd.
179
180        Returns:
181            Latitude in decimal degrees associated with the haul.
182        """
183        raise NotImplementedError('Use implementor.')
184
185    def get_longitude_end(self, units: str = 'dd') -> float:
186        """Get the field labeled as longitude_dd_end in the API.
187
188        Args:
189            units: The units to return this value in. Only supported is dd for
190                degrees. Deafults to dd.
191
192        Returns:
193            Longitude in decimal degrees associated with the haul.
194        """
195        raise NotImplementedError('Use implementor.')
196
197    def get_species_code(self) -> OPT_FLOAT:
198        """Get the field labeled as species_code in the API.
199
200        Returns:
201            Unique ID associated with the species observed or for which a zero
202            catch record was inferred.
203        """
204        raise NotImplementedError('Use implementor.')
205
206    def get_common_name(self) -> OPT_STR:
207        """Get the field labeled as common_name in the API.
208
209        Returns:
210            The “common name” associated with the species observed or for which
211            a zero catch record was inferred. Example: Pacific glass shrimp.
212        """
213        raise NotImplementedError('Use implementor.')
214
215    def get_scientific_name(self) -> OPT_STR:
216        """Get the field labeled as scientific_name in the API.
217
218        Returns:
219            The “scientific name” associated with the species observed or for
220            which a zero catch record was inferred. Example: Pasiphaea pacifica.
221        """
222        raise NotImplementedError('Use implementor.')
223
224    def get_taxon_confidence(self) -> OPT_STR:
225        """Get the field labeled as taxon_confidence in the API.
226
227        Returns:
228            Confidence flag regarding ability to identify species (High,
229            Moderate, Low). In practice, this can also be Unassessed.
230        """
231        raise NotImplementedError('Use implementor.')
232
233    def get_cpue_weight_maybe(self, units: str = 'kg/ha') -> OPT_FLOAT:
234        """Get a field labeled as cpue_* in the API.
235
236        Args:
237            units: The desired units for the catch per unit effort. Options:
238                kg/ha, kg/km2, kg1000/km2. Defaults to kg/ha.
239
240        Returns:
241            Catch weight divided by net area (in given units) if available. See
242            metadata. None if could not interpret as a float. If an inferred
243            zero catch record, will be zero.
244        """
245        raise NotImplementedError('Use implementor.')
246
247    def get_cpue_count_maybe(self, units: str = 'count/ha') -> OPT_FLOAT:
248        """Get the field labeled as cpue_* in the API.
249
250        Get the catch per unit effort from the record with one of the following
251        units: kg/ha, kg/km2, kg1000/km2.
252
253        Args:
254            units: The desired units for the catch per unit effort. Options:
255                count/ha, count/km2, and count1000/km2. Defaults to count/ha.
256
257        Returns:
258            Catch weight divided by net area (in given units) if available. See
259            metadata. None if could not interpret as a float. If an inferred
260            zero catch record, will be zero.
261        """
262        raise NotImplementedError('Use implementor.')
263
264    def get_weight_maybe(self, units: str = 'kg') -> OPT_FLOAT:
265        """Get the field labeled as weight_kg in the API.
266
267        Args:
268            units: The units in which the weight should be returned. Options are
269                g, kg for grams and kilograms respectively. Deafults to kg.
270
271        Returns:
272            Taxon weight if available. See metadata. None if could not
273            interpret as a float. If an inferred zero catch record, will be
274            zero.
275        """
276        raise NotImplementedError('Use implementor.')
277
278    def get_count_maybe(self) -> OPT_FLOAT:
279        """Get the field labeled as count in the API.
280
281        Returns:
282            Total number of organism individuals in haul. None if could not
283            interpret as a float. If an inferred zero catch record, will be
284            zero.
285        """
286        raise NotImplementedError('Use implementor.')
287
288    def get_bottom_temperature_maybe(self, units: str = 'c') -> OPT_FLOAT:
289        """Get the field labeled as bottom_temperature_c in the API.
290
291        Args:
292            units: The units in which the temperature should be returned.
293                Options: c or f for Celcius and Fahrenheit respectively.
294                Defaults to c.
295
296        Returns:
297            Bottom temperature associated with observation / inferrence if
298            available in desired units. None if not given or could not interpret
299            as a float.
300        """
301        raise NotImplementedError('Use implementor.')
302
303    def get_surface_temperature_maybe(self, units: str = 'c') -> OPT_FLOAT:
304        """Get the field labeled as surface_temperature_c in the API.
305
306        Args:
307            units: The units in which the temperature should be returned.
308                Options: c or f for Celcius and Fahrenheit respectively.
309                Defaults to c.
310
311        Returns:
312            Surface temperature associated with observation / inferrence if
313            available. None if not given or could not interpret as a float.
314        """
315        raise NotImplementedError('Use implementor.')
316
317    def get_depth(self, units: str = 'm') -> float:
318        """Get the field labeled as depth_m in the API.
319
320        Args:
321            units: The units in which the distance should be returned. Options:
322                m or km for meters and kilometers respectively. Defaults to m.
323
324        Returns:
325            Depth of the bottom.
326        """
327        raise NotImplementedError('Use implementor.')
328
329    def get_distance_fished(self, units: str = 'm') -> float:
330        """Get the field labeled as distance_fished_km in the API.
331
332        Args:
333            units: The units in which the distance should be returned. Options:
334                m or km for meters and kilometers respectively. Defaults to m.
335
336        Returns:
337            Distance of the net fished.
338        """
339        raise NotImplementedError('Use implementor.')
340
341    def get_net_width(self, units: str = 'm') -> float:
342        """Get the field labeled as net_width_m in the API.
343
344        Args:
345            units: The units in which the distance should be returned. Options:
346                m or km for meters and kilometers respectively. Defaults to m.
347
348        Returns:
349            Distance of the net fished after asserting it is given.
350        """
351        raise NotImplementedError('Use implementor.')
352
353    def get_net_height(self, units: str = 'm') -> float:
354        """Get the field labeled as net_height_m in the API.
355
356        Args:
357            units: The units in which the distance should be returned. Options:
358                m or km for meters and kilometers respectively. Defaults to m.
359
360        Returns:
361            Height of the net fished after asserting it is given.
362        """
363        raise NotImplementedError('Use implementor.')
364
365    def get_net_width_maybe(self, units: str = 'm') -> OPT_FLOAT:
366        """Get the field labeled as net_width_m in the API.
367
368        Args:
369            units: The units in which the distance should be returned. Options:
370                m or km for meters and kilometers respectively. Defaults to m.
371
372        Returns:
373            Distance of the net fished or None if not given.
374        """
375        raise NotImplementedError('Use implementor.')
376
377    def get_net_height_maybe(self, units: str = 'm') -> OPT_FLOAT:
378        """Get the field labeled as net_height_m in the API.
379
380        Args:
381            units: The units in which the distance should be returned. Options:
382                m or km for meters and kilometers respectively. Defaults to m.
383
384        Returns:
385            Height of the net fished or None if not given.
386        """
387        raise NotImplementedError('Use implementor.')
388
389    def get_area_swept(self, units: str = 'ha') -> float:
390        """Get the field labeled as area_swept_ha in the API.
391
392        Args:
393            units: The units in which the area should be returned. Options:
394                ha, m2, km2. Defaults to ha.
395
396        Returns:
397            Area covered by the net while fishing in desired units.
398        """
399        raise NotImplementedError('Use implementor.')
400
401    def get_duration(self, units: str = 'hr') -> float:
402        """Get the field labeled as duration_hr in the API.
403
404        Args:
405            units: The units in which the duration should be returned. Options:
406                day, hr, min. Defaults to hr.
407
408        Returns:
409            Duration of the haul.
410        """
411        raise NotImplementedError('Use implementor.')
412
413    def get_cpue_weight(self, units: str = 'kg/ha') -> float:
414        """Get the value of field cpue_kgha with validity assert.
415
416        Args:
417            units: The desired units for the catch per unit effort. Options:
418                kg/ha, kg/km2, kg1000/km2. Defaults to kg/ha.
419
420        Raises:
421            AssertionError: Raised if this field was not given by the API or
422            could not be parsed as expected.
423
424        Returns:
425            Catch weight divided by net area (kg / hectares) if available. See
426            metadata. Will be zero if a zero catch record.
427        """
428        raise NotImplementedError('Use implementor.')
429
430    def get_cpue_count(self, units: str = 'count/ha') -> float:
431        """Get the value of field cpue_noha with validity assert.
432
433        Args:
434            units: The desired units for the catch per unit effort. Options:
435                count/ha, count/km2, and count1000/km2. Defaults to count/ha.
436
437        Raises:
438            AssertionError: Raised if this field was not given by the API or
439            could not be parsed as expected.
440
441        Returns:
442            Catch number divided by net sweep area if available (count /
443            hectares). See metadata. Will be zero if a zero catch record.
444        """
445        raise NotImplementedError('Use implementor.')
446
447    def get_weight(self, units: str = 'kg') -> float:
448        """Get the value of field weight_kg with validity assert.
449
450        Args:
451            units: The units in which the weight should be returned. Options are
452                g, kg for grams and kilograms respectively. Deafults to kg.
453
454        Raises:
455            AssertionError: Raised if this field was not given by the API or
456            could not be parsed as expected.
457
458        Returns:
459            Taxon weight (kg) if available. See metadata. Will be zero if a zero
460            catch record.
461        """
462        raise NotImplementedError('Use implementor.')
463
464    def get_count(self) -> float:
465        """Get the value of field count with validity assert.
466
467        Raises:
468            AssertionError: Raised if this field was not given by the API or
469            could not be parsed as expected.
470
471        Returns:
472            Total number of organism individuals in haul. Will be zero if a zero
473            catch record.
474        """
475        raise NotImplementedError('Use implementor.')
476
477    def get_bottom_temperature(self, units='c') -> float:
478        """Get the value of field bottom_temperature_c with validity assert.
479
480        Args:
481            units: The units in which the temperature should be returned.
482                Options: c or f for Celcius and Fahrenheit respectively.
483                Defaults to c.
484
485        Raises:
486            AssertionError: Raised if this field was not given by the API or
487            could not be parsed as expected.
488
489        Returns:
490            Bottom temperature associated with observation / inferrence if
491            available.
492        """
493        raise NotImplementedError('Use implementor.')
494
495    def get_surface_temperature(self, units='c') -> float:
496        """Get the value of field surface_temperature_c with validity assert.
497
498        Args:
499            units: The units in which the temperature should be returned.
500                Options: c or f for Celcius and Fahrenheit respectively.
501                Defaults to c.
502
503        Raises:
504            AssertionError: Raised if this field was not given by the API or
505            could not be parsed as expected.
506
507        Returns:
508            Surface temperature associated with observation / inferrence if
509            available.
510        """
511        raise NotImplementedError('Use implementor.')
512
513    def is_complete(self) -> bool:
514        """Determine if this record has all of its values filled in.
515
516        Returns:
517            True if all optional fields have a parsed value with the expected
518            type and false otherwise.
519        """
520        raise NotImplementedError('Use implementor.')
521
522    def to_dict(self) -> dict:
523        """Serialize this Record to a dictionary form.
524
525        Serialize this Record to a dictionary form, including only field names
526        that would be found on records returned from the API service.
527
528        Returns:
529            Dictionary with field names matching those found in the API results
530            with incomplete records having some values as None.
531        """
532        return {
533            'year': self.get_year(),
534            'srvy': self.get_srvy(),
535            'survey': self.get_survey(),
536            'survey_id': self.get_survey_id(),
537            'cruise': self.get_cruise(),
538            'haul': self.get_haul(),
539            'stratum': self.get_stratum(),
540            'station': self.get_station(),
541            'vessel_name': self.get_vessel_name(),
542            'vessel_id': self.get_vessel_id(),
543            'date_time': self.get_date_time(),
544            'latitude_dd': self.get_latitude(),
545            'longitude_dd': self.get_longitude(),
546            'species_code': self.get_species_code(),
547            'common_name': self.get_common_name(),
548            'scientific_name': self.get_scientific_name(),
549            'taxon_confidence': self.get_taxon_confidence(),
550            'cpue_kgha': self.get_cpue_weight_maybe(units='kg/ha'),
551            'cpue_kgkm2': self.get_cpue_weight_maybe(units='kg/km2'),
552            'cpue_kg1000km2': self.get_cpue_weight_maybe(units='kg1000/km2'),
553            'cpue_noha': self.get_cpue_count_maybe(units='count/ha'),
554            'cpue_nokm2': self.get_cpue_count_maybe(units='count/km2'),
555            'cpue_no1000km2': self.get_cpue_count_maybe(units='count1000/km2'),
556            'weight_kg': self.get_weight(units='kg'),
557            'count': self.get_count(),
558            'bottom_temperature_c': self.get_bottom_temperature_maybe(
559                units='c'
560            ),
561            'surface_temperature_c': self.get_surface_temperature_maybe(
562                units='c'
563            ),
564            'depth_m': self.get_depth(units='m'),
565            'distance_fished_km': self.get_distance_fished(units='km'),
566            'net_width_m': self.get_net_width(units='m'),
567            'net_height_m': self.get_net_height(units='m'),
568            'area_swept_ha': self.get_area_swept(units='ha'),
569            'duration_hr': self.get_duration(units='hr')
570        }