pisces.request

Convenience functions for building common queries.

pisces.request.distaz_query(records, deg=None, km=None, swath=None)

Out-of-database subset based on distances and/or azimuths.

Parameters:

recordsiterable of objects with lat, lon attribute floats

Target of the subset.

deglist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) minr, maxr in degrees or None for unconstrained.

kmlist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) minr, maxr in km or None for unconstrained.

swathlist or tuple of numbers, optional

(lat, lon, azimuth, tolerance) Azimuth (from North) +/-tolerance from lat,lon point in degrees.

Returns:

list

Subset of supplied records.

pisces.request.geographic_query(q, table, region=None, depth=None, asquery=False)

Filter by region (W, E, S, N) [deg] and/or depth range (min, max) [km].

pisces.request.get_arrivals(session, arrival, assoc=None, stations=None, channels=None, atime=None, phases=None, arids=None, orids=None, auth=None, asquery=False)

Build common queries for arrivals.

Parameters:

stations, channelslist or tuple of strings

Desired station, channel strings.

arrival: mapped Arrival table class

assoc: mapped Assoc table class, optional

atimetuple or list of float, optional

(tstart, tend) epoch arrival time window. Either can be None.

phases: list or tuple of strings

Arrival ‘iphase’.

aridslist of integers

Desired arid numbers.

oridslist of integers

orids from which associated arrivals will be returned. Requires Assoc table.

authlist/tuple of strings

Arrival author list.

Returns:

list or sqlalchemy.orm.Query instance

Arrival results.

Notes

Each argument adds an AND clause to the SQL query. Unspecified (keyword) arguments are treated as wildcards. That is, no arguments means, “give me all arrivals everywhere ever.”

pisces.request.get_events(session, origin, event=None, region=None, deg=None, km=None, swath=None, mag=None, depth=None, etime=None, orids=None, evids=None, prefor=False, asquery=False)

Build common queries for events.

Parameters:

sessionsqlalchemy.orm.Session instance

Must be bound.

originmapped Origin table class

eventmapped Event table class, optional

regionlist or tuple of numbers, optional

(W, E, S, N) in degrees. Default, None.

deglist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) . Default, None. minr, maxr in degrees or None for unconstrained.

kmlist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) Default, None. minr, maxr in km or None for unconstrained.

swathlist or tuple of numbers, optional

(lat, lon, azimuth, tolerance) Azimuth (from North) +/-tolerance from lat,lon point in degrees. Not yet implemented.

magdict, optional

{‘type1’: [min1, max1], ‘type2’: [min2, max2], …} ‘type’ can be ‘mb’, ‘ms’, or ‘ml’. Produces OR clauses.

depthtuple or list, optional

Depth interval [mindep, maxdep] in km. Use None for an unconstrained limit.

etimetuple or list, optional

(tstart, tend) epoch event time window Use None for an unconstrained limit.

orids, evidslist or tuple of int, optional

orid, evid numbers < 1000 in length Evids requires event table.

preforbool, optional

Return preferred origins only. Default False. Requires event table be provided.

asquerybool, optional

Return the query object instead of the results. Default, False. Useful if additional you desire additional sorting of filtering, or if you have your own in-database geographic query function(s). If supplied, deg, km, and/or swath are ignored in the returned query.

Returns:

sqlalchemy.orm.Query instance

Notes

Each keyword argument corresponds to an AND clause, except ‘mag’ which returns OR clauses. Don’t submit a request containing both ‘evids’ and ‘orids’ unless you want them joined by an AND clause. Otherwise process them individually, then collate and unique them afterwards.

pisces.request.get_ids(session, lastid, ids, detach=False)

Get or create lastid rows.

Parameters:

sessionsqlalchemy.orm.session instance, bound

lastidsqlalchemy orm mapped lastid table

idslist

Desired lastid keyname strings.

detachbool, optional

If True, expunge results from session before returning. Useful if you don’t have permission on lastid, and don’t want session commits to throw a permission error.

Returns:

list

Corresponding existing or new rows from lastid table.

Notes

Keyvalue is 0 if id name not present in lastid table.

pisces.request.get_stations(session, site, sitechan=None, affiliation=None, stations=None, channels=None, nets=None, loc=None, region=None, deg=None, km=None, swath=None, time_span=None, asquery=False)

Build common queries for stations.

Parameters:

sessionsqlalchemy.orm.Session instance

Must be bound.

sitemapped Site table class

sitechanmapped Sitechan table class, optional

affiliationmapped Affiliation table class, optional

stationslist or tuple of strings

Desired station code strings.

channels, netslist or tuple of strings, or single regex string, optional

