Metrics Module

The metrics module calculates network metrics for wosecopy concept graphs.

Network Metrics Functions

calculate_aspl

Average Shortest Path Length (ASPL): Measures the average distance between all pairs of nodes.

Lower values indicate more efficient concept connections
Reflects how easily concepts can reach each other

Interpretation:

Low ASPL (< 3): Highly interconnected narrative
Medium ASPL (3-5): Moderately connected concepts
High ASPL (> 5): Dispersed concept structure

calculate_mlcc

Mean Local Clustering Coefficient (MLCC): Measures how tightly nodes cluster together.

Higher values indicate more tightly knit concept groups
Reflects local cohesion in the narrative

Interpretation:

High MLCC (> 0.5): Concepts form tight clusters
Low MLCC (< 0.3): Concepts are loosely connected

calculate_modularity

Modularity (Q): Measures the strength of division into communities/modules.

Higher values indicate stronger community structure
Reflects thematic organization

Interpretation:

High Q (> 0.5): Strong thematic communities
Low Q (< 0.3): Weakly defined themes

calculate_num_components

Number of Connected Components (NGCC): Count of separate concept clusters.

Interpretation:

1 component: Fully connected narrative
Multiple components: Disconnected narrative threads

calculate_avg_component_size

Average size of connected components.

calculate_gcc_size

Giant Connected Component (GCC) size: Size of the largest connected cluster.

Interpretation:

Large GCC: Most concepts connected in main narrative
Small GCC: Fragmented narrative structure

Aggregate Functions

calculate_all_metrics

Calculate all 6 metrics at once for a single graph.

Returns:

{
    'aspl': 2.5,
    'mlcc': 0.33,
    'modularity': 0.42,
    'num_components': 1,
    'avg_component_size': 5.0,
    'gcc_size': 5
}

Example:

from wosecopy import build_graph, calculate_all_metrics

concepts = ['belief', 'faith', 'church', 'prayer']
graph = build_graph(concepts)
metrics = calculate_all_metrics(graph)

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

stats

Main function from the original notebook. Calculate metrics for multiple concept lists.

Example:

from wosecopy.metrics import stats

concept_lists = [
    ['a', 'b', 'c'],
    ['x', 'y', 'z'],
    ['one', 'two', 'three']
]

metrics = stats(concept_lists, graph_type='chain')

# metrics is a dict with lists of values:
# {
#     'aspl': [2.0, 1.5, 2.0],
#     'mlcc': [0.0, 0.0, 0.0],
#     ...
# }

aggregate_metrics

Aggregate metrics across multiple graphs.

Aggregation Methods:

mean: Average value
median: Median value
std: Standard deviation

Example:

from wosecopy.metrics import aggregate_metrics

metrics_list = [
    {'aspl': 2.0, 'mlcc': 0.5},
    {'aspl': 3.0, 'mlcc': 0.6},
    {'aspl': 2.5, 'mlcc': 0.55}
]

mean_metrics = aggregate_metrics(metrics_list, aggregation='mean')
# {'aspl': 2.5, 'mlcc': 0.55}

compare_metrics

Perform statistical comparison of metrics across groups.

Statistical Tests:

kruskal: Kruskal-Wallis H-test (non-parametric)
anova: One-way ANOVA

Example:

from wosecopy.metrics import compare_metrics

group_metrics = {
    'group1': {'aspl': [2.0, 2.5, 3.0]},
    'group2': {'aspl': [4.0, 4.5, 5.0]},
    'group3': {'aspl': [1.5, 2.0, 2.5]}
}

p_values = compare_metrics(group_metrics, statistical_test='kruskal')
print(f"p-value for ASPL: {p_values['aspl']}")

Complete Example

Analyze Stories by Rating

from wosecopy import wosecopyExtractor
from wosecopy.metrics import stats, aggregate_metrics
from wosecopy.analysis import group_by_rating
import pandas as pd

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

# Extract concepts
extractor = wosecopyExtractor(language='en')
df['concepts'] = extractor.get_wosecopy(df)

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

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

    # Aggregate
    avg_metrics = aggregate_metrics([
        {k: v[i] for k, v in metrics.items()}
        for i in range(len(concept_lists))
    ])

    print(f"Rating {rating}:")
    print(f"  ASPL: {avg_metrics['aspl']:.2f}")
    print(f"  MLCC: {avg_metrics['mlcc']:.2f}")
    print(f"  Modularity: {avg_metrics['modularity']:.2f}")

Metrics Reference Table

Metric	What it Measures	Interpretation
ASPL	Efficiency of connections	Lower = tighter
MLCC	Local clustering	Higher = clustered
Modularity	Community structure	Higher = modular
Num Components	Number of clusters	1 = connected
Avg Component Size	Average cluster size	Larger = cohesive
GCC Size	Largest cluster size	Larger = unified