bvbrc.SurveillanceClient#

class bvbrc.SurveillanceClient(api_key=None)#

Data Type : surveillance

Primary Key : id

get(id: str, *, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None) → BVBRCResponse#

Retrieve a specific record by its unique identifier.

Fetches a single data record from the BV-BRC database using its unique ID. This is useful when you know the exact identifier of the record you want to retrieve.

Parameters#

idstr: The unique identifier of the record to retrieve. The format depends on the datatype (e.g., genome IDs, feature IDs, etc.).
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the retrieved data and associated response metadata.

Examples#

Retrieve a genome by ID:

>>> import bvbrc as bv
>>> genome_client = bv.GenomeClient()
>>> response = genome_client.get("1313.5458")

Retrieve with custom format and timeout:

>>> response = genome_client.get(
...     "1313.5458",
...     return_format=bv.ReturnFormat.CSV,
...     timeout=30
... )

search(*predicates: RQLExpr, select: Iterable[str | Field] = Ellipsis, sort: Iterable[str | Field] = Ellipsis, limit: int | Literal['max'] = Ellipsis, start: int = 0, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None, **constraints: Any) → BVBRCResponse#

Search for records using provided parameters.

Sends a query to the BV-BRC API using Resource Query Language (RQL) expressions and field constraints. This is the primary method for finding records that match specific criteria.

Parameters#

*predicatesRQL.RQLExpr: Variable number of RQL expression objects that define the search criteria. These are combined using a logical AND operation.
selectiterable of str or RQL.Field, optional: Fields to include in the query results. Can be field names as strings or RQL.Field objects. If not specified, fields are returned based on the default behavior of the BV-BRC API (which may vary by return format).
sortiterable of str or RQL.Field, optional: Fields to sort the results by. Can be field names as strings or RQL.Field objects. Multiple fields create a multi-level sort. Sort direction must be specified with ‘+’ (ascending) or ‘-’ (descending).
limitint or “max”, optional: Maximum number of results to return. Can be an integer or the string “max” to return all matching results (up to a maximum of 25,000).
startint, default 0: Starting offset for pagination (0-based index).
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).
**constraintsany: Additional keyword arguments that specify field constraints or filters. Each key-value pair represents a field name and its required value.

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the query results and associated response metadata.

Examples#

Basic search with field constraints:

>>> import bvbrc as bv
>>> genome_client = bv.GenomeClient()
>>> response = genome_client.search(species="Escherichia coli", limit=10)

Advanced search with predicates:

>>> response = genome_client.search(
...     bv.fld("genome_length") > 5000000,
...     bv.fld("genome_status") == "Complete",
...     select=["genome_id", "genome_name", "genome_length"],
...     sort=["+genome_length"],
...     limit=50
... )

Or searching using the field attributes of the client object:

>>> response = genome_client.search(
...     genome_client.genome_length > 5000000,
...     genome_client.genome_status == "Complete",
...     select=[
...         genome_client.genome_id,
...         genome_client.genome_name,
...         genome_client.genome_length
...     ],
...     sort=[+genome_client.genome_length],
...     limit=50
... )

submit_query(query: RQLQuery, *, return_format: str | ReturnFormat = ReturnFormat.JSON, timeout: float | tuple[float, float] | None = None) → BVBRCResponse#

Submit a pre-built RQL query to the BV-BRC API.

This method is useful when you have already built a query using the bvbrc.query method and want to submit it with a client.

Parameters#

queryRQL.RQLQuery: A pre-built RQL query object containing the search criteria, field selections, sorting, and other query parameters.
return_formatstr or ReturnFormat, default ReturnFormat.JSON: The desired format for the returned data. See the BV-BRC documentation for allowed return formats.
timeoutfloat or tuple, optional: Timeout for the HTTP request. Can be a single float (total timeout) or a tuple of (connect_timeout, read_timeout).

Returns#

BVBRCResponse: A response object (derived from the requests.Response object) containing the query results and associated response metadata.

Examples#

Build and submit a query:

>>> import bvbrc as bv
>>> q = bv.query(
...     bv.fld("genome_name") == "Escherichia coli",
...     select=["genome_id", "genome_name"],
...     limit=10
... )
>>> client = bv.GenomeClient()
>>> response = client.submit_query(q)

Specify the return format:

>>> response = client.submit_query(
...     q,
...     return_format=bv.ReturnFormat.CSV
)

additional_metadata = Field('additional_metadata')#: array of case insensitive strings

alcohol_or_other_drug_dependence = Field('alcohol_or_other_drug_dependence')#: case insensitive string

breastfeeding = Field('breastfeeding')#: case insensitive string

chest_imaging_interpretation = Field('chest_imaging_interpretation')#: case insensitive string

chronic_conditions = Field('chronic_conditions')#: array of case insensitive strings

collection_city = Field('collection_city')#: case insensitive string

collection_country = Field('collection_country')#: case insensitive string

collection_date = Field('collection_date')#: date

collection_latitude = Field('collection_latitude')#: number

collection_longitude = Field('collection_longitude')#: number

collection_poi = Field('collection_poi')#: case insensitive string

collection_season = Field('collection_season')#: case insensitive string

collection_state_province = Field('collection_state_province')#: case insensitive string

collection_year = Field('collection_year')#: case insensitive string

collector_institution = Field('collector_institution')#: case insensitive string

collector_name = Field('collector_name')#: array of case insensitive strings

comments = Field('comments')#: array of case insensitive strings

contact_email_address = Field('contact_email_address')#: case insensitive string

contributing_institution = Field('contributing_institution')#: case insensitive string

date_inserted = Field('date_inserted')#: date

date_modified = Field('date_modified')#: date

daycare_attendance = Field('daycare_attendance')#: case insensitive string

