Adding Data to Charts

LightningChart Python provides multiple flexible methods for adding and managing data in your charts. This guide covers all data addition approaches from simple coordinate pairs to complex real-time scenarios.

Basic Data Addition Methods

Single Data Points

Add individual samples one at a time:

import lightningchart as lc

chart = lc.ChartXY()
series = chart.add_line_series()

# Add single points
series.append_sample(x=0, y=10)
series.append_sample(x=1, y=15)
series.append_sample(x=2, y=8)

# Or using dictionary format
series.append_sample(sample={'x': 3, 'y': 12})

Multiple Data Points

Add arrays of data efficiently:

# Method 1: Using add() with separate arrays
series.add(
    x=[0, 1, 2, 3, 4],
    y=[10, 15, 8, 12, 20]
)

# Method 2: Using add() with data array
series.add([
    {'x': 0, 'y': 10},
    {'x': 1, 'y': 15},
    {'x': 2, 'y': 8}
])

# Method 3: Using add_dict_data()
series.add_dict_data([
    {"x": 0, "y": 10},
    {"x": 1, "y": 15},
    {"x": 2, "y": 8}
])

# Method 4: Using append_samples() with parameters
series.append_samples(
    x_values=[0, 1, 2, 3, 4],
    y_values=[10, 15, 8, 12, 20]
)

# Method 5: Using samples dictionary
series.append_samples(samples={
    'xValues': [0, 1, 2, 3, 4],
    'yValues': [10, 15, 8, 12, 20]
})

# Method 6: Progressive data (auto-generate X values)
series.append_samples(
    y_values=[10, 15, 8, 12, 20],
    start=100,  # Start X at 100
    step=5      # Increment X by 5
)
# Results in: (100,10), (105,15), (110,8), (115,12), (120,20)

Adding timestamp data

# Create a list of x and y values.
x_values = [
    '2025-11-03T00:00:00',
    '2025-11-04T00:00:00',
    '2025-11-05T00:00:00',
    '2025-11-06T00:00:00',
]
y_values = [1, 2, 3, 4]

# Add data to the series.
series.add(x_values, y_values)

When using timestamps, you generally want to also set up a Date-Time Axis.

Replace All Data

Replace entire dataset:

series.set_samples(samples={
    'xValues': [0, 1, 2, 3, 4],
    'yValues': [10, 15, 8, 12, 20],
    'colors': ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff']
})
series.set_individual_point_color_enabled(True)

Data Offset and Slicing

Control which portions of your data arrays are used with offset and count parameters:

# Skip first 2 values and use next 3 values
series.set_samples(
    samples={
        'xValues': [10, 11, 12, 13, 14, 15],
        'yValues': [1, 2, 3, 4, 5, 6],
        'colors': ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff', '#00ffff'],
        'sizes': [10, 11, 12, 13, 14, 15]
    },
    offset=2,  # Skip first 2 values
    count=3    # Use only 3 values after offset
)
series.set_individual_point_color_enabled(True)
# Results in: (12,3), (13,4), (14,5) with corresponding colors and sizes

These parameters work with both set_samples() and append_samples():

# Append data with offset
series.append_samples(
    samples={
        'xValues': [0, 1, 2, 3, 4, 5, 6],
        'yValues': [5, 10, 15, 20, 25, 30, 35]
    },
    offset=1,  # Skip first value
    count=4    # Use 4 values after offset
)
# Adds: (1,10), (2,15), (3,20), (4,25)

Combine with progressive data generation:

# Use only part of Y values array with auto-generated X values
series.append_samples(
    samples={
        'yValues': [8, 12, 16, 20, 24, 28]
    },
    start=0,   # X starts at 0
    step=2,    # X increments by 2
    offset=1,  # Skip first Y value
    count=3    # Use 3 Y values
)
# Results in: (0,12), (2,16), (4,20)

Dictionary Data Format

Using add_dict_data()

The add_dict_data() method provides a clean way to add data using dictionary format:

# Single data point
series.add_dict_data({"x": 0, "y": 10})

# Multiple data points
series.add_dict_data([
    {"x": 0, "y": 10},
    {"x": 1, "y": 15},
    {"x": 2, "y": 8}
])

Advanced Data Modification

Alter Samples by Match

Target specific data points for modification:

# Modify samples where x=1 and x=3
series.alter_samples_by_match(
    match_key='xValues',
    match_values=[1, 3],
    y_values=[25, 35],  # New Y values for matched points
    colors=['purple', 'orange']
)

Advanced Data Features

Colored Data Points

series.append_samples(
    x_values=[0, 1, 2, 3],
    y_values=[10, 15, 8, 12],
    colors=['#ff0000', '#00ff00', '#0000ff', '#ffff00']
)

