quantlab.dataset.nbbo.bars.NbboBarsRequest

class quantlab.dataset.nbbo.bars.NbboBarsRequest(bar_interval, session_start='09:30', session_end='16:00', policy=<factory>)

Bases: object

The settings NBBO bars are cut with on the WRDS server.

Two requests are equal exactly when they produce the same bars from the same records. The session edges are normalised ("09:30:00" and "09:30" are one edge), and the filter policy is compared field by field.

Parameters:

bar_intervalstr

The bar size, a key of BAR_INTERVAL_SECONDS.

session_start, session_endstr, default “09:30”, “16:00”

The session window, New York clock time, as for XnysSessionCalendar.

policyNbboFilterPolicy, default NbboFilterPolicy()

The quote filters.

Raises:

ValueError

If the bar size is unknown or the session window is malformed.

Examples

>>> request = NbboBarsRequest("1m", "09:30:00", "16:00")
>>> request.session_start, request.bar_seconds
('09:30', 60)
>>> request == NbboBarsRequest.from_record(request.as_record())
True

as_record()

Return the request as the JSON-ready dict written with the raw tier.

Examples

>>> NbboBarsRequest("1m").as_record()["drop_crossed"]
True

assert_recorded(root, owner)

Raise unless this request is the one recorded under root.

Called by the conversion, which must not label bars with settings they were not built with.

Parameters:

rootstr or os.PathLike

The nbbo_bars watermark directory.

ownerstr

Names the caller in the error message.

Raises:

ValueError

If nothing is recorded there, or a different request is.

Examples

For a directory nothing was downloaded into:

NbboBarsRequest("1m").assert_recorded(
    "downloads/_watermarks/wrds/nbbo_bars", "demo"
)
# ValueError: demo: no NBBO bar settings are recorded ...

property bar_seconds

Return the bar length in seconds.

Examples

>>> NbboBarsRequest("5m").bar_seconds
300

calendar()

Return a session calendar for this request’s window.

Build it once and pass it to session: the exchange calendar loads on first use and takes a moment.

Examples

>>> NbboBarsRequest("1m").calendar().session_end
datetime.time(16, 0)

classmethod from_config(config)

Build the request an NbboBarsDatasetConfig describes.

Parameters:

configNbboBarsDatasetConfig

Its frequency is the bar size.

Returns:

NbboBarsRequest

The request.

Examples

With config an NbboBarsDatasetConfig left at its defaults:

NbboBarsRequest.from_config(config).bar_interval   # '1m'

classmethod from_record(record)

Rebuild a request from as_record output.

Examples

>>> NbboBarsRequest.from_record(NbboBarsRequest("5m").as_record()).bar_interval
'5m'

classmethod read(root)

Return the request recorded under root, or None if there is none.

Examples

For a directory nothing was downloaded into:

NbboBarsRequest.read("downloads/_watermarks/wrds/nbbo_bars")  # None

record(root, owner)

Record this request under root, or check it against the one recorded.

Called by the acquisition before it downloads anything.

Parameters:

rootstr or os.PathLike

The nbbo_bars watermark directory.

ownerstr

Names the caller in the error message.

Raises:

ValueError

If a different request is already recorded there.

Examples

The first call writes the file, a different request is then refused:

root = "downloads/_watermarks/wrds/nbbo_bars"
NbboBarsRequest("1m").record(root, "demo")
NbboBarsRequest("5m").record(root, "demo")
# ValueError: demo: the NBBO bars under ... were built with
# different settings ...

static record_path(root)

Return the request file in the nbbo_bars watermark directory root.

Examples

>>> NbboBarsRequest.record_path("/dl/_watermarks/wrds/nbbo_bars")
PosixPath('/dl/_watermarks/wrds/nbbo_bars/_request.json')

session(calendar, day)

Return the bounds of day’s session, or None if its window is empty.

Half days and daylight saving come from the calendar, exactly as for the tick path, so the server and the tick path cut the same grid.

Parameters:

calendarXnysSessionCalendar

From calendar().

daydatetime.date

A trading session date.

Returns:

NbboBarsSession or None

None when the window is empty on that day after clipping to an early close.

Raises:

ValueError

If day is not an XNYS session, or its window is not a whole number of bars.

Examples

>>> request = NbboBarsRequest("1m")
>>> session = request.session(request.calendar(), date(2024, 11, 29))
>>> session.open_clock, session.close_clock, session.n_bars
(datetime.time(9, 30), datetime.time(13, 0), 210)