# SocialED: a unified toolkit for social event detection

> SocialED is a Python library that gathers social event detection research into one API: nineteen detection algorithms, fifteen datasets and a single interface modelled on the PyOD and PyGOD outlier detection libraries. It is built on PyTorch and DGL, and its dependency list is the main thing to read before installing it.

**RingBDStack/SocialED** — A python library for social event detection

- Repository: https://github.com/RingBDStack/SocialED
- Website: https://github.com/ChenBeici/SocialED_datasets
- Stars: 593 · Forks: 45
- Language: Python
- License: BSD-2-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ringbdstack-socialed

## What social event detection is, and what the library is for

Social event detection is the research area of automatically identifying and analysing events from social media platforms, covering event types from natural disasters to viral phenomena, and using that social data to understand real world events.

The library exists because of a gap that is easy to underestimate. The project notes put it plainly: despite the significant advances in detection methods, deploying these approaches or running comparative evaluations has remained challenging because there is no unified framework. Every method has its own data format, its own preprocessing and its own evaluation script, so comparing two papers means writing both pipelines.

SocialED is the attempt to fix that. It is described as an all-in-one toolkit that offers nineteen detection algorithms, fifteen diverse datasets, and a unified API with detailed documentation. The API design is deliberately borrowed rather than invented: the library is developed on top of DGL and PyTorch and follows the API design of PyOD and PyGOD, the two outlier detection libraries, which is a decision worth understanding because it is what makes the library familiar to anyone who has used those.

The upstream applications the project names are crisis management, public opinion monitoring, fake news detection and more, and the datasets are described as covering platforms such as Twitter and Facebook.

## From LDA to graph neural networks, in one interface

The nineteen algorithms span three generations of method, and the individual descriptions in the project notes are worth skimming because they show the range.

The classical end includes LDA, a generative statistical model that explains sets of observations through unobserved groups, and it is useful for discovering the hidden thematic structure in large text corpora. The embedding models include Word2Vec, a family of models that generate word embeddings by training shallow networks to predict word context, and GLOVE, which aggregates global word and co-occurrence statistics from a corpus. WMD, the Word Mover's Distance, measures the semantic distance between two documents by computing the minimum distance words from one document need to travel to match the words of another, grounded in the idea of embeddings. BERT is the transformer encoder, pre-training deep bidirectional representations.

The graph based end is where the recent work sits, with KPGNN, QSGNN, FinEvent and HISEvent named as the specialised techniques the library integrates. A social event is a set of posts and their relationships, so a graph is the natural representation, and the newer detectors work on that structure rather than on the text alone.

The claim to check is whether the unified interface is genuinely uniform or only nominally so. With methods this different, the shared API is probably uniform in the training and prediction contract and less uniform in what you can configure, and the per-algorithm documentation is where you will find out.

## Modular components and a shared training interface

Three capabilities are listed as the key ones. There is preprocessing, covering graph construction and tokenization, which is the part that every method needs and that nobody wants to write twice. There are standardised interfaces for training and prediction, so an algorithm can be swapped without rewriting the loop around it. And there is an easy-to-extend modular architecture, with the project noting that the components of each algorithm are customisable so users can adjust models to specific needs.

That last point is the one that separates this from a thin wrapper collection. If each algorithm exposes its components, then a researcher can replace a graph encoder or a classifier and keep the rest, which is how the library supports the claim of emerging methods being added continuously rather than occasionally.

The deep learning framework integration is also real rather than decorative. The library is built on PyTorch and DGL, and it supports both CPU and GPU, and the requirements name torch and torch_geometric and dgl as the core stack, with the graph construction step in the preprocessing sitting directly on DGL's graph abstractions. The practical consequence is that a dataset is fed in as a graph and the rest of the pipeline is ordinary PyTorch training.

## Installing it, and what the dependencies demand

The project recommends pip, and the two commands are the whole story for most people:
```bash
   pip install SocialED           # normal install
   pip install --upgrade SocialED  # or update if needed
```
There is a second route for working from a clone, which sets up a conda environment first:
```bash
    # Set up the environment
    conda create -n SocialED python=3.8
    conda activate SocialED

    # Installation
    git clone https://github.com/RingBDStack/SocialED.git
    cd SocialED
    pip install -r requirements.txt
    pip install .
```
The declared requirements are Python 3.8 or newer, NumPy 1.24.3 or newer, scikit-learn 1.2.2 or newer, SciPy 1.10.1 or newer, NetworkX 2.3 or newer, torch 2.3.0 or newer, torch_geometric 2.5.3 or newer, and DGL 0.6.0 or newer.

