Returns Estimation

This module provides tools for estimating returns based on price series and trend labels.

Estimator Classes

class tstrends.returns_estimation.SimpleReturnEstimator[source]

A simple return estimator that calculates returns based on price differences and labels.

This class implements a basic return estimation strategy by multiplying the price differences between consecutive periods with their corresponding labels. The labels indicate the position taken (-1 for short, 0 for no position, 1 for long).

Example

>>> prices = [100.0, 101.0, 99.0]
>>> labels = [1, 1, -1]
>>> estimator = SimpleReturnEstimator()
>>> return_value = estimator.estimate_return(prices, labels)
>>> print(return_value)
2.0

In this example, the return is calculated as follows: (101.0 - 100.0) * 1 + (99.0 - 101.0) * -1 = 2.0

estimate_return(prices, labels)[source]

Estimate the return based on price differences and labels.

Parameters:

  • prices (list[float]) – A list of historical prices

  • labels (list[int]) – A list of position labels (-1, 0, or 1)

Returns:

The estimated return

Return type:

float

class tstrends.returns_estimation.ReturnsEstimatorWithFees(fees_config=None)[source]

A return estimator that incorporates transaction and holding fees into return calculations.

This class extends the SimpleReturnEstimator by adding various types of fees that impact the overall return calculation. The goal of these fees is twofold: 1. To account for the cost of entering and exiting positions in real life, as well as maintaining positions 2. Act as a form of regularization to prevent overfitting the prices fluctuations, either by identifying ultrashort term trends or overextending trends over neutral periods.

Transaction Fees:

  • Long Position (lp) Transaction Fees: Applied when introducing a positive (upward trend) label

  • Short Position (sp) Transaction Fees: Applied when introducing a negative (downward trend) label

Holding Fees:

  • Long Position (lp) Holding Fees: Ongoing fees charged for maintaining a positive (upward trend) label

  • Short Position (sp) Holding Fees: Ongoing fees charged for maintaining a negative (downward trend) label

All fees are expressed as percentages of the position value.

The return calculation will:

  1. Include the basic price movement returns

  2. Subtract transaction fees when positions change

  3. Subtract daily holding fees based on position type

Parameters:

fees_config (FeesConfig | None)

fees_config

Configuration for transaction and holding fees

Type:

FeesConfig

__init__(fees_config=None)[source]

Initialize the estimator with fees configuration.

Parameters:

fees_config (FeesConfig, optional) – Configuration for transaction and holding fees. If None, creates a config with zero fees.

estimate_return(prices, labels)[source]

Estimate the return based on price differences and labels, and include fees cost if it is not zero.

Parameters:

  • prices (Sequence[float]) – A sequence of historical prices

  • labels (list[int]) – A list of position labels (-1, 0, or 1)

Returns:

The estimated return

Return type:

float

Configuration

class tstrends.returns_estimation.FeesConfig(lp_transaction_fees=0.0, sp_transaction_fees=0.0, lp_holding_fees=0.0, sp_holding_fees=0.0)[source]

Configuration for transaction and holding fees.

This class provides a structured way to configure various types of fees that impact return calculations. It includes both transaction fees (applied when positions change) and holding fees (applied for maintaining positions).

Parameters:

  • lp_transaction_fees (float)

  • sp_transaction_fees (float)

  • lp_holding_fees (float)

  • sp_holding_fees (float)

lp_transaction_fees

Transaction fee percentage for long positions

Type:

float

sp_transaction_fees

Transaction fee percentage for short positions

Type:

float

lp_holding_fees

Daily absolute holding fee for long positions

Type:

float

sp_holding_fees

Daily absolute holding fee for short positions

Type:

float

Example

>>> fees_config = FeesConfig(
...     lp_transaction_fees=0.001,  # 0.1% fee for long position transactions
...     sp_transaction_fees=0.002,  # 0.2% fee for short position transactions
...     lp_holding_fees=0.0005,    # 0.05% daily fee for holding long positions
...     sp_holding_fees=0.0008     # 0.08% daily fee for holding short positions
... )
lp_transaction_fees: float = 0.0
sp_transaction_fees: float = 0.0
lp_holding_fees: float = 0.0
sp_holding_fees: float = 0.0
__post_init__()[source]

Validate the fees configuration and convert integers to floats.

__init__(lp_transaction_fees=0.0, sp_transaction_fees=0.0, lp_holding_fees=0.0, sp_holding_fees=0.0)
Parameters:

  • lp_transaction_fees (float)

  • sp_transaction_fees (float)

  • lp_holding_fees (float)

  • sp_holding_fees (float)

Return type:

None

tstrends.returns_estimation.FeesConfig.lp_transaction_fees
tstrends.returns_estimation.FeesConfig.sp_transaction_fees
tstrends.returns_estimation.FeesConfig.lp_holding_fees
tstrends.returns_estimation.FeesConfig.sp_holding_fees