Desired channel, network code strings or regex

loclist/tuple, optional

Location code. Not yet implemented.

regiontuple or list of numbers, optional

Geographic (W,E,S,N) in degrees, None values for unconstrained.

deglist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) minr, maxr in degrees or None for unconstrained.

kmlist or tuple of numbers, optional

(centerlat, centerlon, minr, maxr) minr, maxr in km or None for unconstrained.

swathlist or tuple of numbers, optional

(lat, lon, azimuth, tolerance) Azimuth (from North) +/-tolerance from lat,lon point in degrees. Currently only works in gnem Oracle.

asquerybool, optional

Return the query object instead of the results. Default, False. Useful if additional you desire additional sorting of filtering, or if you have your own in-database geographic query function(s). If supplied, deg, km, and/or swath are ignored in the returned query.

time_spantuple or list

(startdate, enddate) or [startdate, enddate] startdate and enddate are integer julian days of when you want stations (YYYYddd). If stations were moved one or more times in the time_span, you will get multiple copies of the station with updated gps values. If you want to be guaranteed a specific station at a specific time, startdate and enddate must both be included, even if they are the same.

Notes

Each parameter produces an AND clause, list parameters produce IN clauses, a regex produces a REGEXP_LIKE clause (Oracle-specific?).

deg, km, and swath are evaluated out-of-database by evaluating all other flags first, then masking. This can be memory-intensive. See “Examples” for how to perform in-database distance filters.

To include channels or networks with your results use asquery=True, and

>>> q = q.add_columns(Sitechan.chan)
>>> q = q.add_columns(Affiliation.net)

with the returned query.

Examples

Use your own in-database distance query function “km_from_point”:

>>> from sqlalchemy import func
>>> q = get_stations(session, site, channels=['BHZ'], region=(65,75,30,40), asquery=True)
>>> stations = q.filter(func.km_from_point(site.lat, site.lon, 40, -110) < 100).all()

pisces.request.get_waveforms(session, wfdisc, station=None, channel=None, starttime=None, endtime=None, wfids=None, tol=None, asquery=False)

Request waveforms.

Parameters:

sessionsqlalchemy.orm.Session instance

Must be bound.

wfdiscmapped Wfdisc table class

station, channelstr, optional

Desired station, channel code strings

starttimes, endtimesfloat, optional

Epoch start times, end times. Traces will be cut to these times.

wfidsiterable of int, optional

Wfdisc wfids. Obviates the above arguments and just returns full Wfdisc row waveforms.

tolfloat

If provided, a warning is fired if any Trace is not within tol seconds of starttime and endtime.

asquerybool, optional

Return the query object instead of the results. Default, False. Useful if additional you desire additional sorting of filtering.

Returns:

obspy.Stream

Traces are merged and cut to requested times.

pisces.request.get_wfdisc_rows(session, wfdisc, sta=None, chan=None, t1=None, t2=None, wfids=None, daylong=False, asquery=False, verbose=False)

Returns a list of wfdisc records from provided SQLAlchemy ORM mapped wfdisc table, for given station, channel, and time window combination.

Parameters:

session: bound session instance

wfdisc: SQLAlchemy mapped wfdisc table

sta, chan,str, optional

station, channel strings,

t1, t2int, optional

Epoch time window of interest (seconds) Actually searches for wfdisc.time between t1-86400 and t2 and wfdisc.endtime > t1

wfidslist of integers, optional

wfid integers. Obviates other arguments.

daylongbool, optional

If True, uses a slightly different time query for best results. Not yet implemented (is currently the default behavior).

asquerybool, optional

Return the query object instead of the results. Default, False. Useful if additional you desire additional sorting of filtering.

verbosebool, optional

Print request to the stdout. Not used with asquery=True.

Returns:

list of wfdisc row objects, or sqlalchemy.orm.Query instance

pisces.request.netstachan_query(q, stations=None, channels=None, networks=None, asquery=False)

pisces.request.time_query(q, time=None, daylong=False, asquery=False)

pisces.request.wfdisc_rows_to_stream(wf_rows, start_t, end_t, tol=None)

Convert wfdisc rows to obspy stream, trim the data to starttime and endtime in the process

Parameters:

wf_rows

Wfdisc rows as generated by get_wfdisc_rows or similar

start_t: UTCDateTime

Requested start time of the returned traces

end_t: UTCDateTime

Requested end time of the returned traces

tol: float

If provided, a warning is fired if any Trace is not within tol seconds of starttime and endtime

Returns:

obspy.Stream

Traces are merged and trimmed to requested times

Raises:

ValueError:

Returned Stream contains trace start/end times outside of the tolerance.