tex2net 1.41

Build character graphs from text.

tex2net

Overview

tex2net is a Python library designed to convert narrative texts into interactive network graphs that visualize character interactions. The library leverages Natural Language Processing (NLP) with spaCy, text rewriting and summarization using Transformer models (T5), network analysis with NetworkX, and interactive visualization with Pyvis and Matplotlib. This tool is perfect for researchers, data scientists, and digital humanities scholars looking to explore complex narrative structures.

Features

• Text Preprocessing & Entity Extraction: Extract characters from text using spaCy's Named Entity Recognition.
• Graph Construction: Build directed graphs representing character interactions, annotated with actions and sentence IDs.
• Node Merging: Combine nodes with similar character names for consistency.
• Text Rewriting & Summarization: Use T5 models to rephrase or summarize text, emphasizing clear character-verb-character structures.
• Network Analysis: Compute centrality measures, detect communities, analyze temporal relationships, and more.
• Visualization: Create both static (Matplotlib) and interactive (Pyvis) visualizations for in-depth narrative analysis.

Installation

Install the package via pip:

pip install tex2net

tex2net currently supports Python 3.10 and newer.

Make sure you have all the required dependencies. You can also install them using the provided requirements.txt if needed. You may need to run:

pip install --upgrade typing_extensions
python -m spacy download en_core_web_lg

Usage Example

Below is an example of how to use tex2net to create a character graph from sample text:

import tex2net

# Sample text data (this could be text from a novel, article, or LaTeX file)
text_data = """
Alice was discussing ideas with Bob. Later, Bob met Charlie.
"""

# Create a character graph from the text data
graph, characters, relationships = tex2net.create_character_graph(text_data)

# Optionally, join similar nodes to merge duplicate character entries
joined_graph = tex2net.join_similar_nodes(graph, characters)

tex2net.visualize_directed_graph(joined_graph, title="Character Relationships Directed Graph")

For more complex text the create_character_graph_llm_chunked function can be used.

For longer texts use create_character_graph_llm_long_text.

More functions are instantiated in example_usage.ipynb.

Gallery and GitHub Pages showcase

This repository now includes a static gallery in docs/index.html together with generated example assets in docs/generated.

To rebuild the gallery locally:

python scripts/build_gallery.py

The Pages workflow in .github/workflows/pages.yml rebuilds and publishes the gallery automatically.

Contributing

Contributions are welcome! Feel free to submit pull requests or open issues to improve the functionality of this library. Please follow the code style and add tests for any new features.

Release process

Releases are published to PyPI with GitHub Actions and PyPI Trusted Publishing.

1. Update the version in pyproject.toml.
2. Merge the change into main.
3. Create and push a version tag such as v1.41.
4. Wait for the Release tex2net to PyPI workflow to finish.

The publishing job expects a GitHub environment named pypi and a matching Trusted Publisher entry on PyPI for this repository and workflow file.

License

This project is licensed under the GPL-3.0 License.

---

Happy storytelling and network exploring!

Citation

If you find tex2net helpful in your academic or professional work, please cite the following paper:

@inproceedings{aparicio2023tex2net,
  title={tex2net: A Package for Storytelling Using Network Models},
  author={Aparicio, Joao Tiago and Arsenio, Elisabete and Henriques, Rui},
  booktitle={Proceedings of the 41st ACM International Conference on Design of Communication},
  pages={119--125},
  year={2023}
}

or

Aparicio, J. T., Arsenio, E., & Henriques, R. (2023, October). tex2net: A Package for Storytelling Using Network Models. In Proceedings of the 41st ACM International Conference on Design of Communication (pp. 119-125).

You can find the paper at ACM Digital Library: https://dl.acm.org/doi/pdf/10.1145/3615335.3623022.