Series¶

`SeriesCommon`¶

SeriesCommon is the base class for all series types. The methods below are available on every series object (Line, Area, Histogram, and Candlestick).

class SeriesCommon¶

set(df: pd.DataFrame, format_cols: bool)¶

Sets the series data from a DataFrame.

If format_cols is True (default), datetime columns are converted to Unix seconds automatically.

update(series: pd.Series, historical_update: bool = False)¶

Updates the series with a single new data point.

If the timestamp of the new point matches the last bar, the last bar is overwritten. Otherwise, a new bar is appended.

When historical_update is True, the chart updates an existing bar by time instead of appending (useful when whitespace bars extend past the last real bar).

marker(time, position, shape, color, text) → str¶

Creates a single marker on the series.

time — bar timestamp (datetime, pd.Timestamp, or str). Defaults to the last bar.
position — 'above', 'below', or 'inside'.
shape — 'arrow_up', 'arrow_down', 'circle', or 'square'.
color — CSS colour string.
text — label text.

Returns a marker ID that can be passed to remove_marker().

marker_list(markers: list) → list¶

Creates multiple markers in a single call. Each element is a dict with the same keys as marker(): time, position, shape, color, text.

Returns a list of marker IDs.

remove_marker(marker_id: str)¶: Removes the marker with the given ID.

clear_markers()¶: Removes all markers from the series.

horizontal_line(price, color, width, style, text, axis_label_visible, func) → HorizontalLine¶: Creates a horizontal line at price.

trend_line(start_time, start_value, end_time, end_value, round: bool = False, color: COLOR, width: int, style: LINE_STYLE, text: str, text_position: TREND_LINE_TEXT_POSITION, text_color: COLOR) → TwoPointDrawing¶

Creates a trend line between two (time, price) coordinates.

round: When False (default), coordinates use the same Unix-second timestamps as set. Pass times from your DataFrame directly, including weekly or monthly resampled bars. When True, times are snapped to the detected bar interval.
text / text_position / text_color: Optional on-chart label. text_position can be "center" (default), "start", or "end" along the line segment.

box(start_time, start_value, end_time, end_value, round: bool = False, color: COLOR, fill_color: COLOR, width: int, style: LINE_STYLE, text: str, text_position: BOX_TEXT_POSITION, text_placement: BOX_TEXT_PLACEMENT, text_color: COLOR) → TwoPointDrawing¶

Creates a rectangular box between two (time, price) corners.

round: When False (default), coordinates use the same Unix-second timestamps as set. Pass times from your DataFrame directly, including weekly or monthly resampled bars. When True, times are snapped to the detected bar interval.
text / text_position / text_placement / text_color: Optional on-chart label.

text_position — anchor within or relative to the box edge: "center" (default), "left", "right", "top", or "bottom".
text_placement — "outside" (default) draws the label just outside the rectangle on the chosen edge; "inside" draws it within the rectangle.

Returns a TwoPointDrawing object. Update label and style options at runtime via .options().

Example:

weekly = daily.set_index("time").resample("W").agg({
    "open": "first", "high": "max", "low": "min", "close": "last",
}).reset_index()

chart.set(weekly)
chart.box(
    weekly["time"].iloc[0], weekly["low"].min(),
    weekly["time"].iloc[8], weekly["high"].max(),
    text="Support zone",
    text_position="top",
    text_placement="outside",
)

___