Variable Point Sizes

series.append_samples(
    x_values=[0, 1, 2, 3],
    y_values=[10, 15, 8, 12],
    sizes=[5, 10, 15, 20]  # Different sizes for each point
)

Point Rotations and Lookup Values

series.append_samples(
    x_values=[0, 1, 2, 3],
    y_values=[10, 15, 8, 12],
    rotations=[0, 45, 90, 135],  # Rotation in degrees
    lookup_values=[100, 200, 300, 400],  # For color mapping
    ids=[1, 2, 3, 4]  # Custom identifiers
)

Modifying Existing Data

Alter Specific Data Points

# Alter samples starting from index 3
series.alter_samples(
    index=3,
    y_values=[30],  # Change y value of sample at index 3
    colors=["#aa00ff"],  # Change color of sample at index 3
    sizes=[15]  # Change size of sample at index 3
)

Schema-Based Data Management

Define data structure for flexible mapping:

series = chart.add_point_line_series(
    colors=True,
    sizes=True,
    schema={
        'time': {'pattern': None},
        'value': {'storage': 'Float32Array'},
        'pointColor': {},
        'pointSize': {}
    }
)

# Enable individual colors first
series.set_individual_point_color_enabled(True)

# Set data mapping before adding data
series.set_data_mapping({'x': 'time', 'y': 'value', 'color': 'pointColor', 'size': 'pointSize'})

# Then append samples
series.append_samples({
    'time': [1, 2, 3, 4],
    'value': [5, 7, 3, 9],
    'pointColor': [(255, 0, 0), "#00ff00", "#0000ff", "yellow"],
    'pointSize': [15, 5, 10, 20]
})

JSON Data Format

Add data from JSON-like structures:

series = chart.add_point_series(colors=True, sizes=True)
series.set_individual_point_color_enabled(True)
series.set_data_mapping({
    'x': 'timestamp',
    'y': 'temperature',
    'color': 'color',
    'size': 'size'
})
data = [
    {"timestamp": 0, "temperature": 20, "color": "#ff0000", "size": 15},
    {"timestamp": 1, "temperature": 25, "color": "#00ff00", "size": 18},
    {"timestamp": 2, "temperature": 22, "color": "#0000ff", "size": 12}
]
series.append_json(data)

3D Data

For 3D series, add XYZ coordinates:

chart3d = lc.Chart3D()
series3d = chart3d.add_point_series()

# Add 3D coordinates
series3d.add(
    x=[0, 1, 2, 3],
    y=[10, 15, 8, 12],
    z=[5, 8, 3, 7]
)

# Or using data array
series3d.add([
    {'x': 0, 'y': 10, 'z': 5},
    {'x': 1, 'y': 15, 'z': 8},
    {'x': 2, 'y': 8, 'z': 3}
])


# add data using add_dict_data:
series3d.add_dict_data([
    {'x': 0, 'y': 10, 'z': 5},
    {'x': 1, 'y': 15, 'z': 8},
    {'x': 2, 'y': 8, 'z': 3}
])

Heatmap Data

For heatmap series, add intensity matrices:

chart = lc.ChartXY()
heatmap = chart.add_heatmap_grid_series(rows=8, columns=8)

# Add intensity values as 2D matrix
intensity_data = [
    [10, 15, 20, 25],
    [12, 18, 22, 28],
    [8, 12, 16, 20],
    [14, 19, 24, 29]
]

heatmap.invalidate_intensity_values(intensity_data)

# Update specific regions
heatmap.invalidate_intensity_values(
    data=[[30, 35], [32, 37]],
    column_index=0,
    row_index=0
)

heatmap.set_palette_coloring(
    steps=[
        {'value': 0, 'color': (0, 128, 255)},
        {'value': 20, 'color': (0, 255, 0)},
        {'value': 40, 'color': (255, 128, 0)},
    ],
    look_up_property='value',
    percentage_values=False,
)

Surface Grid Data

For surface and scrolling grid series:

chart = lc.Chart3D(title='3D Surface Grid', theme=lc.Themes.Light)
surface = chart.add_surface_grid_series(columns=4, rows=3)

# Position and grid step
surface.set_start(x=0, z=0).set_end(x=3, z=2)
surface.set_step(x=1, z=1)

# Provide varying height and intensity data
surface.invalidate_height_map(y_matrix)
surface.invalidate_intensity_values(intensity_matrix)

Performance Optimization

Memory Management

# Enable automatic data grouping for dense data
series = chart.add_line_series(allow_data_grouping=True)

# Control maximum samples
series.set_max_sample_count(max_sample_count=100, automatic=False)

# Enable automatic data cleaning to manage memory
series.enable_data_cleaning(True)  # Available for scrolling heatmap, area and area range series