Quick Start Guide
=================

This guide will get you up and running with wosecopy in 5 minutes!

Your First Analysis
-------------------

Step 1: Prepare Your Data
~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a CSV file with your stories. Minimum required column is a text column (default name: ``Story``).

Example ``my_stories.csv``:

.. code-block:: text

   Story,prompt,rating
   "There was a belief in the village. The faith helped people cope.","belief-faith-sing",4
   "The gloom settled over the city. A payment was due soon.","gloom-payment-exist",3

Step 2: Extract Concepts
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   wosecopy extract my_stories.csv -o results.csv

This will:

* Extract nouns from each sentence
* Match concepts between consecutive sentences
* Create a concept chain for each story
* Save results to ``results.csv``

Step 3: Analyze Results
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

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

Common Use Cases
----------------

Analyze by Creativity Ratings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have ratings in your CSV:

.. code-block:: bash

   wosecopy analyze-ratings results.csv --rating-column rating -o grouped_metrics.json

Export Graphs for Gephi/Cytoscape
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   wosecopy export results.csv -o graphs/ --format graphml

Compare Multiple Raters
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   wosecopy compare results.csv -r rating_h -r rating_j -r rating_k -o plots/

Measure Story Creativity
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   wosecopy unexpectedness results.csv --prompt-column prompt -o creative_scores.csv

Python API Quick Start
----------------------

Basic Extraction
~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import wosecopyExtractor

   # Create extractor
   extractor = wosecopyExtractor(language='en')

   # Process CSV
   df = extractor.process_csv('my_stories.csv', output_path='results.csv')

   # Or process DataFrame directly
   import pandas as pd
   df = pd.DataFrame({'Story': ['Your story here...']})
   concepts = extractor.get_wosecopy(df)

Graph Analysis
~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import build_graph, calculate_all_metrics

   # Build graph
   concepts = ['belief', 'faith', 'church', 'prayer']
   graph = build_graph(concepts)

   # Calculate metrics
   metrics = calculate_all_metrics(graph)
   print(f"Clustering: {metrics['mlcc']:.3f}")
   print(f"Modularity: {metrics['modularity']:.3f}")

Visualization
~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import plot_graph, plot_network_stats

   # Visualize network
   plot_graph(graph, save_path='network.png')

   # Plot metrics
   from wosecopy.metrics import stats
   metrics = stats(concept_lists)
   plot_network_stats(metrics, save_path='stats.png')

Understanding the Output
-------------------------

Extracted Concepts
~~~~~~~~~~~~~~~~~~

The ``wosecopy_concepts`` column contains a list of linked concepts:

.. code-block:: python

   ['belief', 'faith', 'church', 'prayer', 'community']

These represent the narrative flow through semantically-connected concepts.

Network Metrics
~~~~~~~~~~~~~~~

Six key metrics are calculated:

1. **ASPL** (Average Shortest Path Length): How efficiently concepts connect
2. **MLCC** (Mean Local Clustering): How tightly concepts cluster
3. **Modularity**: Strength of community structure
4. **Num Components**: Number of separate concept groups
5. **Avg Component Size**: Average size of groups
6. **GCC Size**: Size of largest connected group

Unexpectedness Scores
~~~~~~~~~~~~~~~~~~~~~~

Higher scores indicate more creative/unexpected concepts relative to the prompt.

Next Steps
----------

* Read the :doc:`cli_guide` for detailed CLI documentation
* Check out :doc:`tutorials` for in-depth examples
* Explore the :doc:`api/core` for Python API details