Graph Module
============

The graph module provides functionality for building, exporting, and managing concept network graphs.

Functions
---------

build_graph
~~~~~~~~~~~

.. autofunction:: wosecopy.graph.build_graph

Build a NetworkX graph from a list of concepts.

**Graph Types**:

* ``chain``: Connect consecutive concepts (recommended for narrative flow)
* ``dense``: Connect all concepts to each other

**Example**:

.. code-block:: python

   from wosecopy import build_graph

   concepts = ['belief', 'faith', 'church', 'prayer']

   # Chain graph (narrative flow)
   chain_graph = build_graph(concepts, graph_type='chain')

   # Dense graph (all connections)
   dense_graph = build_graph(concepts, graph_type='dense')

build_graphs_from_list
~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.graph.build_graphs_from_list

Build multiple graphs from a list of concept lists.

**Example**:

.. code-block:: python

   from wosecopy import build_graphs_from_list

   concept_lists = [
       ['a', 'b', 'c'],
       ['x', 'y', 'z']
   ]
   graphs = build_graphs_from_list(concept_lists)

export_graph
~~~~~~~~~~~~

.. autofunction:: wosecopy.graph.export_graph

Export a single graph to a file.

**Supported Formats**:

* ``graphml``: GraphML format (recommended for Gephi, Cytoscape)
* ``gexf``: GEXF format
* ``gml``: Graph Modelling Language
* ``edgelist``: Simple edge list

**Example**:

.. code-block:: python

   from wosecopy import build_graph, export_graph

   graph = build_graph(['a', 'b', 'c'])
   export_graph(graph, 'my_graph.graphml', format='graphml')

export_graphs
~~~~~~~~~~~~~

.. autofunction:: wosecopy.graph.export_graphs

Export multiple graphs to a directory.

**Example**:

.. code-block:: python

   from wosecopy import export_graphs

   graphs = [graph1, graph2, graph3]
   export_graphs(graphs, 'graphs/', prefix='story', format='graphml')
   # Creates: graphs/story_0.graphml, graphs/story_1.graphml, etc.

load_graph
~~~~~~~~~~

.. autofunction:: wosecopy.graph.load_graph

Load a graph from a file.

**Example**:

.. code-block:: python

   from wosecopy import load_graph

   graph = load_graph('my_graph.graphml', format='graphml')

merge_graphs
~~~~~~~~~~~~

.. autofunction:: wosecopy.graph.merge_graphs

Merge multiple graphs into a single graph.

**Example**:

.. code-block:: python

   from wosecopy import merge_graphs

   merged = merge_graphs([graph1, graph2, graph3])

get_graph_summary
~~~~~~~~~~~~~~~~~

.. autofunction:: wosecopy.graph.get_graph_summary

Get basic statistics about a graph.

**Returns**:

* ``num_nodes``: Number of nodes
* ``num_edges``: Number of edges
* ``is_connected``: Whether graph is fully connected
* ``num_components``: Number of connected components
* ``density``: Graph density (0-1)

**Example**:

.. code-block:: python

   from wosecopy import build_graph, get_graph_summary

   graph = build_graph(['a', 'b', 'c'], graph_type='chain')
   summary = get_graph_summary(graph)
   print(summary)
   # {'num_nodes': 3, 'num_edges': 2, 'is_connected': True, ...}

Usage Examples
--------------

Complete Workflow
~~~~~~~~~~~~~~~~~

.. code-block:: python

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

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

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

   # Export for Gephi
   export_graphs(graphs, 'graphs/', format='graphml')

Analyzing Individual Graphs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from wosecopy import build_graph, get_graph_summary

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

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