```{py:method} ray_line(start_time, value, ...) -> RayLine

Creates a ray line extending from a starting point.

vertical_line(time, ...) → VerticalLine¶: Creates a vertical line at time.

vertical_span(start_time, end_time, color, round)¶

Creates a vertical span (shaded region) across the chart.

Can accept a single time, a (start, end) pair, or a list of times.

price_line(label_visible, line_visible, title)¶: Configures the last-price line and label visibility.

precision(precision: int)¶: Sets the decimal precision and minimum price movement for the series.

hide_data()¶: Hides the series data from view without deleting it.

show_data()¶: Shows a previously hidden series.

legend(visible, lines, color, font_size, font_family, text, pane_index)¶: Configures the legend for the pane this series lives on.

attach_primitive(js_constructor_call: str) → AttachedPrimitive¶

Attaches a JavaScript primitive (custom drawing) to this series. The expression must construct an object implementing LWC’s ISeriesPrimitive.

Returns an AttachedPrimitive with a .detach() method.

Example:

js = """
{
    draw(target) {
        // custom WebGL/Canvas2D drawing
    }
}
"""
primitive = series.attach_primitive(f"({js})")
# later:
primitive.detach()

options() → dict¶: Returns the current series options as a dict (blocking call).

get_data() → list¶: Returns all series data as a list of dicts (blocking call).

move_to_pane(pane_index: int)¶: Moves this series to the pane at the given index.

get_pane() → Pane¶: Returns the Pane object for the pane this series lives on (blocking call).

subscribe_data_changed(func: callable)¶: Subscribes to data-change events on this series. The callable receives the series as its first argument. Async functions are supported.

unsubscribe_data_changed()¶: Unsubscribes from data-change events.

position(entry: NUM, stop: NUM, target: NUM, entry_time: TIME, end_time: TIME, stop_color: COLOR, target_color: COLOR, quantity: NUM) → PositionTool¶

Attaches a PositionTool overlay to this series. A shorthand for constructing PositionTool(series, ...) directly.

entry / stop / target — trade price levels.
entry_time — timestamp of the entry bar (left edge of overlay).
end_time — (optional) right-edge timestamp; auto-tracks latest bar if omitted.
stop_color / target_color — fill colours for the risk/reward zones.
quantity — (optional) units/contracts for monetary P&L display. Must be > 0.

Returns the created PositionTool instance.

position_list(positions: list) → list¶

Creates multiple PositionTool overlays in a single call.

Each element of positions is a dict with keys matching the parameters of position(): entry, stop, target, entry_time, and optionally end_time, stop_color, target_color, quantity.

Returns a list of PositionTool instances.

`Line`¶

class Line(name: str, color: COLOR, style: LINE_STYLE, type: LINE_TYPE, width: int, price_line: bool, price_label: bool, price_scale_id: str, last_price_animation: str, pane_index: int)

A LineSeries in Lightweight Charts. Created via chart.create_line().

Inherits all SeriesCommon methods.

last_price_animation accepts 'disabled', 'continuous', or 'one_shot'.

delete():no-index:: Irreversibly deletes the line series.

`Area`¶

class Area(name: str, top_color: COLOR, bottom_color: COLOR, line_color: COLOR, line_width: int, price_line: bool, price_label: bool, pane_index: int)¶

An AreaSeries in Lightweight Charts with gradient fill. Created via chart.create_area().

Inherits all SeriesCommon methods. Additionally, set() and update() accept per-point colour columns/keys: line_color, top_color, bottom_color (camelCase variants also accepted).

delete()¶: Irreversibly deletes the area series.

`Histogram`¶

class Histogram(name: str, color: COLOR, price_line: bool, price_label: bool, scale_margin_top: float, scale_margin_bottom: float, pane_index: int, price_scale_id: str)

A HistogramSeries in Lightweight Charts. Created via chart.create_histogram().

Inherits all SeriesCommon methods.

delete():no-index:: Irreversibly deletes the histogram series.

scale(scale_margin_top: float, scale_margin_bottom: float): Configures the histogram’s price scale margins.

`AttachedPrimitive`¶

class AttachedPrimitive(series, js_constructor_call: str)¶

Wraps a JavaScript series primitive attached via series.attach_primitive().

detach()¶: Detaches the primitive from the series.

update_options(options: dict)¶: Calls applyOptions() on the primitive, updating its configuration.

`UpDownMarkers`¶

class UpDownMarkers(chart, series, up_color: COLOR, down_color: COLOR)¶

Attaches up/down marker primitives to a series using Lightweight Charts v5’s createUpDownMarkers API. Created automatically for candlestick-type series or attached to any series manually.

detach()¶: Detaches the up/down markers from the series.

Series¶

SeriesCommon¶

Line¶

Area¶

Histogram¶

AttachedPrimitive¶

UpDownMarkers¶