Metrics Module
==============

The metrics module calculates network metrics for wosecopy concept graphs.

Network Metrics Functions
--------------------------

calculate_aspl
~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.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
~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.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
~~~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.calculate_avg_component_size

Average size of connected components.

calculate_gcc_size
~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.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
~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.calculate_all_metrics

Calculate all 6 metrics at once for a single graph.

**Returns**:

.. code-block:: python

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

**Example**:

.. code-block:: python

   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
~~~~~

.. autofunction:: wosecopy.metrics.stats

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

**Example**:

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.aggregate_metrics

Aggregate metrics across multiple graphs.

**Aggregation Methods**:

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

**Example**:

.. code-block:: python

   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
~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.metrics.compare_metrics

Perform statistical comparison of metrics across groups.

**Statistical Tests**:

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

**Example**:

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   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  |
+-------------------+-------------------------------+-------------------+