Tutorials
=========

In-depth tutorials for common use cases.

Tutorial 1: Basic Concept Extraction
-------------------------------------

Learn how to extract and analyze wosecopy concepts from creative stories.

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

Create a CSV file ``stories.csv``:

.. code-block:: text

   Story,prompt,rating
   "There was a belief in the village. The faith helped people.","belief-faith",4
   "Music filled the air. The song brought joy.","music-song",5

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

.. code-block:: python

   from wosecopy import wosecopyExtractor
   import pandas as pd

   # Load data
   df = pd.read_csv('stories.csv')

   # Create extractor
   extractor = wosecopyExtractor(language='en', model_size='lg')

   # Extract concepts
   concepts = extractor.get_wosecopy(df)

   # Add to dataframe
   df['concepts'] = concepts

   # Save
   df.to_csv('results.csv', index=False)

Step 3: Examine Results
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   # View concepts
   for i, row in df.iterrows():
       print(f"Story {i+1}: {row['concepts']}")

Tutorial 2: Network Analysis
-----------------------------

Analyze the network structure of extracted concepts.

Build and Visualize Graphs
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import build_graph, plot_graph, get_graph_summary

   # Build graph from first story
   concepts = df['concepts'][0]
   graph = build_graph(concepts, graph_type='chain')

   # Get summary
   summary = get_graph_summary(graph)
   print(f"Nodes: {summary['num_nodes']}")
   print(f"Edges: {summary['num_edges']}")

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

Calculate Metrics
~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import calculate_all_metrics

   metrics = calculate_all_metrics(graph)

   print(f"ASPL: {metrics['aspl']:.2f}")
   print(f"Clustering: {metrics['mlcc']:.2f}")
   print(f"Modularity: {metrics['modularity']:.2f}")

Tutorial 3: Creativity Analysis
--------------------------------

Measure and compare creativity across different ratings.

Group by Rating
~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy.analysis import group_by_rating
   from wosecopy.metrics import stats

   # Group concepts by rating
   grouped = group_by_rating(df, 'rating', 'concepts')

   # Calculate metrics for each group
   for rating, concept_lists in grouped.items():
       metrics = stats(concept_lists)

       print(f"Rating {rating}:")
       print(f"  Stories: {len(concept_lists)}")
       print(f"  Avg ASPL: {sum(metrics['aspl'])/len(metrics['aspl']):.2f}")

Calculate Unexpectedness
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy.analysis import unexpectedness_arrays

   # Calculate unexpectedness scores
   scores = unexpectedness_arrays(
       df,
       prompt_column='prompt',
       concepts_column='concepts'
   )

   df['unexpectedness'] = scores

   # Analyze by rating
   print(df.groupby('rating')['unexpectedness'].mean())

Tutorial 4: Multi-Rater Analysis
---------------------------------

Compare results across multiple human raters.

Setup Data
~~~~~~~~~~

Assume CSV with columns: ``Story``, ``rating_h``, ``rating_j``, ``rating_k``

.. code-block:: python

   from wosecopy.analysis import compare_raters
   from wosecopy.visualization import plot_metrics_comparison

   # Compare raters
   rater_metrics = compare_raters(
       df,
       rating_columns=['rating_h', 'rating_j', 'rating_k'],
       concepts_column='concepts'
   )

   # Plot comparison
   plot_metrics_comparison(
       rater_metrics,
       metric_name='aspl',
       save_path='rater_comparison.png'
   )

Statistical Testing
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy.metrics import compare_metrics

   # Prepare data
   group_metrics = {}
   for rater in ['rating_h', 'rating_j', 'rating_k']:
       grouped = group_by_rating(df, rater, 'concepts')
       group_metrics[rater] = stats(grouped[4])  # Rating 4 only

   # Statistical comparison
   p_values = compare_metrics(group_metrics, statistical_test='kruskal')
   print("P-values:", p_values)

Tutorial 5: Batch Processing
-----------------------------

Process multiple CSV files efficiently.

Process Multiple Files
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pathlib import Path
   from wosecopy import wosecopyExtractor

   # Initialize extractor once
   extractor = wosecopyExtractor(language='en')

   # Process all CSV files in directory
   input_dir = Path('data')
   output_dir = Path('results')
   output_dir.mkdir(exist_ok=True)

   for csv_file in input_dir.glob('*.csv'):
       print(f"Processing {csv_file.name}...")

       output_path = output_dir / csv_file.name

       extractor.process_csv(
           str(csv_file),
           output_path=str(output_path)
       )

   print("Batch processing complete!")

Tutorial 6: Export for Gephi
-----------------------------

Export graphs for visualization in Gephi.

Export Workflow
~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import wosecopyExtractor, build_graphs_from_list, export_graphs
   import pandas as pd

   # Extract concepts
   df = pd.read_csv('stories.csv')
   extractor = wosecopyExtractor(language='en')
   concepts = extractor.get_wosecopy(df)

   # Build graphs
   graphs = build_graphs_from_list(concepts, graph_type='chain')

   # Export for Gephi
   export_graphs(
       graphs,
       output_dir='graphs_for_gephi',
       prefix='story',
       format='graphml'
   )

   print(f"Exported {len(graphs)} graphs to graphs_for_gephi/")

In Gephi
~~~~~~~~

1. Open Gephi
2. File → Open → Select ``story_0.graphml``
3. Choose graph type: Undirected
4. Run layout algorithm (e.g., ForceAtlas2)
5. Apply statistics (Modularity, PageRank, etc.)
6. Customize appearance

Tutorial 7: German Language Support
------------------------------------

Process German text.

Setup
~~~~~

.. code-block:: bash

   # Download German model
   python -m spacy download de_core_news_lg

Extract German Concepts
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import wosecopyExtractor

   # German data
   df_de = pd.read_csv('german_stories.csv')

   # Create German extractor
   extractor_de = wosecopyExtractor(language='de', model_size='lg')

   # Extract
   concepts_de = extractor_de.get_wosecopy(df_de, text_column='Geschichte')

   df_de['konzepte'] = concepts_de
   df_de.to_csv('results_de.csv', index=False)

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

* Explore the :doc:`api/core` for advanced features
* Check the :doc:`cli_guide` for command-line usage
* See example notebooks (coming soon)