Metadata-Version: 2.4
Name: ciga
Version: 0.1.5
Summary: Character interaction temporal graph analysis
Author-email: Media Comprehension Lab <shu13@gsu.edu>
Maintainer-email: Shu Hu <shu13@gsu.edu>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/MediaCompLab/ciga
Project-URL: Repository, https://github.com/MediaCompLab/ciga
Project-URL: Issues, https://github.com/MediaCompLab/ciga/issues
Keywords: temporal graphs,social network analysis,character interaction,narrative analysis,igraph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Sociology
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: igraph
Requires-Dist: numpy
Requires-Dist: tqdm
Requires-Dist: matplotlib
Requires-Dist: scipy
Provides-Extra: visualization
Requires-Dist: imageio>=2.9; extra == "visualization"
Requires-Dist: imageio-ffmpeg>=0.4; extra == "visualization"
Provides-Extra: tda
Requires-Dist: ripser; extra == "tda"
Requires-Dist: persim; extra == "tda"
Provides-Extra: llm
Requires-Dist: openai; extra == "llm"
Provides-Extra: hypergraph-reticula
Requires-Dist: reticula<0.14,>=0.13; extra == "hypergraph-reticula"
Provides-Extra: hypergraph-xgi
Requires-Dist: xgi<0.11,>=0.10.2; extra == "hypergraph-xgi"
Provides-Extra: hypergraph-hgx
Requires-Dist: hypergraphx<1.9,>=1.8; extra == "hypergraph-hgx"
Provides-Extra: hypergraph
Requires-Dist: reticula<0.14,>=0.13; extra == "hypergraph"
Requires-Dist: xgi<0.11,>=0.10.2; extra == "hypergraph"
Requires-Dist: hypergraphx<1.9,>=1.8; extra == "hypergraph"
Provides-Extra: all
Requires-Dist: imageio>=2.9; extra == "all"
Requires-Dist: imageio-ffmpeg>=0.4; extra == "all"
Requires-Dist: ripser; extra == "all"
Requires-Dist: persim; extra == "all"
Requires-Dist: openai; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: sphinx>=3.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: twine>=4.0.2; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