days_elapsed_to_disease_status = Field('days_elapsed_to_disease_status')#: case insensitive string

days_elapsed_to_sample_collection = Field('days_elapsed_to_sample_collection')#: case insensitive string

days_elapsed_to_vaccination = Field('days_elapsed_to_vaccination')#: array of case insensitive strings

diagnosis = Field('diagnosis')#: array of case insensitive strings

dialysis = Field('dialysis')#: case insensitive string

disease_severity = Field('disease_severity')#: case insensitive string

disease_status = Field('disease_status')#: case insensitive string

duration_of_exposure = Field('duration_of_exposure')#: array of case insensitive strings

duration_of_treatment = Field('duration_of_treatment')#: array of case insensitive strings

ecmo = Field('ecmo')#: case insensitive string

education = Field('education')#: case insensitive string

embargo_end_date = Field('embargo_end_date')#: date

exposure = Field('exposure')#: array of case insensitive strings

exposure_type = Field('exposure_type')#: array of case insensitive strings

genome_id = Field('genome_id')#: array of strings

geographic_group = Field('geographic_group')#: case insensitive string

hospitalization_duration = Field('hospitalization_duration')#: case insensitive string

hospitalized = Field('hospitalized')#: case insensitive string

host_age = Field('host_age')#: case insensitive string

host_capture_status = Field('host_capture_status')#: case insensitive string

host_common_name = Field('host_common_name')#: case insensitive string

host_ethnicity = Field('host_ethnicity')#: array of case insensitive strings

host_group = Field('host_group')#: case insensitive string

host_habitat = Field('host_habitat')#: case insensitive string

host_health = Field('host_health')#: case insensitive string

host_height = Field('host_height')#: case insensitive string

host_id_type = Field('host_id_type')#: case insensitive string

host_identifier = Field('host_identifier')#: string

host_natural_state = Field('host_natural_state')#: case insensitive string

host_race = Field('host_race')#: array of case insensitive strings

host_sex = Field('host_sex')#: case insensitive string

host_species = Field('host_species')#: case insensitive string

host_weight = Field('host_weight')#: case insensitive string

human_leukocyte_antigens = Field('human_leukocyte_antigens')#: case insensitive string

id = Field('id')#

primary key

string

infections_within_five_years = Field('infections_within_five_years')#: array of case insensitive strings

influenza_like_illness_over_the_past_year = Field('influenza_like_illness_over_the_past_year')#: case insensitive string

initiation_of_treatment = Field('initiation_of_treatment')#: array of case insensitive strings

intensive_care_unit = Field('intensive_care_unit')#: case insensitive string

last_update_date = Field('last_update_date')#: date

longitudinal_study = Field('longitudinal_study')#: case insensitive string

maintenance_medication = Field('maintenance_medication')#: array of case insensitive strings

nursing_home_residence = Field('nursing_home_residence')#: case insensitive string

onset_hours = Field('onset_hours')#: case insensitive string

other_vaccinations = Field('other_vaccinations')#: case insensitive string

oxygen_saturation = Field('oxygen_saturation')#: case insensitive string

packs_per_day_for_how_many_years = Field('packs_per_day_for_how_many_years')#: case insensitive string

pathogen_test_interpretation = Field('pathogen_test_interpretation')#: array of case insensitive strings

pathogen_test_result = Field('pathogen_test_result')#: array of case insensitive strings

pathogen_test_type = Field('pathogen_test_type')#: array of case insensitive strings

pathogen_type = Field('pathogen_type')#: case insensitive string

post_visit_medications = Field('post_visit_medications')#: array of case insensitive strings

pre_visit_medications = Field('pre_visit_medications')#: array of case insensitive strings

pregnancy = Field('pregnancy')#: case insensitive string

primary_living_situation = Field('primary_living_situation')#: case insensitive string

profession = Field('profession')#: case insensitive string

project_identifier = Field('project_identifier')#: string

sample_accession = Field('sample_accession')#: string

sample_identifier = Field('sample_identifier')#: string

sample_material = Field('sample_material')#: case insensitive string

sample_receipt_date = Field('sample_receipt_date')#: case insensitive string

sample_transport_medium = Field('sample_transport_medium')#: case insensitive string

sequence_accession = Field('sequence_accession')#: array of strings

source_of_vaccine_information = Field('source_of_vaccine_information')#: array of case insensitive strings

species = Field('species')#: case insensitive string

strain = Field('strain')#: case insensitive string

submission_date = Field('submission_date')#: date

subtype = Field('subtype')#: case insensitive string

sudden_onset = Field('sudden_onset')#: case insensitive string

symptoms = Field('symptoms')#: array of case insensitive strings

taxon_lineage_ids = Field('taxon_lineage_ids')#: array of strings

tobacco_use = Field('tobacco_use')#: case insensitive string

travel_history = Field('travel_history')#: array of case insensitive strings

treatment = Field('treatment')#: array of case insensitive strings

treatment_dosage = Field('treatment_dosage')#: array of case insensitive strings

treatment_type = Field('treatment_type')#: array of case insensitive strings

trimester_of_pregnancy = Field('trimester_of_pregnancy')#: case insensitive string

types_of_allergies = Field('types_of_allergies')#: array of case insensitive strings

use_of_personal_protective_equipment = Field('use_of_personal_protective_equipment')#: array of case insensitive strings

vaccination_type = Field('vaccination_type')#: case insensitive string

vaccine_dosage = Field('vaccine_dosage')#: array of case insensitive strings

vaccine_lot_number = Field('vaccine_lot_number')#: array of case insensitive strings

vaccine_manufacturer = Field('vaccine_manufacturer')#: array of case insensitive strings

ventilation = Field('ventilation')#: case insensitive string