{"id":26502179,"url":"https://github.com/faustogerman/narrative-trails","last_synced_at":"2026-05-02T22:34:33.627Z","repository":{"id":282288337,"uuid":"946673890","full_name":"faustogerman/narrative-trails","owner":"faustogerman","description":"A Method for Coherent Storyline Extraction via Maximum Capacity Path Optimization","archived":false,"fork":false,"pushed_at":"2025-03-13T18:30:33.000Z","size":101859,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-13T19:40:30.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faustogerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-11T14:00:08.000Z","updated_at":"2025-03-13T18:30:37.000Z","dependencies_parsed_at":"2025-03-13T19:50:31.926Z","dependency_job_id":null,"html_url":"https://github.com/faustogerman/narrative-trails","commit_stats":null,"previous_names":["faustogerman/narrative-trails"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustogerman%2Fnarrative-trails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustogerman%2Fnarrative-trails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustogerman%2Fnarrative-trails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustogerman%2Fnarrative-trails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faustogerman","download_url":"https://codeload.github.com/faustogerman/narrative-trails/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244663299,"owners_count":20489893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-20T17:37:00.052Z","updated_at":"2026-05-02T22:34:33.607Z","avatar_url":"https://github.com/faustogerman.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Narrative Trails\nA Method for Coherent Storyline Extraction via Maximum Capacity Path Optimization\n\n![Narrative Trails Pipeline](./other/narrative-trails-pipeline.png)\n\nNarrative Trails is an embedding-based framework for extracting coherent storylines from large document datasets. Unlike traditional information retrieval, which retrieves documents without a pre-defined structure, Narrative Trails structures information into ordered narratives that maximize semantic coherence between documents. This makes it easier for people to identify underlying patterns, connections, and themes that might not be immediately evident by the data.\n\n## Installation\n```bash\ngit clone https://github.com/faustogerman/narrative-trails.git\ncd narrative-trails\npip install -r requirements.txt\n```\nNote: We recommend using a dedicated Conda environment to install and execute this project.\n\n#### OpenAI API\nTo re-extract embeddings or use your own dataset, create a `.env` file at the root of the project and add an `OPENAI_API_KEY` entry with your OpenAI key to make API calls for embedding extraction. \n\nHowever, we already provide embeddings for our evaluation datasets in the `./data` folder. Therefore, you can run this project and reproduce our results without an API key by simply commenting out the following line in `./Library/embedding_extraction.py`:\n\n```python\nclient = OpenAI(api_key=os.getenv(\"OPENAI_API_KEY\"))\n```\n\n## Usage\nAfter cloning the repository and installing the dependencies from `requirements.txt` open and run any `.ipynb` file to reproduce our results. Example Jupyter notebooks for the News Articles and VisPub datasets are available in the [./Examples](./Examples/) folder with details about parameters and redundancy reduction.\n\nNOTE: Expect the results to be slightly different from ours, since each installation of UMAP and HDSCAN can lead to different initial random states, producing different low-dimensional projections.\n\n## Example Storylines\nBelow are example narratives extracted using the Narrative Trails algorithm.\n\n**Example \\#1 – Narrative About the First COVID 19 Death and Airlines Suspending Flights to China**\n```\nidx    Topic   Date             title\n----------------------------------------------------------------\n85     0       Jan 10, 2020     China reports first death from mysterious outbreak in Wuhan\n86     0       Jan 15, 2020     Japan confirms first case of coronavirus infection\n87     0       Jan 17, 2020     Coronavirus: more cases and second death reported in China\n98     0       Jan 23, 2020     China coronavirus: Lockdown measures rise across Hubei province\n102    0       Jan 24, 2020     China expands coronavirus outbreak lockdown to 56 million people\n114    0       Jan 29, 2020     Airlines around the world are suspending flights to China as the coronavirus spreads\n```\n\n**Example \\#2 – Narrative About the 2021 Cuban Protests and Political Reactions in the U.S.** \n```\nidx    Topic   Date             title\n----------------------------------------------------------------\n185    16      Jul 12, 2021     Cuba: Thousands Nationwide Take Streets Against Communism\n205    15      Jul 12, 2021     Police patrol Havana in large numbers after rare protests\n184    15      Jul 12, 2021     Cuba blames US, social media for uprising against Communist regime\n189    11      Jul 12, 2021     Cuba arrests activists as government blames unrest on U.S. interference\n203    11      Jul 12, 2021     Cuban government aggressively suppresses protests\n215    12      Jul 12, 2021     Cuban Americans in Miami warn China-Russia intervention could cause 'bloodbath' in Cuba\n180    12      Jul 12, 2021     Biden Administration Claims Cuban Anti-Communist Protests Are About 'Rising COVID Cases/Deaths'\n204    12      Jul 12, 2021     Democrats and Republicans divided on Cuban protest response\n206    12      Jul 12, 2021     Rubio slams Biden admin's 'major failure' of initially tying of Cuban protests to rising COVID cases\n259    12      Jul 14, 2021     Rubio: Cuba will see 'horrific bloodbath' if Biden does not take action\n445    12      Jul 26, 2021     Protests break out in front of WH urging Biden to take firmer stance on Cuba\n```\n\n**Example \\#3 – Narrative About the Evolution of Visualization Techniques in Data Science** \n```\nidx    Topic   Date             Title\n----------------------------------------------------------------\n129    51      Jan 01, 2021     M2Lens: Visualizing and Explaining Multimodal Models for Sentiment Analysis\n75     45      Jan 01, 2022     Diverse Interaction Recommendation for Public Users Exploring Multi-view Visualization using Deep Learning\n66     36      Jan 01, 2022     MEDLEY: Intent-based Recommendations to Support Dashboard Composition\n70     20      Jan 01, 2022     Effects of View Layout on Situated Analytics for Multiple-View Representations in Immersive Visualization\n1953   36      Jan 01, 2007     ManyEyes: a Site for Visualization at Internet Scale\n3351   36      Jan 01, 1993     Bridging the gap between visualization and data management: A simple visualization management system\n2265   34      Jan 01, 2005     Distributed data management for large volume visualization\n3308   38      Jan 01, 1994     A case study on visualization for boundary value problems\n3537   33      Jan 01, 1990     Visualization for nonlinear engineering FEM analysis in manufacturing\n2568   42      Jan 01, 2003     IEEE Visualization 2003 (IEEE Cat. No.03CH37496)\n581    29      Jan 01, 2018     Dynamic Volume Lines: Visual Comparison of 3D Volumes through Space-filling Curves\n864    56      Jan 01, 2016     Visualizing Shape Deformations with Variation of Geometric Spectrum\n65     29      Jan 01, 2022     Level Set Restricted Voronoi Tessellation for Large scale Spatial Statistical Analysis\n1386   30      Jan 01, 2012     Surface-Based Structure Analysis and Visualization for Multifield Time-Varying Datasets\n984    30      Jan 01, 2015     Interactive Visualization for Singular Fibers of Functions f : R3 → R2\n1301   30      Jan 01, 2012     Generalized Topological Simplification of Scalar fields on Surfaces\n1097   30      Jan 01, 2014     Multiscale Symmetry Detection in Scalar Fields by Clustering Contours\n926    48      Jan 01, 2015     Comparative visual analysis of vector field ensembles\n1930   48      Jan 01, 2008     Interactive Visualization and Analysis of Transitional Flow\n2242   49      Jan 01, 2005     Opening the can of worms: an exploration tool for vortical flows\n345    48      Jan 01, 2020     Objective Observer-Relative Flow Visualization in Curved Spaces for Unsteady 2D Geophysical Flows\n```\n\n## Citing Our Work\n```\n@inproceedings{German2025Narrative,\n  author    = {Fausto German and Brian Keith and Chris North},\n  title     = {Narrative Trails: A Method for Coherent Storyline Extraction via Maximum Capacity Path Optimization},\n  booktitle = {Proceedings of the Text2Story 2025 Workshop@ECIR2025},\n  series    = {CEUR Workshop Proceedings},\n  year      = {2025},\n  address   = {Lucca, Italy},\n  month     = apr,\n  pages     = {15--22},\n  publisher = {CEUR-WS},\n  note      = {April 10, 2025}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaustogerman%2Fnarrative-trails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaustogerman%2Fnarrative-trails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaustogerman%2Fnarrative-trails/lists"}