![license](https://img.shields.io/github/license/MediaCompLab/CIGA.svg)
![package](https://github.com/MediaCompLab/CIGA/actions/workflows/python-package.yml/badge.svg?event=push)
![publish](https://github.com/MediaCompLab/CIGA/actions/workflows/python-publish.yml/badge.svg)

# CIGA: Character Interaction Graph Analysis

CIGA analyzes character interactions over time. Use graphs for pairwise relationships,
or hypergraphs to keep a group interaction as one event. It builds on igraph and is a
redesign of [CharNet](https://github.com/MediaCompLab/CharNet).

[Getting started](docs/tutorials.rst) · [Documentation](docs/index.rst) ·
[Upgrade roadmap](UPGRADE_PLAN.md) · [Contributing](CONTRIBUTING.md)

## Install

This documentation targets **CIGA 0.1.5** (Python 3.9+). After its PyPI release:

```bash
python -m pip install "ciga==0.1.5"
```

To use the source checkout, including before publication:

```bash
git clone https://github.com/MediaCompLab/ciga.git
cd ciga
python -m pip install -e .
```

Core graph/hypergraph analysis and interactive HTML viewers need no extras.
Optional features after publication:

| Feature | Install |
| --- | --- |
| GIF and MP4 export | `python -m pip install "ciga[visualization]==0.1.5"` |
| Persistent homology | `python -m pip install "ciga[tda]==0.1.5"` |
| Listener inference with a model provider | `python -m pip install "ciga[llm]==0.1.5"` |
| Reticula, XGI and Hypergraphx integrations (Python 3.10+) | `python -m pip install "ciga[hypergraph]==0.1.5"` |

`all` includes visualization, TDA and LLM extras; use `ciga[all,hypergraph]==0.1.5`
for both sets. In a checkout, use `python -m pip install -e ".[extra]"`.
See [installation](docs/installation.rst) for individual backends and pathpyG setup.

## Quick start

This complete example counts interactions in each scene and saves an HTML graph:

```python
import pandas as pd
import ciga as cg

dialogue = pd.DataFrame({
    'scene': [1, 1, 2, 2],
    'Speaker': ['Alice', 'Bob', 'Alice', 'Charlie'],
    'Listener': ['Bob', 'Alice', 'Charlie', 'Alice'],
    'text': ['Hello', 'Hi', 'Come in', 'Thanks'],
})
positions = ('scene',)
pairs = cg.prepare_data(dialogue, positions, source='Speaker', target='Listener', interaction='text')
pairs = cg.calculate_weights(pairs, weight_func=lambda text: 1)
tg = cg.TGraph(data=pairs, positions=positions, directed=True)

scores = cg.tgraph_degree_centrality(tg, accumulate=False, weighted=True)
print(scores)  # scene, character, degree columns and weighted degree columns
scores.to_csv('degrees.csv', index=False)

g = tg.get_graph((1,))
cg.graph_viz(g, output_file='scene-1.html', open_browser=False)
```

Open `scene-1.html` in a browser. Positions must be numeric, ordered from coarse to
fine, for example `('season', 'episode', 'scene', 'line')`.

Temporal analyses are **cumulative by default**. Use `accumulate=False` for separate
snapshots or `window_size=2` for the last two observed steps, including the current one.
Results include time columns, `character`, and the metric columns.

## Choose a representation

| Your data or question | Use | What is retained |
| --- | --- | --- |
| Pairwise relationships in one selection | `igraph.Graph` from `tg.get_graph(...)` and `graph_*` | Edges and their aggregated weights |
| Pairwise relationships over time | `TGraph` and `tgraph_*` | Time-indexed pair interactions |
| Participation in group events | `Hypergraph` and `hypergraph_*` | Each event, its participants and metadata |
| Group events over time | `THypergraph` and `thypergraph_*` | Event identity, directed roles and time |

For example, one speaker addressing two listeners remains one hypergraph event:

```python
import pandas as pd
import ciga as cg

dialogue = pd.DataFrame({
    'scene': [1, 1, 2],
    'source': ['Alice', 'Alice', 'Bob'],
    'target': ['Bob, Charlie', 'Bob, Charlie', 'Charlie'],
})
events = cg.prepare_hypergraph_data(dialogue, positions=['scene'])
th = cg.THypergraph(data=events, positions=['scene'])
h = th.get_hypergraph((1,))
assert h.ecount() == 2  # repeated groups remain separate events
print(cg.hypergraph_degree_centrality(h, include_character=True))
cg.hypergraph_viz(h, output_file='groups.html', open_browser=False)
```

Both temporal classes default to directed. Static centrality tables follow vertex order;
temporal centralities add time and character columns. Similar function names do not make
graph and hypergraph metrics interchangeable: hypergraph degree counts events, not pairs.
See the [hypergraph guide](docs/hypergraph.rst) and [preview migration notes](docs/hypergraph_migration.rst).

## Next steps

- [Data preparation](docs/data.rst): columns, weights, CSV input and listener inference.
- [Analysis](docs/analysis.rst): centrality, communities, TDA and time-respecting paths.
- [Visualization](docs/visualization.rst): local explorers, time labels, GIF and MP4 export.
- [Native hypergraph methods](docs/hypergraph_backends.rst): conversions, assumptions and provenance.
- [Dialogue CSV example](examples/hypergraph_dialogue.py): run `python examples/hypergraph_dialogue.py`
  from the checkout; outputs go to `build/hypergraph-dialogue-demo`. Add `--native` for installed native methods.
- [Local backend benchmark](benchmarks/hypergraph/results/2026-09-02.md): measured workloads and limitations.

For annotation or a graphical interface, see [CIGA Annotator](https://github.com/MediaCompLab/ciga-annotator)
and [CIGA GUI](https://github.com/MediaCompLab/ciga-gui).

## Citation and license

If CIGA supports your research, cite it using [CITATION.cff](CITATION.cff), also available
under **Cite this repository** on GitHub:

> Hu, S. CIGA: Character Interaction Graph Analysis (Version 0.1.5) [Computer software].
> https://github.com/MediaCompLab/ciga

Cite the version used in your analysis. CIGA is licensed under [GPL-3.0-or-later](LICENSE).
