st-tschart

A Streamlit component for rendering interactive timeseries charts with Cognite Data Fusion (CDF) integration.

Features

• 📊 Multiple Timeseries Display: Visualize multiple timeseries on the same chart
• 🔍 Interactive Zoom & Pan: Explore your data with intuitive controls
• 📈 Min/Max Bands: Display aggregated data with min/max visualization
• 🎨 Unit Grouping: Automatically group timeseries with the same units
• 🌙 Theme Support: Inherits Streamlit's light/dark theme
• ⚡ CDF Integration: Direct integration with Cognite Data Fusion
• 📱 Responsive Design: Adapts to different screen sizes

Installation

pip install st-tschart

Quick Start

import streamlit as st
from st_tschart import timeseries_chart

# Basic usage
result = timeseries_chart(
    items=[1222, 2323, 3333],  # List of timeseries IDs
    merge_units=True,           # Group same units on same y-axis
    show_min_max=True,          # Show min/max bands
    cdf_token="your-token",     # CDF API token
    cdf_project="your-project", # CDF project name
    cdf_base_url="https://api.cognitedata.com",
    height=600                  # Chart height in pixels
)

# Access the returned data
if result:
    st.write("Selected time range:", result['timerange'])
    st.write("Timeseries metadata:", result['items'])

Parameters

Required Parameters

• items (List[Union[int, str]]): List of timeseries IDs to display
• cdf_token (str): CDF API token for authentication
• cdf_project (str): CDF project name

Optional Parameters

• merge_units (bool, default=False): Whether to merge timeseries with the same units on the same y-axis
• show_min_max (bool, default=False): Whether to show min/max bands for aggregated data
• cdf_base_url (str, default="https://api.cognitedata.com"): CDF base URL
• height (int, default=600): Height of the chart in pixels
• start_date (str, optional): Start date for the time range (ISO format)
• end_date (str, optional): End date for the time range (ISO format)
• max_data_points (int, default=1000): Maximum number of data points to fetch per timeseries
• key (str, optional): Unique component key for Streamlit

Return Value

The component returns a dictionary with two keys:

{
    'items': [...],      # List of metadata for the displayed timeseries
    'timerange': {       # The selected time range
        'start': '...',  # ISO format timestamp
        'end': '...'     # ISO format timestamp
    }
}

Development

Prerequisites

• Node.js and npm
• Python 3.9+
• uv (for Python package management)

Building from Source

1. Clone the repository:

git clone https://github.com/yourusername/st-tschart.git
cd st-tschart

2. Build the component:

./build.sh

3. Test locally:

uv run streamlit run example_app.py

Project Structure

st-tschart/
├── st_tschart/
│   ├── __init__.py           # Python package entry point
│   └── frontend/             # React frontend
│       ├── src/
│       │   ├── components/   # React components
│       │   ├── services/     # CDF client service
│       │   ├── hooks/        # React hooks
│       │   ├── types/        # TypeScript types
│       │   └── main.tsx      # Frontend entry point
│       └── package.json      # Frontend dependencies
├── example_app.py            # Example Streamlit app
├── build.sh                  # Build script
├── pyproject.toml           # Python package configuration
└── README.md                # This file

Example App

Run the example app to see the component in action:

uv run streamlit run example_app.py

The example app demonstrates:

• How to configure CDF credentials
• Adding multiple timeseries IDs
• Adjusting display options
• Handling the component's return value

Theme Integration

The component automatically inherits Streamlit's theme colors. It adapts to both light and dark themes without any additional configuration.

Troubleshooting

Component not displaying

1. Ensure CDF credentials are correctly provided
2. Verify timeseries IDs exist in your CDF project
3. Check browser console for any JavaScript errors

Build issues

1. Ensure Node.js and npm are installed
2. Run npm install in the frontend directory
3. Check that uv is installed for Python package management

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.