The requirements file is where the real cost shows. It pins everything exactly, and the pins include a CUDA 11 build of DGL alongside a CUDA 11 build of the NVIDIA libraries and the corresponding CUDA 12 packages, plus faiss-gpu and bitsandbytes, which are GPU libraries that will not install on a machine without a matching CUDA setup. So the summary list above and the actual install are very different in weight, and anyone without a GPU should read the file before running the second route.

## The package layout and the documentation

The source tree follows the shape of the API. Inside the SocialED package there is a datasets directory, a detector directory, a utils directory, a tests directory and a metrics directory, which maps directly onto the four things a user does: load a dataset, pick a detector, prepare the data, and score the result.

Packaging is done with setup.py and setup.cfg, with the requirements read straight out of the requirements file and passed to the install_requires argument, and the long description taken from the project overview file with its markdown content type declared. The package is marked as operating system independent and the python requirement is expressed as 3.8 or newer.

Documentation is built with readthedocs, and there is a readthedocs configuration at the repository root along with an environment file for conda and a contributors file. The homepage is not the repository itself but a separate repository holding the datasets, which is a sensible split: the code is a package, and the data is a large set of files that deserve their own home and their own versioning.

The research pedigree is visible too. The project reports a best demo paper award at APWeb-WAIM 2025, and it links to a Springer chapter, so the library has been through a peer review process of a sort, which is not nothing for a research tool.

## Where the licence and the metadata disagree

There is a discrepancy worth flagging before you build on this. The repository is recorded under the BSD-2-Clause licence, and the repository contains a licence file, but the packaging metadata declares a different one. The classifier in the setup file reads:
```python
    classifiers=[
        'Programming Language :: Python :: 3.8',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
```
MIT and BSD-2-Clause are similar in spirit and quite different in their notice requirements, so this is not a nitpick if you redistribute the library or bundle it into a product. The file in the repository root is the one that carries the actual terms, and the classifier looks like it was not updated when the licensing changed.

The release history is steady rather than fast, with 1.1.7 published on 2025-07-27 and 1.1.5 on 2025-02-21, and the last push to the repository on 2026-10-02, which is months after the last release. A library that is still below version two, with a research dependency stack and a licence label that needs checking, is a dependency to vendor carefully rather than to wire into something you cannot easily rebuild.

## Conclusion

SocialED suits a researcher who wants to compare event detection methods without writing the data plumbing for each of them, since the unified API and the shared dataset loaders are the point of the project and the fifteen datasets would otherwise be a week of work on their own. It is the wrong choice for a production service, because the dependency stack is a research stack, with a pinned requirements file that includes exact CUDA build numbers for two different major versions, and a library version still below two. Before you install, read the requirements file rather than the summary list, because the two do not say the same thing about how heavy the install is, and check the licence file, since the repository is under BSD-2-Clause while the packaging metadata declares MIT, which is the kind of discrepancy worth resolving before you redistribute anything. The current release is 1.1.7 and the last push was on 2026-10-02.

## FAQ

### How do I install SocialED?

With pip, using pip install SocialED, or pip install --upgrade SocialED to update. Working from a clone, the documented route creates a conda environment with python=3.8, clones the repository, installs requirements.txt and then runs pip install in the project directory.

### What does SocialED require as dependencies?

Python 3.8 or newer, numpy 1.24.3 or newer, scikit-learn 1.2.2 or newer, scipy 1.10.1 or newer, networkx 2.3 or newer, torch 2.3.0 or newer, torch_geometric 2.5.3 or newer and dgl 0.6.0 or newer. The requirements file pins exact versions, including CUDA 11 build packages, faiss-gpu and bitsandbytes.

### How many algorithms and datasets does SocialED include?

Nineteen detection algorithms and fifteen diverse datasets. The algorithm list runs from classic methods such as LDA and BiLSTM through the embedding models Word2Vec, GLOVE, WMD and BERT to graph based detectors including KPGNN, QSGNN, FinEvent and HISEvent.

### Which API design does SocialED follow?

The API design of PyOD and PyGOD, the outlier detection libraries, and it is built on DGL and PyTorch. The interface is unified across the algorithms and the components of each algorithm are modular, so parts of a model can be swapped for a specific need.

### What licence is SocialED released under?

The repository is recorded under BSD-2-Clause with a licence file in the root, but the packaging metadata in setup.py declares a MIT licence classifier, so the two disagree and the file in the repository is the one to check. The current release is 1.1.7, published on 2025-07-27.

## Sources

- [License: BSD-2-Clause](https://github.com/RingBDStack/SocialED/blob/main/LICENSE)
- [Project website](https://github.com/ChenBeici/SocialED_datasets)
- [README](https://github.com/RingBDStack/SocialED/blob/main/README.md)
- [Releases](https://github.com/RingBDStack/SocialED/releases)
- [RingBDStack/SocialED on GitHub](https://github.com/RingBDStack/SocialED)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ringbdstack-socialed