afscgap

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