st-link-analysis 0.4.0

A streamlit custom component for visualizing and interacting with graphs

st-link-analysis

A custom Streamlit component for link analysis, built with Cytoscape.js and Streamlit.

Overview

This project provides a Streamlit custom component for visualizing and interacting with graph data using Cytoscape.js. It supports customizable edge and node styles, labels, colors, captions, and icons.

Demo

A demo deployed with Render can be accessed here.

Features

• Customizable Node and Edge Styles: Easily define the appearance of nodes and edges using a variety of style options.
• Material Icons Support: Supports a subset of Material icons for styling nodes which can be passed by name (e.g., icon='person'). Custom icons can still be used by passing a URL (e.g., icon='url(...)').
• Customizable Layouts: Choose from different layout algorithms to arrange the graph elements.
• Interactive Features:
  • Toolbar with fullscreen, JSON export, and layout refresh buttons.
  • View control bar for zooming, fitting, and centering the view, making it easier to navigate your graphs.
  • View all properties of the selected elements in a side panel.
  • Highlights neighboring nodes or edges when an element is selected.
• Node Actions (Expand / Remove): Enable node removal and expansion using the node_actions parameter. Removal can be triggered by a delete keydown or a remove button click, while expansion occurs on a double-click or expand button click. When these events are triggered, the event details and selected node IDs are sent back to the Streamlit app as the component's return value.

Installation

To install the package, use pip:

pip install st-link-analysis

Usage

Here is a basic example of how to use the component in your Streamlit app:

import streamlit as st
from st_link_analysis import st_link_analysis, NodeStyle, EdgeStyle

st.set_page_config(layout="wide")

# Sample Data
elements = {
    "nodes": [
        {"data": {"id": 1, "label": "PERSON", "name": "Streamlit"}},
        {"data": {"id": 2, "label": "PERSON", "name": "Hello"}},
        {"data": {"id": 3, "label": "PERSON", "name": "World"}},
        {"data": {"id": 4, "label": "POST", "content": "x"}},
        {"data": {"id": 5, "label": "POST", "content": "y"}},
    ],
    "edges": [
        {"data": {"id": 6, "label": "FOLLOWS", "source": 1, "target": 2}},
        {"data": {"id": 7, "label": "FOLLOWS", "source": 2, "target": 3}},
        {"data": {"id": 8, "label": "POSTED", "source": 3, "target": 4}},
        {"data": {"id": 9, "label": "POSTED", "source": 1, "target": 5}},
        {"data": {"id": 10, "label": "QUOTES", "source": 5, "target": 4}},
    ],
}

# Style node & edge groups
node_styles = [
    NodeStyle("PERSON", "#FF7F3E", "name", "person"),
    NodeStyle("POST", "#2A629A", "content", "description"),
]

edge_styles = [
    EdgeStyle("FOLLOWS", caption='label', directed=True),
    EdgeStyle("POSTED", caption='label', directed=True),
    EdgeStyle("QUOTES", caption='label', directed=True),
]

# Render the component
st.markdown("### st-link-analysis: Example")
st_link_analysis(elements, "cose", node_styles, edge_styles)

API Reference

Element	Description
st_link_analysis	Main component for creating and displaying the graph, including layout and height settings. Refer to docstring.
NodeStyle	Defines styles for nodes, including labels, colors, captions, and icons. Refer to docstring.
EdgeStyle	Defines styles for edges, including curve styles, labels, colors, and directionality. Refer to docstring.
Event	Define an event to pass to component function and listen to. Use sparingly Refer to docstring.

Development

• Ensure you have Python 3.9+, Node.js, and npm installed.
• Clone this repository
• Navigate to root directory

Python Setup

Create and activate a virtual environment, then install the package in editable mode:

python3 -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
pip install -e ".[dev]"

Node Setup

Navigate to the frontend directory and install the necessary npm packages:

cd st_link_analysis/frontend
npm install

Running the App

Change RELEASE flag in st_link_analysis/component/component.py to False.

In one terminal start the frontend dev server

cd st_link_analysis/frontend
npm run start

In another terminal run the streamlit server

cd examples
streamlit run app.py

Testing

Run linting, type checking, and tests:

ruff check
mypy st_link_analysis/
pytest

Type Checking

This project uses type hints and mypy for static type checking to improve code maintainability and developer experience. The mypy configuration is defined in pyproject.toml with strict settings to catch potential type-related issues early.

To run type checking locally:

mypy st_link_analysis/

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• Cytoscape.js
• Streamlit
• Material Icons