GroupedLiquidityUniverse#

API documentation for tradingstrategy.liquidity.GroupedLiquidityUniverse Python class in Trading Strategy framework.

class GroupedLiquidityUniverse[source]#

Bases: PairGroupedUniverse

A universe where each trading pair has its own liquidity data feed.

This is helper class to create foundation for multi pair strategies.

For the data logistics purposes, all candles are lumped together in single columnar data blobs. However, it rarely makes sense to execute operations over different trading pairs. :py:class`GroupedLiquidityUniverse` creates trading pair id -> liquidity sample data grouping out from raw liquidity sample.

__init__(df, time_bucket=TimeBucket.d1, timestamp_column='timestamp', index_automatically=True, forward_fill=False)[source]#

Set up new candle universe where data is grouped by trading pair.

Parameters:

  • df (DataFrame) – DataFrame backing the data.

  • time_bucket –

    What bar size candles we are operating at. Default to daily.

    TODO: Currently not used. Will be removed in the future versions.

  • timestamp_column – What column use to build a time index. Used for QStrader / Backtrader compatibility.

  • index_automatically – Convert the index to use time series. You might avoid this with QSTrader kind of data.

  • fix_wick_threshold –

    Apply abnormal high/low wick fix filter.

    Percent value of maximum allowed high/low wick relative to close. By default fix values where low is 90% lower than close and high is 90% higher than close.

    See fix_bad_wicks() for more information.

  • bad_open_close_threshold – See fix_bad_wicks().

  • primary_key_column – The pair/reserve id column name in the dataframe.

  • remove_zero_candles –

    Remove candles with zero values for OHLC.

    To deal with abnormal data.

  • forward_fill –

    Forward-will gaps in the data.

    See forward fill and forward filling data for more information.

Methods

__init__(df[, time_bucket, ...])

Set up new candle universe where data is grouped by trading pair.

clear_cache()

Clear candles cached by pair.

create_empty()

Create a liquidity universe without any data.

create_from_multiple_candle_dataframes(dfs)

Construct universe based on multiple trading pairs.

create_from_single_pair_dataframe(df[, bucket])

Construct universe based on a single trading pair data.

forward_fill([columns, drop_other_columns])

Forward-fill sparse OHLCV candle data.

get_all_pairs()

Go through all liquidity samples, one DataFrame per trading pair.

get_all_samples_by_range(start, end)

Get list of candles/samples for all pairs at a certain range.

get_all_samples_by_timestamp(ts)

Get list of candles/samples for all pairs at a certain timepoint.

get_closest_liquidity(pair_id, when[, kind, ...])

Get the available liuqidity for a trading pair at a specific timepoint or some candles before the timepoint.

get_columns()

Get column names from the underlying pandas.GroupBy object

get_last_entries_by_pair_and_timestamp(pair, ...)

Get samples for a single pair before a timestamp.

get_liquidity_samples_by_pair(pair_id)

Get samples for a single pair.

get_liquidity_with_tolerance(pair_id, when, ...)

Get the available liquidity for a trading pair at a specific time point/

get_pair_count()

Return the number of pairs in this dataset.

get_pair_ids()

Get all pairs present in the dataset

get_prior_timestamp(ts)

Get the first timestamp in the index that is before the given timestamp.

get_sample_count()

Return the dataset size - how many samples total for all pairs

get_samples_by_pair(pair_id)

Get samples for a single pair.

get_single_pair_data([timestamp, ...])

Get all candles/liquidity samples for the single alone pair in the universe by a certain timestamp.

get_single_value(asset_id, when, ...[, ...])

Get a single value for a single pair/asset at a specific point of time.

get_timestamp_range([use_timezone])

Return the time range of data we have for.

iterate_samples_by_pair_range(start, end)

Get list of candles/samples for all pairs at a certain range.

Attributes

__init__(df, time_bucket=TimeBucket.d1, timestamp_column='timestamp', index_automatically=True, forward_fill=False)[source]#

Set up new candle universe where data is grouped by trading pair.

Parameters:

  • df (DataFrame) – DataFrame backing the data.

  • time_bucket –

    What bar size candles we are operating at. Default to daily.

    TODO: Currently not used. Will be removed in the future versions.

  • timestamp_column – What column use to build a time index. Used for QStrader / Backtrader compatibility.

  • index_automatically – Convert the index to use time series. You might avoid this with QSTrader kind of data.

  • fix_wick_threshold –

    Apply abnormal high/low wick fix filter.

    Percent value of maximum allowed high/low wick relative to close. By default fix values where low is 90% lower than close and high is 90% higher than close.

    See fix_bad_wicks() for more information.

  • bad_open_close_threshold – See fix_bad_wicks().

  • primary_key_column – The pair/reserve id column name in the dataframe.

  • remove_zero_candles –

    Remove candles with zero values for OHLC.

    To deal with abnormal data.

  • forward_fill –

    Forward-will gaps in the data.

    See forward fill and forward filling data for more information.

get_liquidity_samples_by_pair(pair_id)[source]#

Get samples for a single pair.

Returns:

If the pair does not exist return None.

Parameters:

pair_id (int) –

Return type:

Optional[DataFrame]

get_liquidity_with_tolerance(pair_id, when, tolerance, kind='close')[source]#

Get the available liquidity for a trading pair at a specific time point/

The liquidity is defined as one-sided as in XY liquidity model.

Example:

liquidity_amount, last_trade_delay = liquidity_universe.get_liquidity_with_tolerance(
sushi_usdt.pair_id,
    pd.Timestamp("2021-12-31"),
    tolerance=pd.Timedelta("1y"),
)
assert liquidity_amount == pytest.approx(2292.4517)
assert last_trade_delay == pd.Timedelta('4 days 00:00:00')
Parameters:

  • pair_id (int) – Trading pair id

  • when (Timestamp) – Timestamp to query

  • kind – One of OHLC data points: “open”, “close”, “low”, “high”

  • tolerance (Timedelta) – If there is no liquidity sample available at the exact timepoint, look to the past to the get the nearest sample. For example if candle time interval is 5 minutes and look_back_timeframes is 10, then accept a candle that is maximum of 50 minutes before the timepoint.

Returns:

Return (price, delay) tuple.

We always return a price. In the error cases an exception is raised. The delay is the timedelta between the wanted timestamp and the actual timestamp of the candle.

Candles are always timestamped by their opening.

Raises:

LiquidityDataUnavailable –

There were no samples available with the given condition.

This can happen when

  • There has not been a single trade yet

  • There hasn’t been any trades since tolerance time window

Return type:

Tuple[float, Timedelta]

get_closest_liquidity(pair_id, when, kind='open', look_back_time_frames=5)[source]#

Get the available liuqidity for a trading pair at a specific timepoint or some candles before the timepoint.

The liquidity is defined as one-sided as in XY liquidity model.

Warning

This is an early alpha method and has been deprecated. Please use get_liquidity_with_tolerance() instead.

Parameters:

  • pair_id (int) – Traing pair id

  • when (Timestamp) – Timestamp to query

  • kind – One of liquidity samples: “open”, “close”, “low”, “high”

  • look_back_timeframes – If there is no liquidity sample available at the exact timepoint, look to the past to the get the nearest sample

Returns:

We always return

Raises:

LiquidityDataUnavailable – There was no liquidity sample available

Return type:

float

static create_empty()[source]#

Create a liquidity universe without any data.

Return type:

GroupedLiquidityUniverse