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:

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

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

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

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

Export Graphs for Gephi/Cytoscape

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

Compare Multiple Raters

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

Measure Story Creativity

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

Python API Quick Start

Basic Extraction

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

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

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:

['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