afscgap

   1"""Library which allows for Pythonic access to the interacting with AFSC GAP.
   2
   3This library supports Pythonic utilization of the Ground Fish Assessment Program (GAP) datasets
   4produced by the Resource Assessment and Conservation Engineering (RACE) Division of the Alaska
   5Fisheries Science Center (AFSC) as part of the National Oceanic and Atmospheric Administration
   6(NOAA Fisheries). Note that this is a community-provided library and is not officially endorsed by
   7NOAA.
   8
   9(c) 2024 Regents of University of California / The Eric and Wendy Schmidt Center
  10for Data Science and the Environment at UC Berkeley.
  11
  12This file is part of afscgap released under the BSD 3-Clause License. See
  13LICENSE.md.
  14"""
  15import typing
  16
  17import afscgap.cursor
  18import afscgap.flat
  19import afscgap.param
  20
  21from afscgap.typesdef import OPT_FLOAT
  22from afscgap.typesdef import INT_PARAM
  23from afscgap.typesdef import STR_PARAM
  24from afscgap.typesdef import OPT_INT
  25from afscgap.typesdef import OPT_STR
  26from afscgap.typesdef import OPT_REQUESTOR
  27
  28WARN_FUNCTION = typing.Optional[typing.Callable[[str], None]]
  29
  30DEFAULT_URL = 'https://data.pyafscgap.org'
  31
  32
  33class Query:
  34    """Entrypoint for the AFSC GAP Python library.
  35
  36    Facade for executing queries against AFSC GAP and builder to create those
  37    queries.
  38    """
  39
  40    def __init__(self, base_url: OPT_STR = None, requestor: OPT_REQUESTOR = None):
  41        """Create a new Query.
  42
  43        Args:
  44            base_url: The URL at which the flat files can be found. If None, will use
  45                default. See afscgap.DEFAULT_URL.
  46            requestor: Strategy to use for making HTTP requests. If None, will
  47                use a default as defined by afscgap.client.Cursor.
  48        """
  49        # URLs for data
  50        self._base_url = base_url
  51        self._requestor = requestor
  52
  53        # Filter parameters
  54        self._year: afscgap.param.Param = afscgap.param.EmptyParam()
  55        self._srvy: afscgap.param.Param = afscgap.param.EmptyParam()
  56        self._survey: afscgap.param.Param = afscgap.param.EmptyParam()
  57        self._survey_id: afscgap.param.Param = afscgap.param.EmptyParam()
  58        self._cruise: afscgap.param.Param = afscgap.param.EmptyParam()
  59        self._haul: afscgap.param.Param = afscgap.param.EmptyParam()
  60        self._stratum: afscgap.param.Param = afscgap.param.EmptyParam()
  61        self._station: afscgap.param.Param = afscgap.param.EmptyParam()
  62        self._vessel_name: afscgap.param.Param = afscgap.param.EmptyParam()
  63        self._vessel_id: afscgap.param.Param = afscgap.param.EmptyParam()
  64        self._date_time: afscgap.param.Param = afscgap.param.EmptyParam()
  65        self._latitude_dd: afscgap.param.Param = afscgap.param.EmptyParam()
  66        self._longitude_dd: afscgap.param.Param = afscgap.param.EmptyParam()
  67        self._species_code: afscgap.param.Param = afscgap.param.EmptyParam()
  68        self._common_name: afscgap.param.Param = afscgap.param.EmptyParam()
  69        self._scientific_name: afscgap.param.Param = afscgap.param.EmptyParam()
  70        self._taxon_confidence: afscgap.param.Param = afscgap.param.EmptyParam()
  71        self._cpue_kgha: afscgap.param.Param = afscgap.param.EmptyParam()
  72        self._cpue_kgkm2: afscgap.param.Param = afscgap.param.EmptyParam()
  73        self._cpue_kg1000km2: afscgap.param.Param = afscgap.param.EmptyParam()
  74        self._cpue_noha: afscgap.param.Param = afscgap.param.EmptyParam()
  75        self._cpue_nokm2: afscgap.param.Param = afscgap.param.EmptyParam()
  76        self._cpue_no1000km2: afscgap.param.Param = afscgap.param.EmptyParam()
  77        self._weight_kg: afscgap.param.Param = afscgap.param.EmptyParam()
  78        self._count: afscgap.param.Param = afscgap.param.EmptyParam()
  79        self._bottom_temperature_c: afscgap.param.Param = afscgap.param.EmptyParam()
  80        self._surface_temperature_c: afscgap.param.Param = afscgap.param.EmptyParam()
  81        self._depth_m: afscgap.param.Param = afscgap.param.EmptyParam()
  82        self._distance_fished_km: afscgap.param.Param = afscgap.param.EmptyParam()
  83        self._net_width_m: afscgap.param.Param = afscgap.param.EmptyParam()
  84        self._net_height_m: afscgap.param.Param = afscgap.param.EmptyParam()
  85        self._area_swept_ha: afscgap.param.Param = afscgap.param.EmptyParam()
  86        self._duration_hr: afscgap.param.Param = afscgap.param.EmptyParam()
  87
  88        # Query pararmeters
  89        self._limit: OPT_INT = None
  90        self._filter_incomplete: bool = False
  91        self._presence_only: bool = False
  92        self._suppress_large_warning: bool = False
  93        self._warn_function: WARN_FUNCTION = None
  94
  95    def filter_year(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
  96        max_val: OPT_FLOAT = None) -> 'Query':
  97        """Filter on year for the survey in which this observation was made.
  98
  99        Filter on year for the survey in which this observation was made,
 100        ovewritting all prior year filters on this Query if one was previously
 101        set.
 102
 103        Args:
 104            eq: The exact value that must be matched for a record to be
 105                returned. Pass None if no equality filter should be applied.
 106                Error thrown if min_val or max_val also provided.
 107            min_val: The minimum allowed value, inclusive. Pass None if no
 108                minimum value filter should be applied. Defaults to None. Error
 109                thrown if eq also proivded.
 110            max_val: The maximum allowed value, inclusive. Pass None if no
 111                maximum value filter should be applied. Defaults to None. Error
 112                thrown if eq also proivded.
 113
 114        Returns:
 115            This object for chaining if desired.
 116        """
 117        self._year = self._create_float_param(eq, min_val, max_val)
 118        return self
 119
 120    def filter_srvy(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
 121        max_val: OPT_STR = None) -> 'Query':
 122        """Filter on haul survey short name.
 123
 124        Filter on the short name of the survey in which this observation was
 125        made. Pass None if no filter should be applied. Defaults to None. Note
 126        that common values include: NBS (N Bearing Sea), EBS (SE Bearing Sea),
 127        BSS (Bearing Sea Slope), GOA (Gulf of Alaska), and AI (Aleutian
 128        Islands). Overwrites all prior srvy filters if set on this Query.
 129
 130        Args:
 131            eq: The exact value that must be matched for a record to be
 132                returned. Pass None if no equality filter should be applied.
 133                Error thrown if min_val or max_val also provided.
 134            min_val: The minimum allowed value, inclusive. Pass None if no
 135                minimum value filter should be applied. Defaults to None. Error
 136                thrown if eq also proivded.
 137            max_val: The maximum allowed value, inclusive. Pass None if no
 138                maximum value filter should be applied. Defaults to None. Error
 139                thrown if eq also proivded.
 140
 141        Returns:
 142            This object for chaining if desired.
 143        """
 144        self._srvy = self._create_str_param(eq, min_val, max_val)
 145        return self
 146
 147    def filter_survey(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
 148        max_val: OPT_STR = None) -> 'Query':
 149        """Filter on survey long name.
 150
 151        Filter on long form description of the survey in which the observation
 152        was made. Overwrites all prior survey filters if set on this Query.
 153
 154        Args:
 155            eq: The exact value that must be matched for a record to be
 156                returned. Pass None if no equality filter should be applied.
 157                Error thrown if min_val or max_val also provided.
 158            min_val: The minimum allowed value, inclusive. Pass None if no
 159                minimum value filter should be applied. Defaults to None. Error
 160                thrown if eq also proivded.
 161            max_val: The maximum allowed value, inclusive. Pass None if no
 162                maximum value filter should be applied. Defaults to None. Error
 163                thrown if eq also proivded.
 164
 165        Returns:
 166            This object for chaining if desired.
 167        """
 168        self._survey = self._create_str_param(eq, min_val, max_val)
 169        return self
 170
 171    def filter_survey_id(self, eq: OPT_FLOAT = None,
 172        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None) -> 'Query':
 173        """Filter on unique numeric ID for the survey.
 174
 175        Filter on unique numeric ID for the survey, overwritting prior survey ID
 176        filters if set on this Query.
 177
 178        Args:
 179            eq: The exact value that must be matched for a record to be
 180                returned. Pass None if no equality filter should be applied.
 181                Error thrown if min_val or max_val also provided.
 182            min_val: The minimum allowed value, inclusive. Pass None if no
 183                minimum value filter should be applied. Defaults to None. Error
 184                thrown if eq also proivded.
 185            max_val: The maximum allowed value, inclusive. Pass None if no
 186                maximum value filter should be applied. Defaults to None. Error
 187                thrown if eq also proivded.
 188
 189        Returns:
 190            This object for chaining if desired.
 191        """
 192        self._survey_id = self._create_float_param(eq, min_val, max_val)
 193        return self
 194
 195    def filter_cruise(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
 196        max_val: OPT_FLOAT = None) -> 'Query':
 197        """Filter on cruise ID.
 198
 199        Filter on an ID uniquely identifying the cruise in which the observation
 200        was made. Overwrites all prior cruise filters on this Query.
 201
 202        Args:
 203            eq: The exact value that must be matched for a record to be
 204                returned. Pass None if no equality filter should be applied.
 205                Error thrown if min_val or max_val also provided.
 206            min_val: The minimum allowed value, inclusive. Pass None if no
 207                minimum value filter should be applied. Defaults to None. Error
 208                thrown if eq also proivded.
 209            max_val: The maximum allowed value, inclusive. Pass None if no
 210                maximum value filter should be applied. Defaults to None. Error
 211                thrown if eq also proivded.
 212
 213        Returns:
 214            This object for chaining if desired.
 215        """
 216        self._cruise = self._create_float_param(eq, min_val, max_val)
 217        return self
 218
 219    def filter_haul(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
 220        max_val: OPT_FLOAT = None) -> 'Query':
 221        """Filter on haul identifier.
 222
 223        Filter on an ID uniquely identifying the haul in which this observation
 224        was made. Overwrites all prior haul filters on this Query.
 225
 226        Args:
 227            eq: The exact value that must be matched for a record to be
 228                returned. Pass None if no equality filter should be applied.
 229                Error thrown if min_val or max_val also provided.
 230            min_val: The minimum allowed value, inclusive. Pass None if no
 231                minimum value filter should be applied. Defaults to None. Error
 232                thrown if eq also proivded.
 233            max_val: The maximum allowed value, inclusive. Pass None if no
 234                maximum value filter should be applied. Defaults to None. Error
 235                thrown if eq also proivded.
 236
 237        Returns:
 238            This object for chaining if desired.
 239        """
 240        self._haul = self._create_float_param(eq, min_val, max_val)
 241        return self
 242
 243    def filter_stratum(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
 244        max_val: OPT_FLOAT = None) -> 'Query':
 245        """Filter on unique ID for statistical area / survey combination.
 246
 247        Filter on unique ID for statistical area / survey combination,
 248        overwritting all prior stratum filters on Query.
 249
 250        Args:
 251            eq: The exact value that must be matched for a record to be
 252                returned. Pass None if no equality filter should be applied.
 253                Error thrown if min_val or max_val also provided.
 254            min_val: The minimum allowed value, inclusive. Pass None if no
 255                minimum value filter should be applied. Defaults to None. Error
 256                thrown if eq also proivded.
 257            max_val: The maximum allowed value, inclusive. Pass None if no
 258                maximum value filter should be applied. Defaults to None. Error
 259                thrown if eq also proivded.
 260
 261        Returns:
 262            This object for chaining if desired.
 263        """
 264        self._stratum = self._create_float_param(eq, min_val, max_val)
 265        return self
 266
 267    def filter_station(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
 268        max_val: OPT_STR = None) -> 'Query':
 269        """Filter on station associated with the survey.
 270
 271        Filter on station associated with the survey, overwritting all prior
 272        station filters on this Query.
 273
 274        Args:
 275            eq: The exact value that must be matched for a record to be
 276                returned. Pass None if no equality filter should be applied.
 277                Error thrown if min_val or max_val also provided.
 278            min_val: The minimum allowed value, inclusive. Pass None if no
 279                minimum value filter should be applied. Defaults to None. Error
 280                thrown if eq also proivded.
 281            max_val: The maximum allowed value, inclusive. Pass None if no
 282                maximum value filter should be applied. Defaults to None. Error
 283                thrown if eq also proivded.
 284
 285        Returns:
 286            This object for chaining if desired.
 287        """
 288        self._station = self._create_str_param(eq, min_val, max_val)
 289        return self
 290
 291    def filter_vessel_name(self, eq: STR_PARAM = None,
 292        min_val: OPT_STR = None, max_val: OPT_STR = None) -> 'Query':
 293        """Filter on unique ID describing the vessel that made this observation.
 294
 295        Filter on unique ID describing the vessel that made this observation,
 296        overwritting all prior vessel name filters on this Query.
 297
 298        Args:
 299            eq: The exact value that must be matched for a record to be
 300                returned. Pass None if no equality filter should be applied.
 301                Error thrown if min_val or max_val also provided.
 302            min_val: The minimum allowed value, inclusive. Pass None if no
 303                minimum value filter should be applied. Defaults to None. Error
 304                thrown if eq also proivded.
 305            max_val: The maximum allowed value, inclusive. Pass None if no
 306                maximum value filter should be applied. Defaults to None. Error
 307                thrown if eq also proivded.
 308
 309        Returns:
 310            This object for chaining if desired.
 311        """
 312        self._vessel_name = self._create_str_param(eq, min_val, max_val)
 313        return self
 314
 315    def filter_vessel_id(self, eq: OPT_FLOAT = None,
 316        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None) -> 'Query':
 317        """Filter on name of the vessel at the time the observation was made.
 318
 319        Filter on name of the vessel at the time the observation was made,
 320        overwritting all prior vessel ID filters on this Query.
 321
 322        Args:
 323            eq: The exact value that must be matched for a record to be
 324                returned. Pass None if no equality filter should be applied.
 325                Error thrown if min_val or max_val also provided.
 326            min_val: The minimum allowed value, inclusive. Pass None if no
 327                minimum value filter should be applied. Defaults to None. Error
 328                thrown if eq also proivded.
 329            max_val: The maximum allowed value, inclusive. Pass None if no
 330                maximum value filter should be applied. Defaults to None. Error
 331                thrown if eq also proivded.
 332
 333        Returns:
 334            This object for chaining if desired.
 335        """
 336        self._vessel_id = self._create_float_param(eq, min_val, max_val)
 337        return self
 338
 339    def filter_date_time(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
 340        max_val: OPT_STR = None) -> 'Query':
 341        """Filter on the date and time of the haul.
 342
 343        Filter on the date and time of the haul as an ISO 8601 string. If given
 344        an ISO 8601 string, will afscgap.convert from ISO 8601 to the API
 345        datetime string format. Similarly, if given a dictionary, all values
 346        matching an ISO 8601 string will be afscgap.converted to the API
 347        datetime string format. Overwrites all prior date time filters on
 348        this Query.
 349
 350        Args:
 351            eq: The exact value that must be matched for a record to be
 352                returned. Pass None if no equality filter should be applied.
 353                Error thrown if min_val or max_val also provided.
 354            min_val: The minimum allowed value, inclusive. Pass None if no
 355                minimum value filter should be applied. Defaults to None. Error
 356                thrown if eq also proivded.
 357            max_val: The maximum allowed value, inclusive. Pass None if no
 358                maximum value filter should be applied. Defaults to None. Error
 359                thrown if eq also proivded.
 360
 361        Returns:
 362            This object for chaining if desired.
 363        """
 364        self._date_time = self._create_str_param(eq, min_val, max_val)
 365        return self
 366
 367    def filter_latitude(self, eq: OPT_FLOAT = None,
 368        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 369        units: str = 'dd') -> 'Query':
 370        """Filter on latitude in decimal degrees associated with the haul.
 371
 372        Filter on latitude in decimal degrees associated with the haul,
 373        overwritting all prior latitude filters on this Query.
 374
 375        Args:
 376            eq: The exact value that must be matched for a record to be
 377                returned. Pass None if no equality filter should be applied.
 378                Error thrown if min_val or max_val also provided.
 379            min_val: The minimum allowed value, inclusive. Pass None if no
 380                minimum value filter should be applied. Defaults to None. Error
 381                thrown if eq also proivded.
 382            max_val: The maximum allowed value, inclusive. Pass None if no
 383                maximum value filter should be applied. Defaults to None. Error
 384                thrown if eq also proivded.
 385            units: The units in which the filter values are provided. Currently
 386                only dd supported.
 387
 388        Returns:
 389            This object for chaining if desired.
 390        """
 391        self._latitude_dd = self._create_float_param(
 392            afscgap.convert.convert(eq, units, 'dd'),
 393            afscgap.convert.convert(min_val, units, 'dd'),
 394            afscgap.convert.convert(max_val, units, 'dd')
 395        )
 396        return self
 397
 398    def filter_longitude(self, eq: OPT_FLOAT = None,
 399        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 400        units: str = 'dd') -> 'Query':
 401        """Filter on longitude in decimal degrees associated with the haul.
 402
 403        Filter on longitude in decimal degrees associated with the haul,
 404        overwritting all prior longitude filters on this Query.
 405
 406        Args:
 407            eq: The exact value that must be matched for a record to be
 408                returned. Pass None if no equality filter should be applied.
 409                Error thrown if min_val or max_val also provided.
 410            min_val: The minimum allowed value, inclusive. Pass None if no
 411                minimum value filter should be applied. Defaults to None. Error
 412                thrown if eq also proivded.
 413            max_val: The maximum allowed value, inclusive. Pass None if no
 414                maximum value filter should be applied. Defaults to None. Error
 415                thrown if eq also proivded.
 416            units: The units in which the filter values are provided. Currently
 417                only dd supported.
 418
 419        Returns:
 420            This object for chaining if desired.
 421        """
 422        self._longitude_dd = self._create_float_param(
 423            afscgap.convert.convert(eq, units, 'dd'),
 424            afscgap.convert.convert(min_val, units, 'dd'),
 425            afscgap.convert.convert(max_val, units, 'dd')
 426        )
 427        return self
 428
 429    def filter_species_code(self, eq: OPT_FLOAT = None,
 430        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None) -> 'Query':
 431        """Filter on unique ID associated with the species observed.
 432
 433        Filter on unique ID associated with the species observed, overwritting
 434        all prior species code filters on this Query.
 435
 436        Args:
 437            eq: The exact value that must be matched for a record to be
 438                returned. Pass None if no equality filter should be applied.
 439                Error thrown if min_val or max_val also provided.
 440            min_val: The minimum allowed value, inclusive. Pass None if no
 441                minimum value filter should be applied. Defaults to None. Error
 442                thrown if eq also proivded.
 443            max_val: The maximum allowed value, inclusive. Pass None if no
 444                maximum value filter should be applied. Defaults to None. Error
 445                thrown if eq also proivded.
 446
 447        Returns:
 448            This object for chaining if desired.
 449        """
 450        self._species_code = self._create_float_param(eq, min_val, max_val)
 451        return self
 452
 453    def filter_common_name(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
 454        max_val: OPT_STR = None) -> 'Query':
 455        """Filter on the "common name" associated with the species observed.
 456
 457        Filter on the "common name" associated with the species observed,
 458        overwritting all prior common name filters on this Query.
 459
 460        Args:
 461            eq: The exact value that must be matched for a record to be
 462                returned. Pass None if no equality filter should be applied.
 463                Error thrown if min_val or max_val also provided.
 464            min_val: The minimum allowed value, inclusive. Pass None if no
 465                minimum value filter should be applied. Defaults to None. Error
 466                thrown if eq also proivded.
 467            max_val: The maximum allowed value, inclusive. Pass None if no
 468                maximum value filter should be applied. Defaults to None. Error
 469                thrown if eq also proivded.
 470
 471        Returns:
 472            This object for chaining if desired.
 473        """
 474        self._common_name = self._create_str_param(eq, min_val, max_val)
 475        return self
 476
 477    def filter_scientific_name(self, eq: STR_PARAM = None,
 478        min_val: OPT_STR = None, max_val: OPT_STR = None) -> 'Query':
 479        """Filter on the "scientific name" associated with the species observed.
 480
 481        Filter on the "scientific name" associated with the species observed,
 482        overwritting all prior scientific name filters on this Query.
 483
 484        Args:
 485            eq: The exact value that must be matched for a record to be
 486                returned. Pass None if no equality filter should be applied.
 487                Error thrown if min_val or max_val also provided.
 488            min_val: The minimum allowed value, inclusive. Pass None if no
 489                minimum value filter should be applied. Defaults to None. Error
 490                thrown if eq also proivded.
 491            max_val: The maximum allowed value, inclusive. Pass None if no
 492                maximum value filter should be applied. Defaults to None. Error
 493                thrown if eq also proivded.
 494
 495        Returns:
 496            This object for chaining if desired.
 497        """
 498        self._scientific_name = self._create_str_param(eq, min_val, max_val)
 499        return self
 500
 501    def filter_taxon_confidence(self, eq: STR_PARAM = None,
 502        min_val: OPT_STR = None, max_val: OPT_STR = None) -> 'Query':
 503        """Filter on confidence flag regarding ability to identify species.
 504
 505        Filter on confidence flag regarding ability to identify species,
 506        overwritting all taxon confidence filters on this Query.
 507
 508        Args:
 509            eq: The exact value that must be matched for a record to be
 510                returned. Pass None if no equality filter should be applied.
 511                Error thrown if min_val or max_val also provided.
 512            min_val: The minimum allowed value, inclusive. Pass None if no
 513                minimum value filter should be applied. Defaults to None. Error
 514                thrown if eq also proivded.
 515            max_val: The maximum allowed value, inclusive. Pass None if no
 516                maximum value filter should be applied. Defaults to None. Error
 517                thrown if eq also proivded.
 518
 519        Returns:
 520            This object for chaining if desired.
 521        """
 522        self._taxon_confidence = self._create_str_param(eq, min_val, max_val)
 523        return self
 524
 525    def filter_cpue_weight(self, eq: OPT_FLOAT = None,
 526        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 527        units: str = 'kg/ha') -> 'Query':
 528        """Filter on catch per unit effort.
 529
 530        Filter on catch per unit effort as weight divided by net area if
 531        available. Overwrites all prior CPUE weight filters applied to this
 532        Query.
 533
 534        Args:
 535            eq: The exact value that must be matched for a record to be
 536                returned. Pass None if no equality filter should be applied.
 537                Error thrown if min_val or max_val also provided.
 538            min_val: The minimum allowed value, inclusive. Pass None if no
 539                minimum value filter should be applied. Defaults to None. Error
 540                thrown if eq also proivded.
 541            max_val: The maximum allowed value, inclusive. Pass None if no
 542                maximum value filter should be applied. Defaults to None. Error
 543                thrown if eq also proivded.
 544            units: The units for the catch per unit effort provided. Options:
 545                kg/ha, kg/km2, kg1000/km2. Defaults to kg/ha.
 546
 547        Returns:
 548            This object for chaining if desired.
 549        """
 550        param = self._create_float_param(eq, min_val, max_val)
 551
 552        self._cpue_kgha = afscgap.param.EmptyParam()
 553        self._cpue_kgkm2 = afscgap.param.EmptyParam()
 554        self._cpue_kg1000km2 = afscgap.param.EmptyParam()
 555
 556        if units == 'kg/ha':
 557            self._cpue_kgha = param
 558        elif units == 'kg/km2':
 559            self._cpue_kgkm2 = param
 560        elif units == 'kg1000/km2':
 561            self._cpue_kg1000km2 = param
 562        else:
 563            raise RuntimeError('Unrecognized units ' + units)
 564
 565        return self
 566
 567    def filter_cpue_count(self, eq: OPT_FLOAT = None,
 568        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 569        units: str = 'count/ha') -> 'Query':
 570        """Filter catch per unit effort as count over area in hectares.
 571
 572        Filter on catch number divided by net sweep area if available (count /
 573        hectares). Overwrites all prior CPUE count filters applied to this
 574        Query.
 575
 576        Args:
 577            eq: The exact value that must be matched for a record to be
 578                returned. Pass None if no equality filter should be applied.
 579                Error thrown if min_val or max_val also provided.
 580            min_val: The minimum allowed value, inclusive. Pass None if no
 581                minimum value filter should be applied. Defaults to None. Error
 582                thrown if eq also proivded.
 583            max_val: The maximum allowed value, inclusive. Pass None if no
 584                maximum value filter should be applied. Defaults to None. Error
 585                thrown if eq also proivded.
 586            units: The units for the given catch per unit effort. Options:
 587                count/ha, count/km2, and count1000/km2. Defaults to count/ha.
 588
 589        Returns:
 590            This object for chaining if desired.
 591        """
 592        param = self._create_float_param(eq, min_val, max_val)
 593
 594        self._cpue_noha = afscgap.param.EmptyParam()
 595        self._cpue_nokm2 = afscgap.param.EmptyParam()
 596        self._cpue_no1000km2 = afscgap.param.EmptyParam()
 597
 598        if units == 'count/ha':
 599            self._cpue_noha = param
 600        elif units == 'count/km2':
 601            self._cpue_nokm2 = param
 602        elif units == 'count1000/km2':
 603            self._cpue_no1000km2 = param
 604        else:
 605            raise RuntimeError('Unrecognized units ' + units)
 606
 607        return self
 608
 609    def filter_weight(self, eq: OPT_FLOAT = None,
 610        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 611        units: str = 'kg') -> 'Query':
 612        """Filter on taxon weight (kg) if available.
 613
 614        Filter on taxon weight (kg) if available, overwrites all prior weight
 615        filters applied to this Query.
 616
 617        Args:
 618            eq: The exact value that must be matched for a record to be
 619                returned. Pass None if no equality filter should be applied.
 620                Error thrown if min_val or max_val also provided.
 621            min_val: The minimum allowed value, inclusive. Pass None if no
 622                minimum value filter should be applied. Defaults to None. Error
 623                thrown if eq also proivded.
 624            max_val: The maximum allowed value, inclusive. Pass None if no
 625                maximum value filter should be applied. Defaults to None. Error
 626                thrown if eq also proivded.
 627            units: The units in which the weight are given. Options are
 628                g, kg for grams and kilograms respectively. Deafults to kg.
 629
 630        Returns:
 631            This object for chaining if desired.
 632        """
 633        self._weight_kg = self._create_float_param(
 634            afscgap.convert.convert(eq, units, 'kg'),
 635            afscgap.convert.convert(min_val, units, 'kg'),
 636            afscgap.convert.convert(max_val, units, 'kg')
 637        )
 638        return self
 639
 640    def filter_count(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
 641        max_val: OPT_FLOAT = None) -> 'Query':
 642        """Filter on total number of organism individuals in haul.
 643
 644        Filter on total number of organism individuals in haul, overwrites all
 645        prior count filters applied to this Query.
 646
 647        Args:
 648            eq: The exact value that must be matched for a record to be
 649                returned. Pass None if no equality filter should be applied.
 650                Error thrown if min_val or max_val also provided.
 651            min_val: The minimum allowed value, inclusive. Pass None if no
 652                minimum value filter should be applied. Defaults to None. Error
 653                thrown if eq also proivded.
 654            max_val: The maximum allowed value, inclusive. Pass None if no
 655                maximum value filter should be applied. Defaults to None. Error
 656                thrown if eq also proivded.
 657
 658        Returns:
 659            This object for chaining if desired.
 660        """
 661        self._count = self._create_float_param(eq, min_val, max_val)
 662        return self
 663
 664    def filter_bottom_temperature(self, eq: OPT_FLOAT = None,
 665        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 666        units: str = 'c') -> 'Query':
 667        """Filter on bottom temperature.
 668
 669        Filter on bottom temperature associated with observation if available in
 670        the units given. Overwrites all prior bottom temperature filters applied
 671        to this Query.
 672
 673        Args:
 674            eq: The exact value that must be matched for a record to be
 675                returned. Pass None if no equality filter should be applied.
 676                Error thrown if min_val or max_val also provided.
 677            min_val: The minimum allowed value, inclusive. Pass None if no
 678                minimum value filter should be applied. Defaults to None. Error
 679                thrown if eq also proivded.
 680            max_val: The maximum allowed value, inclusive. Pass None if no
 681                maximum value filter should be applied. Defaults to None. Error
 682                thrown if eq also proivded.
 683            units: The units in which the temperature filter values are given.
 684                Options: c or f for Celcius and Fahrenheit respectively.
 685                Defaults to c.
 686
 687        Returns:
 688            This object for chaining if desired.
 689        """
 690        self._bottom_temperature_c = self._create_float_param(
 691            afscgap.convert.convert(eq, units, 'c'),
 692            afscgap.convert.convert(min_val, units, 'c'),
 693            afscgap.convert.convert(max_val, units, 'c')
 694        )
 695        return self
 696
 697    def filter_surface_temperature(self, eq: OPT_FLOAT = None,
 698        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 699        units: str = 'c') -> 'Query':
 700        """Filter on surface temperature.
 701
 702        Filter on surface temperature associated with observation if available
 703        in the units given. Overwrites all prior bottom temperature filters
 704        applied to this Query.
 705
 706        Args:
 707            eq: The exact value that must be matched for a record to be
 708                returned. Pass None if no equality filter should be applied.
 709                Error thrown if min_val or max_val also provided.
 710            min_val: The minimum allowed value, inclusive. Pass None if no
 711                minimum value filter should be applied. Defaults to None. Error
 712                thrown if eq also proivded.
 713            max_val: The maximum allowed value, inclusive. Pass None if no
 714                maximum value filter should be applied. Defaults to None. Error
 715                thrown if eq also proivded.
 716            units: The units in which the temperature filter values are given.
 717                Options: c or f for Celcius and Fahrenheit respectively.
 718                Defaults to c.
 719
 720        Returns:
 721            This object for chaining if desired.
 722        """
 723        self._surface_temperature_c = self._create_float_param(
 724            afscgap.convert.convert(eq, units, 'c'),
 725            afscgap.convert.convert(min_val, units, 'c'),
 726            afscgap.convert.convert(max_val, units, 'c')
 727        )
 728        return self
 729
 730    def filter_depth(self, eq: OPT_FLOAT = None, min_val: OPT_FLOAT = None,
 731        max_val: OPT_FLOAT = None, units: str = 'm') -> 'Query':
 732        """Filter on depth of the bottom in meters.
 733
 734        Filter on depth of the bottom in meters, overwrites all prior depth
 735        filters applied to this Query.
 736
 737        Args:
 738            eq: The exact value that must be matched for a record to be
 739                returned. Pass None if no equality filter should be applied.
 740                Error thrown if min_val or max_val also provided.
 741            min_val: The minimum allowed value, inclusive. Pass None if no
 742                minimum value filter should be applied. Defaults to None. Error
 743                thrown if eq also proivded.
 744            max_val: The maximum allowed value, inclusive. Pass None if no
 745                maximum value filter should be applied. Defaults to None. Error
 746                thrown if eq also proivded.
 747            units: The units in which the distance are given. Options:
 748                m or km for meters and kilometers respectively. Defaults to m.
 749
 750        Returns:
 751            This object for chaining if desired.
 752        """
 753        self._depth_m = self._create_float_param(
 754            afscgap.convert.convert(eq, units, 'm'),
 755            afscgap.convert.convert(min_val, units, 'm'),
 756            afscgap.convert.convert(max_val, units, 'm')
 757        )
 758        return self
 759
 760    def filter_distance_fished(self, eq: OPT_FLOAT = None,
 761        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 762        units: str = 'm') -> 'Query':
 763        """Filter on distance of the net fished.
 764
 765        Filter on distance of the net fished, overwritting prior distance fished
 766        filters applied to this Query.
 767
 768        Args:
 769            eq: The exact value that must be matched for a record to be
 770                returned. Pass None if no equality filter should be applied.
 771                Error thrown if min_val or max_val also provided.
 772            min_val: The minimum allowed value, inclusive. Pass None if no
 773                minimum value filter should be applied. Defaults to None. Error
 774                thrown if eq also proivded.
 775            max_val: The maximum allowed value, inclusive. Pass None if no
 776                maximum value filter should be applied. Defaults to None. Error
 777                thrown if eq also proivded.
 778            units: The units in which the distance values are given. Options:
 779                m or km for meters and kilometers respectively. Defaults to m.
 780
 781        Returns:
 782            This object for chaining if desired.
 783        """
 784        def convert_to_km(target, units):
 785            return afscgap.convert.convert(target, units, 'km')
 786
 787        self._distance_fished_km = self._create_float_param(
 788            convert_to_km(eq, units),
 789            convert_to_km(min_val, units),
 790            convert_to_km(max_val, units)
 791        )
 792        return self
 793
 794    def filter_net_width(self, eq: OPT_FLOAT = None,
 795        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 796        units: str = 'm') -> 'Query':
 797        """Filter on distance of the net fished.
 798
 799        Filter on distance of the net fished, overwritting prior net width
 800        filters applied to this Query.
 801
 802        Args:
 803            eq: The exact value that must be matched for a record to be
 804                returned. Pass None if no equality filter should be applied.
 805                Error thrown if min_val or max_val also provided.
 806            min_val: The minimum allowed value, inclusive. Pass None if no
 807                minimum value filter should be applied. Defaults to None. Error
 808                thrown if eq also proivded.
 809            max_val: The maximum allowed value, inclusive. Pass None if no
 810                maximum value filter should be applied. Defaults to None. Error
 811                thrown if eq also proivded.
 812            units: The units in which the distance should be returned. Options:
 813                m or km for meters and kilometers respectively. Defaults to m.
 814
 815        Returns:
 816            This object for chaining if desired.
 817        """
 818        self._net_width_m = self._create_float_param(
 819            afscgap.convert.convert(eq, units, 'm'),
 820            afscgap.convert.convert(min_val, units, 'm'),
 821            afscgap.convert.convert(max_val, units, 'm')
 822        )
 823        return self
 824
 825    def filter_net_height(self, eq: OPT_FLOAT = None,
 826        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 827        units: str = 'm') -> 'Query':
 828        """Filter on height of the net fished.
 829
 830        Filter on height of the net fished, overwritting prior net height
 831        filters applied to this Query.
 832
 833        Args:
 834            eq: The exact value that must be matched for a record to be
 835                returned. Pass None if no equality filter should be applied.
 836                Error thrown if min_val or max_val also provided.
 837            min_val: The minimum allowed value, inclusive. Pass None if no
 838                minimum value filter should be applied. Defaults to None. Error
 839                thrown if eq also proivded.
 840            max_val: The maximum allowed value, inclusive. Pass None if no
 841                maximum value filter should be applied. Defaults to None. Error
 842                thrown if eq also proivded.
 843            units: The units in which the distance should be returned. Options:
 844                m or km for meters and kilometers respectively. Defaults to m.
 845
 846        Returns:
 847            This object for chaining if desired.
 848        """
 849        self._net_height_m = self._create_float_param(
 850            afscgap.convert.convert(eq, units, 'm'),
 851            afscgap.convert.convert(min_val, units, 'm'),
 852            afscgap.convert.convert(max_val, units, 'm')
 853        )
 854        return self
 855
 856    def filter_area_swept(self, eq: OPT_FLOAT = None,
 857        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 858        units: str = 'm') -> 'Query':
 859        """Filter on area covered by the net while fishing.
 860
 861        Filter on area covered by the net while fishing, overwritting prior
 862        area swept filters applied to this Query.
 863
 864        Args:
 865            eq: The exact value that must be matched for a record to be
 866                returned. Pass None if no equality filter should be applied.
 867                Error thrown if min_val or max_val also provided.
 868            min_val: The minimum allowed value, inclusive. Pass None if no
 869                minimum value filter should be applied. Defaults to None. Error
 870                thrown if eq also proivded.
 871            max_val: The maximum allowed value, inclusive. Pass None if no
 872                maximum value filter should be applied. Defaults to None. Error
 873                thrown if eq also proivded.
 874            units: The units in which the area should be returned. Options:
 875                ha, m2, km2. Defaults to ha.
 876
 877        Returns:
 878            This object for chaining if desired.
 879        """
 880        self._area_swept_ha = self._create_float_param(
 881            afscgap.convert.convert(eq, units, 'ha'),
 882            afscgap.convert.convert(min_val, units, 'ha'),
 883            afscgap.convert.convert(max_val, units, 'ha')
 884        )
 885        return self
 886
 887    def filter_duration(self, eq: OPT_FLOAT = None,
 888        min_val: OPT_FLOAT = None, max_val: OPT_FLOAT = None,
 889        units: str = 'hr') -> 'Query':
 890        """Filter on duration of the haul.
 891
 892        Filter on duration of the haul, ovewritting all prior duration filters
 893        applied to this Query.
 894
 895        Args:
 896            eq: The exact value that must be matched for a record to be
 897                returned. Pass None if no equality filter should be applied.
 898                Error thrown if min_val or max_val also provided.
 899            min_val: The minimum allowed value, inclusive. Pass None if no
 900                minimum value filter should be applied. Defaults to None. Error
 901                thrown if eq also proivded.
 902            max_val: The maximum allowed value, inclusive. Pass None if no
 903                maximum value filter should be applied. Defaults to None. Error
 904                thrown if eq also proivded.
 905            units: The units in which the duration should be returned. Options:
 906                day, hr, min. Defaults to hr.
 907
 908        Returns:
 909            This object for chaining if desired.
 910        """
 911        self._duration_hr = self._create_float_param(
 912            afscgap.convert.convert(eq, units, 'hr'),
 913            afscgap.convert.convert(min_val, units, 'hr'),
 914            afscgap.convert.convert(max_val, units, 'hr')
 915        )
 916        return self
 917
 918    def set_limit(self, limit: OPT_INT) -> 'Query':
 919        """Set the max number of results.
 920
 921        Set the max number of results, overwritting prior limit settings on this
 922        Query.
 923
 924        Args:
 925            limit: The maximum number of results to retrieve per HTTP request.
 926                If None or not provided, will use API's default.
 927
 928        Returns:
 929            This object for chaining if desired.
 930        """
 931        self._limit = limit
 932        return self
 933
 934    def set_filter_incomplete(self, filter_incomplete: bool) -> 'Query':
 935        """Indicate if incomplete records should be filtered out.
 936
 937        Indicate if incomplete records should be filtered out, overwritting
 938        prior incomplete filter settings on this Query.
 939
 940        Args:
 941            filter_incomplete: Flag indicating if "incomplete" records should be
 942                filtered. If true, "incomplete" records are silently filtered
 943                from the results, putting them in the invalid records queue. If
 944                false, they are included and their is_complete() will return
 945                false. Defaults to false.
 946
 947        Returns:
 948            This object for chaining if desired.
 949        """
 950        self._filter_incomplete = filter_incomplete
 951        return self
 952
 953    def set_presence_only(self, presence_only: bool) -> 'Query':
 954        """Indicate if zero catch inference should be enabled.
 955
 956        Indicate if zero catch inference should be enabled, overwritting prior
 957        abscence / zero catch data settings on this Query.
 958
 959        Args:
 960            presence_only: Flag indicating if abscence / zero catch data should
 961                be inferred. If false, will run abscence data inference. If
 962                true, will return presence only data as returned by the NOAA API
 963                service. Defaults to true.
 964
 965        Returns:
 966            This object for chaining if desired.
 967        """
 968        self._presence_only = presence_only
 969        return self
 970
 971    def set_suppress_large_warning(self, supress: bool) -> 'Query':
 972        """Indicate if the large results warning should be supressed.
 973
 974        Indicate if the large results warning should be supressed, overwritting
 975        prior large results warning supressions settings on this Query.
 976
 977        Args:
 978            suppress_large_warning: Indicate if the library should warn when an
 979                operation may consume a large amount of memory. If true, the
 980                warning will not be emitted. Defaults to true.
 981
 982        Returns:
 983            This object for chaining if desired.
 984        """
 985        self._suppress_large_warning = supress
 986        return self
 987
 988    def set_warn_function(self, warn_function: WARN_FUNCTION) -> 'Query':
 989        """Indicate how warnings should be emitted.
 990
 991        Indicate how warnings should be emitted, overwritting the prior warning
 992        function settings on this Query.
 993
 994        Args:
 995            warn_function: Function to call with a message describing warnings
 996                encountered. If None, will use warnings.warn. Defaults to None.
 997
 998        Returns:
 999            This object for chaining if desired.
1000        """
1001        self._warn_function = warn_function
1002        return self
1003
1004    def execute(self) -> afscgap.cursor.Cursor:
1005        """Execute the query built up in this object.
1006
1007        Execute the query built up in this object using its current state. Note
1008        that later changes to this builder will not impact prior returned
1009        Cursors from execute.
1010
1011        Returns:
1012            Cursor to manage HTTP requests and query results.
1013        """
1014        params_dict = {
1015            'year': self._year,
1016            'srvy': self._srvy,
1017            'survey': self._survey,
1018            'survey_id': self._survey_id,
1019            'cruise': self._cruise,
1020            'haul': self._haul,
1021            'stratum': self._stratum,
1022            'station': self._station,
1023            'vessel_name': self._vessel_name,
1024            'vessel_id': self._vessel_id,
1025            'date_time': self._date_time,
1026            'latitude_dd': self._latitude_dd,
1027            'longitude_dd': self._longitude_dd,
1028            'species_code': self._species_code,
1029            'common_name': self._common_name,
1030            'scientific_name': self._scientific_name,
1031            'taxon_confidence': self._taxon_confidence,
1032            'cpue_kgha': self._cpue_kgha,
1033            'cpue_kgkm2': self._cpue_kgkm2,
1034            'cpue_kg1000km2': self._cpue_kg1000km2,
1035            'cpue_noha': self._cpue_noha,
1036            'cpue_nokm2': self._cpue_nokm2,
1037            'cpue_no1000km2': self._cpue_no1000km2,
1038            'weight_kg': self._weight_kg,
1039            'count': self._count,
1040            'bottom_temperature_c': self._bottom_temperature_c,
1041            'surface_temperature_c': self._surface_temperature_c,
1042            'depth_m': self._depth_m,
1043            'distance_fished_km': self._distance_fished_km,
1044            'net_width_m': self._net_width_m,
1045            'net_height_m': self._net_height_m,
1046            'area_swept_ha': self._area_swept_ha,
1047            'duration_hr': self._duration_hr
1048        }
1049
1050        meta_params = afscgap.flat_model.ExecuteMetaParams(
1051            self._base_url if self._base_url else DEFAULT_URL,
1052            self._requestor,
1053            self._limit,
1054            self._filter_incomplete,
1055            self._presence_only,
1056            self._suppress_large_warning,
1057            self._warn_function
1058        )
1059
1060        return afscgap.flat.execute(params_dict, meta_params)
1061
1062    def _create_str_param(self, eq: STR_PARAM = None, min_val: OPT_STR = None,
1063        max_val: OPT_STR = None) -> afscgap.param.Param:
1064        """Create a new string parameter.
1065
1066        Args:
1067            eq: The exact value that must be matched for a record to be
1068                returned. Pass None if no equality filter should be applied.
1069                Error thrown if min_val or max_val also provided.
1070            min_val: The minimum allowed value, inclusive. Pass None if no
1071                minimum value filter should be applied. Defaults to None. Error
1072                thrown if eq also proivded.
1073            max_val: The maximum allowed value, inclusive. Pass None if no
1074                maximum value filter should be applied. Defaults to None. Error
1075                thrown if eq also proivded.
1076
1077        Returns:
1078            Newly initalized parameter.
1079        """
1080        param_type = self._get_param_type(eq, min_val, max_val)
1081        strategy = {
1082            'empty': lambda: afscgap.param.EmptyParam(),
1083            'equals': lambda: afscgap.param.StrEqualsParam(eq),  # type: ignore
1084            'range': lambda: afscgap.param.StrRangeParam(min_val, max_val)  # type: ignore
1085        }[param_type]
1086        return strategy()  # type: ignore
1087
1088    def _create_float_param(self, eq: OPT_FLOAT = None,
1089        min_val: OPT_FLOAT = None,
1090        max_val: OPT_FLOAT = None) -> afscgap.param.Param:
1091        """Create a new float parameter.
1092
1093        Args:
1094            eq: The exact value that must be matched for a record to be
1095                returned. Pass None if no equality filter should be applied.
1096                Error thrown if min_val or max_val also provided.
1097            min_val: The minimum allowed value, inclusive. Pass None if no
1098                minimum value filter should be applied. Defaults to None. Error
1099                thrown if eq also proivded.
1100            max_val: The maximum allowed value, inclusive. Pass None if no
1101                maximum value filter should be applied. Defaults to None. Error
1102                thrown if eq also proivded.
1103
1104        Returns:
1105            Newly initalized parameter.
1106        """
1107        param_type = self._get_param_type(eq, min_val, max_val)
1108        strategy = {
1109            'empty': lambda: afscgap.param.EmptyParam(),
1110            'equals': lambda: afscgap.param.FloatEqualsParam(eq),    # type: ignore
1111            'range': lambda: afscgap.param.FloatRangeParam(min_val, max_val)   # type: ignore
1112        }[param_type]
1113        return strategy()  # type: ignore
1114
1115    def _create_int_param(self, eq: INT_PARAM = None, min_val: OPT_INT = None,
1116        max_val: OPT_INT = None) -> afscgap.param.Param:
1117        """Create a new int parameter.
1118
1119        Args:
1120            eq: The exact value that must be matched for a record to be
1121                returned. Pass None if no equality filter should be applied.
1122                Error thrown if min_val or max_val also provided.
1123            min_val: The minimum allowed value, inclusive. Pass None if no
1124                minimum value filter should be applied. Defaults to None. Error
1125                thrown if eq also proivded.
1126            max_val: The maximum allowed value, inclusive. Pass None if no
1127                maximum value filter should be applied. Defaults to None. Error
1128                thrown if eq also proivded.
1129
1130        Returns:
1131            Newly initalized parameter.
1132        """
1133        param_type = self._get_param_type(eq, min_val, max_val)
1134        strategy = {
1135            'empty': lambda: afscgap.param.EmptyParam(),
1136            'equals': lambda: afscgap.param.IntEqualsParam(eq),  # type: ignore
1137            'range': lambda: afscgap.param.IntRangeParam(min_val, max_val)  # type: ignore
1138        }[param_type]
1139        return strategy()  # type: ignore
1140
1141    def _get_param_type(self, eq, min_val, max_val) -> str:
1142        """Determine how the parameter should be interpreted.
1143
1144        Args:
1145            eq: The value for equality or None if no equals filter.
1146            min_val: The minimum value or None if no minimum filter.
1147            max_val: The maximum value or None if no maximum filter.
1148
1149        Returns:
1150            One of the following as a string: empty, equals, range.
1151        """
1152        if eq is None:
1153            if min_val is None and max_val is None:
1154                return 'empty'
1155            else:
1156                return 'range'
1157        else:
1158            if min_val is not None or max_val is not None:
1159                raise RuntimeError('Both range and equality filters provided.')
1160            else:
1161                return 'equals'