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:

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

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

# 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

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

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

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

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

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

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

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

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

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

Tutorial 7: German Language Support

Process German text.

Setup

# Download German model
python -m spacy download de_core_news_lg

Extract German Concepts

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 Core Module for advanced features
Check the CLI Guide for command-line usage
See example notebooks (coming soon)