API Reference

class swingtrend.Swing(retrace_threshold_pct: float | None = 5.0, sideways_threshold: int = 20, minimum_bar_count: int = 40, debug=False)

A class to help determine the current trend of an Stock.

Parameters:

  • retrace_threshold_pct (float or None) – Default 5.0. Minimum retracement required to qualify a Change of Character (CoCh) level. If None, all retracements qualify.

  • sideways_threshold (int) – Default 20. Minimum number of bars after which the trend is considered range-bound or sideways.

  • minimum_bar_count (int) – Default 40. Minimum number of bars required to accurately determine trend.

  • debug (bool) – Default False. Print additional logs for debug purposes.

identify(date, high: float, low: float, close: float) → None

Identify the trend with the current OHLC data.

Parameters:

  • date (str or datetime) – datetime of the candle

  • high (float) – Candle high

  • low (float) – Candle low

  • close (float) – Candle close

pack() → dict

Get the dictionary representation of the class for serialization purposes.

Used to store the current state of the class, so as to resume later

reset() → None

Reset all properties. Used when switching to a different stock / symbol.

run(sym: str, df, plot_lines=False, add_series=False)

Iterates through the DataFrame and determines the current trend of the instrument.

Optionally it also records CoCh levels for plotting in Matplotlib. Use plot_lines.

To add the current trend data to the pandas Dataframe, use add_series

Parameters:

  • sym (str) – Symbol name of the instrument.

  • df (pandas.DataFrame) – DataFrame containing OHLC data with DatetimeIndex

  • plot_lines (bool) – Default False. Generate line data marking CoCh levels to plot in Matplotlib

  • add_series (bool) – Default False. If True, adds a TREND and IS_SIDEWAYS column to the DataFrame. 1 if TREND is UP or in sideways range, 0 otherwise.

unpack(data: dict) → None

Update the class with data from the dictionary.

Used to restore a previously saved state and resume operations.

Parameters:

data (dict) – Dictionary data obtained from Swing.pack.

property bars_since: int

Added in version 2.0.0.

Bar count since last swing high or low.

Type:

int

property is_sideways: bool

Added in version 2.0.0.

Is the instrument range bound or in a sideways trend?

The instrument is considered sideways, if the number of bars since the last SPH or SPL was formed exceeds Swing.sideways_threshold

Note swing.trend can be UP or DOWN and still be sideways. The trend changes only on breakout or reversal.

If a breakout or trend reversal occurs, the bar count is reset to 0, until a new SPH or SPL is formed.

Type:

bool

property is_trend_stable: bool

Added in version 2.0.0.

Have enough bars been accumulated to accurately determine the trend?

Type:

bool

property leg_count: int

Added in version 2.0.1.

Number of swing legs, the trend has completed.

  • Reset to zero on trend reversal.

  • Incremented on break of structure.

property retrace_threshold_pct: float | None

Retrace threshold percent. Minimum retracement required to qualify a Change of Character (CoCh) level.

Setter:

Sets the retrace threshold percent

Type:

float or None

Swing Class Properties

on_reversal: Callable or None

A optional function or class method that is called when a trend reversal occurs.

Swing.on_reversal has the below signature:

def on_reversal(cls: Swing, date, close: float, reversal_level: float)

Parameters:

cls - The Swing class instance which provides access to all its properties and methods.

date - The bar date on which the reversal occured.

close - The closing price of the reversal bar.

reversal_level - The coc price level that was broken.

on_breakout: Callable or None

A optional function or class method that is called when a Break of Structure (BOS) or breakout/breakdown occurs.

Swing.on_breakout has the below signature.

def on_breakout(cls: Swing, date, close: float, breakout_level: float)

Parameters:

cls - The Swing class instance which provides access to all its properties and methods.

date - The bar date on which the breakout occured.

close - The closing price of the breakout bar.

breakout_level - The breakout price or SPH/SPL level that was broken.

symbol: str or None

The current symbol name if passed during Swing.run.

df: pandas.DataFrame or None

pandas.DataFrame if passed during Swing.run.

trend: str or None

The current trend as UP or DOWN. Set to None, if too few candles were supplied.

sph: float or None

The current swing point high. Set to None, if trend is Down or sph not yet formed.

spl: float or None

The current swing point low. Set to None, if trend is UP or spl not yet formed.

coc: float or None

Change of Character. It represents the trend reversal level. If trend is None, coc is None.

high: float or None

The highest price reached within the current structure. Reset to None, when SPL is formed or a trend reversal has occured.

low: float or None

The lowest price reached within the current structure. Reset to None, when SPH is formed or a trend reversal has occured.

Note regarding dates

Swing class does not perform any datetime operations.

All properties below are based on the input type. If you passed a str or timestamp or datetime, the same type is returned for the properties.

sph_dt: datetime or None

Date of SPH candle formation.

spl_dt: datetime or None

Date of SPL candle formation.

coc_dt: datetime or None

Date of coc candle.

low_dt: datetime or None

Candle date with lowest price in the current structure.

high_dt: datetime or None

Candle date with highest price in the current structure.