docs: community detection guide

doc/source/_static/custom.css

@@ -8,3 +8,99 @@
     max-width: 100%;
     overflow: visible;
 }
+
+/* Custom CSS for colored cards */
+/* Base card styling for better visual appearance */
+.sd-card {
+    border: none !important;
+    border-radius: 8px !important;
+    position: relative;
+    padding: 1em; /* Adjust padding as needed */
+    color: white;
+    transition: transform 0.2s ease-in-out, box-shadow 0.2s ease-in-out;
+}
+
+/* Hover effect */
+.sd-card:hover {
+    transform: translateY(-3px); /* Slightly lift card */
+    box-shadow: 0 5px 15px rgba(0, 0, 0, 0.1); /* Add a subtle shadow */
+}
+
+/* Card titles inside the body */
+.sd-card-body h3, .sd-card-body strong {
+    font-size: 1.2em;
+    font-weight: bold;
+    margin-bottom: 0.5em;
+    color: white !important;
+}
+
+/* Ensure the main content block has flexible spacing */
+.sd-card-body {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    height: 100%;
+    text-align: center;
+}
+
+/* Download button container inside the card */
+.sd-card-body .download-container {
+    position: relative;
+    z-index: 10; /* A high number to make sure it's on top */
+    margin-top: auto; /* Push to the bottom */
+    text-align: right;
+}
+
+/* The actual button inside the container */
+.sd-card-body .download-button {
+    background-color: #f8f9fa;
+    color: #212529;
+    border: 1px solid #ced4da;
+    padding: 10px 20px;
+    border-radius: 5px;
+    cursor: pointer;
+}
+
+.download-link {
+    text-decoration: none !important;
+}
+
+.download-button {
+    padding: 8px 16px;
+    background-color: #2980b9;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 14px;
+    transition: background-color 0.3s;
+}
+
+.download-button:hover {
+    background-color: #3498db;
+}
+
+/* Colored cards (your colors are good) */
+.card-red-orange { background-color: #FF6633; }
+.card-deep-orange { background-color: #FF8C40; }
+.card-yellow-orange { background-color: #FFA500; }
+.card-light-green { background-color: #7ED957; }
+.card-medium-green { background-color: #70B341; }
+.card-dark-green { background-color: #4CAF50; }
+.card-light-blue { background-color: #409ED8; }
+.card-medium-blue { background-color: #007BFF; }
+.card-deep-blue { background-color: #0056b3; }
+.card-light-purple { background-color: #BF40BF; } 
+.card-medium-purple { background-color: #800080; } 
+.card-deep-purple { background-color: #4B0082; } 
+
+section h1,
+section h2,
+section h3 {
+    margin-top: 35px;
+}
+
+section p {
+    margin-top: 20px;
+}

doc/source/community_detection_guide.rst

@@ -0,0 +1,127 @@
+Community Detection Guide
+=========================================
+
+This documentation provides an overview of the notebooks available in the community detection guide.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   community_detection_guide/notebooks/initial_workflow.ipynb
+   community_detection_guide/notebooks/community_detection_algorithms.ipynb
+   community_detection_guide/notebooks/test_significance_of_community.ipynb
+   community_detection_guide/notebooks/generating_and_visualizing_clusters.ipynb
+   community_detection_guide/notebooks/hierarchical_clustering.ipynb
+   community_detection_guide/notebooks/modularity.ipynb
+   community_detection_guide/notebooks/resolution.ipynb
+   community_detection_guide/notebooks/consensus_clustering.ipynb
+   community_detection_guide/notebooks/membership_vector.ipynb
+   community_detection_guide/notebooks/working_with_directed_networks.ipynb
+   community_detection_guide/notebooks/working_with_clusterings.ipynb
+   community_detection_guide/notebooks/functions.ipynb
+
+.. grid:: 2 2 3 3
+   :gutter: 3
+
+   .. grid-item-card::  Initial Workflow
+      :link: community_detection_guide/notebooks/initial_workflow
+      :link-type: doc
+      :class-card: sd-card-hover card-red-orange
+      :shadow: sm
+
+      .. **Overview:** This notebook is a quick start guide to community detection in igraph. It covers the initial workflow for detecting communities in networks. (If you look for a more practical learning experience, we recommend starting with this notebook.)
+
+   .. grid-item-card::  Community Detection Algorithms
+      :link: community_detection_guide/notebooks/community_detection_algorithms
+      :link-type: doc
+      :class-card: sd-card-hover card-deep-orange
+      :shadow: sm
+
+      .. **Overview:** This notebook covers various community detection algorithms available in igraph. It provides a detailed explanation of these algorithms and when to use the
+
+   .. grid-item-card::  Significance of Community Structure
+      :link: community_detection_guide/notebooks/test_significance_of_community
+      :link-type: doc
+      :class-card: sd-card-hover card-yellow-orange
+      :shadow: sm   
+
+      .. **Overview:** This notebook provides methods to test the significance of detected communities. 
+
+   .. grid-item-card::  Generating and Visualizing Clusters
+      :link: community_detection_guide/notebooks/generating_and_visualizing_clusters
+      :link-type: doc
+      :class-card: sd-card-hover card-dark-green
+      :shadow: sm
+
+      .. **Overview:** This notebook provides various methods for generating and visualizing clusters in networks. It includes techniques for visualizing community structures.
+
+   .. grid-item-card::  Hierarchical Clustering
+      :link: community_detection_guide/notebooks/hierarchical_clustering
+      :link-type: doc
+      :class-card: sd-card-hover card-medium-green
+      :shadow: sm
+
+      .. **Overview:** This notebook describes hierarchical clustering. It explains how to perform hierarchical clustering on networks and visualize the results.
+
+   .. grid-item-card::  Modularity
+      :link: community_detection_guide/notebooks/modularity
+      :link-type: doc
+      :class-card: sd-card-hover card-light-green
+      :shadow: sm
+
+      .. **Overview:** This notebook introduces the concept of modularity in community detection.
+
+   .. grid-item-card::  Resolution Parameter
+      :link: community_detection_guide/notebooks/resolution
+      :link-type: doc
+      :class-card: sd-card-hover card-deep-blue 
+      :shadow: sm
+
+      .. **Overview:** This notebook introduces the concept of resolution parameter on the Sierpinski triangle.
+
+   .. grid-item-card::  Consensus Clustering
+      :link: community_detection_guide/notebooks/consensus_clustering
+      :link-type: doc
+      :class-card: sd-card-hover card-medium-blue 
+      :shadow: sm
+
+      .. **Overview:** This notebook introduces the method of consensus clustering by combining multiple clustering results.
+
+   .. grid-item-card::  Membership Vector
+      :link: community_detection_guide/notebooks/membership_vector
+      :link-type: doc
+      :class-card: sd-card-hover card-light-blue 
+      :shadow: sm
+
+      .. **Overview:** This notebook introduces membership vectors in igraph.
+
+   .. grid-item-card::  Working with Directed Networks
+      :link: community_detection_guide/notebooks/working_with_directed_networks
+      :link-type: doc
+      :class-card: sd-card-hover card-deep-purple 
+      :shadow: sm
+
+      .. **Overview:** This notebook describes how to work with clusterings in igraph.
+
+   .. grid-item-card::  Working with Clusterings
+      :link: community_detection_guide/notebooks/working_with_clusterings
+      :link-type: doc
+      :class-card: sd-card-hover card-medium-purple 
+      :shadow: sm
+
+      .. **Overview:** This notebook describes how to work with clusterings in igraph.
+
+   .. grid-item-card::  Helper Functions
+      :link: community_detection_guide/notebooks/functions
+      :link-type: doc
+      :class-card: sd-card-hover card-light-purple 
+      :shadow: sm
+
+      .. **Overview:** This notebook introduces all the helper functions used in the community detection guide. It provides a collection of utility functions for community detection tasks.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/community_detection_guide/networks/README.md

@@ -0,0 +1,59 @@
+### README for `game_of_thrones/GOT.graphml`
+
+The **`game_of_thrones/GOT.graphml`** file contains a character interaction network for Season 1 of the HBO series "Game of Thrones".
+
+---
+
+### License
+
+This data is licensed under a **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License**.
+
+---
+
+### Source
+
+This file was built based on the following CSV file:
+https://raw.githubusercontent.com/mathbeveridge/gameofthrones/master/data/got-s1-edges.csv
+
+---
+---
+---
+
+### README for `lesmis/lesmis.gml`
+
+The **`lesmis/lesmis.gml`** file contains a co-appearance network of characters from Victor Hugo's novel, "Les Misérables".
+
+---
+
+### License
+
+When using this data, please cite the following work:
+> D. E. Knuth, The Stanford GraphBase: A Platform for Combinatorial Computing, Addison-Wesley, Reading, MA (1993).
+
+---
+
+### Source
+
+This file was obtained from Mark Newman's repository of network datasets at the University of Michigan, located at the following URL:
+https://websites.umich.edu/~mejn/netdata/
+
+---
+---
+---
+
+### README for `highschool/network.gml`
+
+A network of friendships among male students in a small high school in Illinois from 1958. An arc points from student i to student j if i named j as a friend, in either of two identical surveys (from Fall and Spring semesters). Edge weights are the number of surveys in which the friendship was named.
+---
+
+### License
+These data can be cited as:
+
+  > J. S. Coleman, Introduction to Mathematical Sociology, London Free Press Glencoe (1964).
+
+---
+
+### Source
+
+This file was obtained from:
+https://networks.skewed.de/net/highschool#None_draw

doc/source/community_detection_guide/networks/export_game_of_thrones.py

@@ -0,0 +1,79 @@
+import pandas as pd
+import requests
+import io
+import os
+import igraph as ig
+
+def load_got_network(local_path: str = './game_of_thrones/got-s1-edges.csv', url: str = None):
+    """
+    Loads the Game of Thrones network dataset from a local CSV file. If the file is not found,
+    it downloads the data from a public GitHub repository. The function can also export
+    the resulting graph to a GraphML file.
+
+    Args:
+        local_path (str, optional): The path to the local CSV file.
+                                    Defaults to './game_of_thrones/got-s1-edges.csv'.
+        url (str, optional): The URL of the raw CSV data. This is used as a fallback.
+                             Defaults to "https://raw.githubusercontent.com/mathbeveridge/gameofthrones/master/data/got-s1-edges.csv".
+
+    Returns:
+        igraph.Graph: An igraph Graph object representing the network.
+    """
+    if url is None:
+        url = "https://raw.githubusercontent.com/mathbeveridge/gameofthrones/master/data/got-s1-edges.csv"
+
+    if os.path.exists(local_path):
+        print(f"Loading data from local file: {local_path}")
+        df_s1_edges = pd.read_csv(local_path)
+    else:
+        print(f"Local file not found at {local_path}. Attempting to download from GitHub...")
+        try:
+            response = requests.get(url)
+            response.raise_for_status() 
+            season1_edges_data = io.StringIO(response.text)
+            df_s1_edges = pd.read_csv(season1_edges_data)
+        except requests.exceptions.RequestException as e:
+            print(f"Error fetching data from {url}: {e}")
+            print("Please ensure you have an active internet connection or download the file manually.")
+            return None
+
+    if 'Weight' in df_s1_edges.columns:
+        edges_for_tuplelist = df_s1_edges[['Source', 'Target', 'Weight']].values.tolist()
+        g_s1 = ig.Graph.TupleList(edges_for_tuplelist, directed=False, weights=True)
+        print("Graph created with edge weights.")
+    else:
+        g_s1 = ig.Graph.TupleList(df_s1_edges[['Source', 'Target']].itertuples(index=False), directed=False)
+        print("Graph created without edge weights.")
+
+    return g_s1
+
+
+def export_graph_to_graphml(graph: ig.Graph, export_path: str):
+    """
+    Exports the given igraph Graph object to a GraphML file.
+
+    Args:
+        graph (igraph.Graph): The igraph Graph object to export.
+        export_path (str): The path where the GraphML file should be saved.
+    """
+    if export_path:
+        os.makedirs(os.path.dirname(export_path), exist_ok=True)
+        graph.write_graphml(export_path)
+        print(f"Graph exported to {export_path}")
+    else:
+        print("No export path provided. Graph not exported.")
+
+if __name__ == "__main__":
+    local_path = './game_of_thrones/got-s1-edges.csv'
+    export_path = './game_of_thrones/GoT.graphml'
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    full_local_path = os.path.join(script_dir, local_path)
+    full_export_path = os.path.join(script_dir, export_path)
+
+    g_s1 = load_got_network(local_path=full_local_path)
+    if g_s1:
+        export_graph_to_graphml(g_s1, full_export_path)
+    else:
+        print("Failed to load the Game of Thrones network.")
+