.. wosecopy documentation master file

wosecopy: WOrd SEntence COoccurrence
====================================

**wosecopy** is a Python package for extracting and analyzing concept associations in creative stories using natural language processing and network analysis.

.. image:: https://img.shields.io/badge/python-3.8+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python 3.8+

.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: MIT License

Overview
--------

wosecopy identifies semantic relationships between concepts across consecutive sentences to understand narrative flow and creativity. It extracts noun-based concepts, matches them using word embeddings, builds network graphs, and calculates various metrics to quantify story structure.

Key Features
------------

* **Bilingual Support**: Process both English and German text
* **Concept Extraction**: Extract noun-based concepts using spaCy
* **Semantic Matching**: Link concepts using word embeddings similarity
* **Network Analysis**: Calculate 6 key metrics (ASPL, MLCC, Modularity, etc.)
* **Creativity Analysis**: Measure concept "unexpectedness"
* **Visualization**: Generate network graphs and statistical plots
* **CLI Tools**: Complete command-line interface
* **Export Formats**: GraphML, GEXF, GML

Quick Start
-----------

Installation
~~~~~~~~~~~~

.. code-block:: bash

   pip install wosecopy
   python -m spacy download en_core_web_lg

Basic Usage
~~~~~~~~~~~

Command Line:

.. code-block:: bash

   # Extract concepts from stories
   wosecopy extract stories.csv -o results.csv

   # Calculate network metrics
   wosecopy metrics results.csv -o metrics.json

   # Visualize a concept network
   wosecopy visualize results.csv -o graph.png

Python API:

.. code-block:: python

   from wosecopy import wosecopyExtractor, build_graph, calculate_all_metrics

   # Extract concepts
   extractor = wosecopyExtractor(language='en')
   df = extractor.process_csv('stories.csv')

   # Build and analyze graph
   concepts = df['wosecopy_concepts'][0]
   graph = build_graph(concepts)
   metrics = calculate_all_metrics(graph)

Contents
--------

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   installation
   quickstart
   cli_guide
   tutorials

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/core
   api/graph
   api/metrics
   api/analysis
   api/visualization
   api/language
   api/cli

.. toctree::
   :maxdepth: 1
   :caption: Additional Information

   contributing
   changelog
   license

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`