graph-seeder 1.0.0.dev2__tar.gz → 1.0.0.dev3__tar.gz

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graph-seeder
-Version: 1.0.0.dev2
+Version: 1.0.0.dev3
 Summary: A powerful tool to extract and densify subgraphs from Knowledge Graphs via SPARQL or LMDB, with different extraction strategies.
 Requires-Python: >=3.9
 Requires-Dist: lmdb>=2.2.0

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/graph_seeder"]
 
 [project]
 name = "graph-seeder"
-version = "1.0.0.dev2"
+version = "1.0.0.dev3"
 description = "A powerful tool to extract and densify subgraphs from Knowledge Graphs via SPARQL or LMDB, with different extraction strategies."
 readme = "README.md"
 requires-python = ">=3.9"

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/SubgraphExtractor.py

@@ -102,9 +102,9 @@ class SubgraphExtractor:
             raise ValueError("Data config requires an 'input_path' to a CSV file.")
 
         output_format = data_cfg.get("output_format", {})
-        if output_format not in ["csv", "json", "ttl"]:
+        if output_format not in ["json", "ttl"]:
             raise ValueError(
-                "Data config 'output_format' must be one of: 'csv', 'json', 'ttl'."
+                "Data config 'output_format' must be one of: 'json', 'ttl'."
             )
 
         # Validate client config
@@ -242,10 +242,8 @@ class SubgraphExtractor:
 
             return []
 
-    def extract_subgraph(
-        self, seeds: list[str]
-    ) -> tuple[list[tuple[str, str, str]], set[str]]:
-        all_triplets: list[tuple[str, str, str]] = []
+    def extract_subgraph(self, seeds: list[str]) -> tuple[list[dict], set[str]]:
+        all_paths: list[dict] = []
         seeds_found: set[str] = set()
 
         with self.ui.create_progress_bar() as progress:
@@ -266,24 +264,28 @@ class SubgraphExtractor:
                 if not triplets:
                     self.stats["not_found"] += 1
                 else:
-                    all_triplets.extend(triplets)
+                    all_paths.append(
+                        {
+                            "seed": clean_nodes[0],
+                            "target": clean_nodes[1] if len(clean_nodes) > 1 else None,
+                            "triples": triplets,
+                        }
+                    )
                     seeds_found.update(clean_nodes)
                     self.stats["found"] += 1
 
-        self.exporter.save_triplets(all_triplets, self.uri_manager.namespaces)
+        self.exporter.save_results(all_paths, self.uri_manager)
         self.exporter.save_graph(self.extractor_strategy.graph)
 
         logger.info("Computing final graph statistics...")
 
         self.print_final_summary(
-            all_triplets, self.extractor_strategy.graph, "Extraction summary"
+            all_paths, self.extractor_strategy.graph, "Extraction summary"
         )
 
-        return all_triplets, seeds_found
+        return all_paths, seeds_found
 
-    def densify_graph(
-        self, triplets: list[tuple[str, str, str]], seeds_found: set[str]
-    ):
+    def densify_graph(self, all_paths: list[dict], seeds_found: set[str]):
         explored_nodes = self.extractor_strategy.explored_nodes
 
         graph_connector: GraphConnector = GraphConnector(
@@ -294,22 +296,20 @@ class SubgraphExtractor:
             self.ui,
             self.cfg,
         )
-        nb_components = get_connected_components(triplets)
+        nb_components = get_connected_components(all_paths)
         if len(nb_components) > 1:
             logger.warning(
                 f"The extracted graph has {len(nb_components)} disconnected components. Starting densification to connect them...\n"
             )
 
-            new_triplets = graph_connector.connect(seeds_found, triplets)
+            densified_paths = graph_connector.connect(all_paths, seeds_found)
 
-            logger.info(
-                f"Found {len(new_triplets) - len(triplets)} new triplets during densification."
+            self.save(
+                densified_paths, graph_connector.bfs.graph, name_suffix="_densified"
             )
 
-            self.save(new_triplets, graph_connector.bfs.graph, name_suffix="_densified")
-
             self.print_final_summary(
-                new_triplets,
+                densified_paths,
                 graph_connector.bfs.graph,
                 "Densification summary",
                 "_densified",
@@ -321,23 +321,23 @@ class SubgraphExtractor:
 
     def print_final_summary(
         self,
-        all_triplets: list[tuple[str, str, str]],
+        paths: list[dict],
         graph: nx.MultiGraph,
         table_title: str,
         name_suffix: str = "",
     ) -> None:
-        detailed_stats = GraphStatistics.compute(all_triplets)
+        detailed_stats = GraphStatistics.compute(paths)
         self.ui.print_summary(self.stats, detailed_stats, graph, table_title)
 
         self.exporter.save_stats(self.stats, detailed_stats, name_suffix)
 
     def save(
         self,
-        triplets: list[tuple[str, str, str]],
+        paths: list[dict],
         graph: nx.MultiGraph,
         name_suffix: str = "",
     ) -> None:
-        self.exporter.save_triplets(triplets, self.uri_manager.namespaces, name_suffix)
+        self.exporter.save_results(paths, self.uri_manager, name_suffix)
         self.exporter.save_graph(graph, name_suffix)
 
     def run(self) -> None:
@@ -352,7 +352,9 @@ class SubgraphExtractor:
             )
             return
 
-        unique_seeds = list(set([str(seed).strip() for row in seeds for seed in row]))
+        unique_seeds = list(
+            dict.fromkeys([str(seed).strip() for row in seeds for seed in row])
+        )
 
         if self.check_seeds_validity:
             invalid_seeds = self._check_seeds_validity(unique_seeds)
@@ -389,13 +391,13 @@ class SubgraphExtractor:
                 seeds = [list(pair) for pair in itertools.combinations(unique_seeds, 2)]
                 logger.info(f"Created {len(seeds)} pairs to explore.\n")
 
-        all_triplets, seeds_found = self.extract_subgraph(seeds)
+        all_paths, seeds_found = self.extract_subgraph(seeds)
 
-        if not all_triplets:
-            logger.error("No triplets were extracted. Exiting without saving.")
+        if not all_paths:
+            logger.error("No paths were extracted. Exiting without saving.")
             return
 
         if self.skip_densification:
             return
 
-        self.densify_graph(all_triplets, seeds_found)
+        self.densify_graph(all_paths, seeds_found)

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/configs/dbpedia_default.json

@@ -1,7 +1,7 @@
 {
     "data": {
         "input_path": "seed.csv",
-        "output_format": "csv",
+        "output_format": "json",
         "output_path": "output/result",
         "stats_output_path": "output/stats.json"
     },
@@ -40,7 +40,7 @@
     "extraction": {
         "strategy": "bfs",
         "create_all_pairs": false,
-        "batch_size": 15,
+        "batch_size": 30,
         "max_hops": 6,
         "hub_pagination_threshold": 70000,
         "max_neighbors_threshold": 300000,

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/configs/default.json

@@ -1,7 +1,7 @@
 {
     "data": {
         "input_path": "seeds.csv",
-        "output_format": "csv",
+        "output_format": "json",
         "output_path": "output/result",
         "stats_output_path": "output/stats.json"
     },

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/configs/europeana_default.json

@@ -1,7 +1,7 @@
 {
     "data": {
         "input_path": "seed.csv",
-        "output_format": "csv",
+        "output_format": "json",
         "output_path": "output/result",
         "stats_output_path": "output/stats.json"
     },
@@ -31,7 +31,7 @@
     "extraction": {
         "strategy": "bfs",
         "create_all_pairs": false,
-        "batch_size": 15,
+        "batch_size": 30,
         "max_hops": 6,
         "hub_pagination_threshold": 60000,
         "max_neighbors_threshold": 150000,

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/configs/pgxlod_default.json

@@ -1,9 +1,9 @@
 {
     "data": {
         "input_path": "seed.csv",
-        "output_format": "csv",
+        "output_format": "json",
         "output_path": "output/result",
-        "stats_output_path": "output/stats.json" 
+        "stats_output_path": "output/stats.json"
     },
     "client": {
         "type": "SPARQL",
@@ -19,16 +19,16 @@
         "include_uri_prefixes": [],
         "exclude_uri_prefixes": [],
         "exclude_nodes": [],
-      "exclude_properties": [],
-      "namespaces": {
-        "pharmgkb": "http://bio2rdf.org/pharmgkb",
-        "pgxlod": "http://pgxlod.loria.fr/resource/"
-      }
+        "exclude_properties": [],
+        "namespaces": {
+            "pharmgkb": "http://bio2rdf.org/pharmgkb",
+            "pgxlod": "http://pgxlod.loria.fr/resource/"
+        }
     },
     "extraction": {
         "strategy": "bfs",
         "create_all_pairs": false,
-        "batch_size": 15,
+        "batch_size": 30,
         "max_hops": 6,
         "hub_pagination_threshold": 60000,
         "max_neighbors_threshold": 150000,
@@ -46,4 +46,4 @@
         "debug_enabled": false,
         "request_logging": false
     }
-}
+}

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/configs/wikidata_default.json

@@ -1,7 +1,7 @@
 {
     "data": {
         "input_path": "seed.csv",
-        "output_format": "csv",
+        "output_format": "json",
         "output_path": "output/result",
         "stats_output_path": "output/stats.json"
     },

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/densification/GraphConnector.py

@@ -47,16 +47,21 @@ class GraphConnector:
             return comp_seeds[0]
 
     def connect(
-        self, found_seeds: set[str], triplets: list[tuple[str, str, str]]
-    ) -> list[tuple[str, str, str]]:
-        new_triplets: list[tuple[str, str, str]] = list(triplets)
+        self,
+        initial_paths: list[dict],
+        found_seeds: set[str],
+    ) -> list[dict]:
+
+        current_paths: list[dict] = list(initial_paths)
         failed_component_pairs = set()
 
+        initial_triplets_count = sum(len(p.get("triples", [])) for p in current_paths)
+
         with self.ui.create_progress_bar() as progress:
             task = progress.add_task("Components densification", total=None)
 
             while True:
-                components = get_connected_components(new_triplets)
+                components = get_connected_components(current_paths)
 
                 if len(components) <= 1:
                     current_completed = progress.tasks[0].completed
@@ -96,19 +101,30 @@ class GraphConnector:
                 source = self._pick_representative(list(seeds_a))
                 target = self._pick_representative(list(seeds_b))
 
-                triplets = self.bfs.execute_task(
+                path_triplets = self.bfs.execute_task(
                     [source, target],
                     progress,
                     task,
                 )
 
-                if triplets:
-                    new_triplets.extend(triplets)
-                    for s, p, o in triplets:
+                if path_triplets:
+                    new_path = {
+                        "seed": source,
+                        "target": target,
+                        "triples": path_triplets,
+                    }
+                    current_paths.append(new_path)
+
+                    for s, p, o in path_triplets:
                         self.graph.add_edge(s, o)
                 else:
                     failed_component_pairs.add(
                         tuple(sorted([tuple(seeds_a), tuple(seeds_b)]))
                     )
 
-        return new_triplets
+        final_triplets_count = sum(len(p.get("triples", [])) for p in current_paths)
+        logger.info(
+            f"Found {final_triplets_count - initial_triplets_count} new triplets during densification."
+        )
+
+        return current_paths

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/utils/ConsoleUI.py

@@ -251,7 +251,7 @@ class ConsoleUI:
 
         table.add_section()
         table.add_row("Graph nodes", str(len(graph.nodes)))
-        table.add_row("Graph edges", str(len(graph.edges)))
+        table.add_row("Unique triples in graph", str(len(graph.edges)))
 
         self.console.print(
             Panel(table, title=f"[bold green]{table_title}[/]", expand=False)

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/utils/GraphExporter.py

@@ -1,24 +1,18 @@
-import csv
 import json
 import logging
 import pickle
 from pathlib import Path
-
 import networkx as nx
-from rdflib import Graph, Namespace, URIRef
+from rdflib import Graph, Namespace, URIRef, Literal
+from graph_seeder.utils.URIManager import URIManager
 
 logger = logging.getLogger("subgraph")
 
 
 class GraphExporter:
-    """Export triplets and graphs to disk in various formats."""
+    """Export paths and graphs to disk in various formats."""
 
     def __init__(self, data_cfg: dict) -> None:
-        """Initialize exporter settings.
-
-        Args:
-            output_format: Target format for triplet export.
-        """
         self.output_format = data_cfg.get("output_format")
         self.output_path = Path(data_cfg.get("output_path", ".")).resolve()
         self.output_path.parent.mkdir(parents=True, exist_ok=True)
@@ -28,51 +22,67 @@ class GraphExporter:
         if self.stats_output_path:
             self.stats_output_path.parent.mkdir(parents=True, exist_ok=True)
 
-    def save_triplets(
+    def save_results(
         self,
-        triplets: list[tuple[str, str, str]],
-        namespaces: dict[str, str],
+        extracted_paths: list[dict],
+        uri_manager: URIManager,
         name_suffix: str = "",
     ) -> None:
-        """Write triplets to disk using the configured output format.
-
-        Args:
-            triplets: Sequence of ``(subject, predicate, object)`` identifiers.
-            namespaces: Dictionary mapping namespace prefixes to URIs.
-            name_suffix: Optional suffix for the output file name (before extension).
-
-        Raises:
-            ValueError: If the configured output format is not supported.
-        """
+        """Write extracted paths to disk using the configured output format."""
         path = self.output_path.with_name(
             f"{self.output_path.stem}{name_suffix}.{self.output_format}"
         )
         fmt = self.output_format
-        if fmt == "csv":
-            with open(path, "w", newline="", encoding="utf-8") as f:
-                writer = csv.writer(f)
-                writer.writerow(["subject", "predicate", "object"])
-                writer.writerows(triplets)
-
-        elif fmt == "json":
-            data = [{"subject": s, "predicate": p, "object": o} for s, p, o in triplets]
+
+        if fmt == "json":
+            compressed_paths = []
+            for path_data in extracted_paths:
+                compressed_paths.append(
+                    {
+                        "seed": uri_manager.compress_uri(path_data["seed"]),
+                        "target": uri_manager.compress_uri(path_data["target"]),
+                        "triples": [
+                            [
+                                uri_manager.compress_uri(s),
+                                uri_manager.compress_uri(p),
+                                uri_manager.compress_uri(o),
+                            ]
+                            for s, p, o in path_data.get("triples", [])
+                        ],
+                    }
+                )
+
+            final_json = {"@context": uri_manager.namespaces, "paths": compressed_paths}
+
             with open(path, "w", encoding="utf-8") as f:
-                json.dump(data, f, indent=2)
+                json.dump(final_json, f, indent=2)
 
         elif fmt == "ttl":
             rdf = Graph()
 
-            for prefix, uri in namespaces.items():
+            for prefix, uri in uri_manager.namespaces.items():
                 rdf.bind(prefix, Namespace(uri))
 
-            for s, p, o in triplets:
-                rdf.add((URIRef(s), URIRef(p), URIRef(o)))
+            added_triples = set()
+
+            for path_data in extracted_paths:
+                for s, p, o in path_data.get("triples", []):
+                    if (s, p, o) not in added_triples:
+                        obj_node = (
+                            URIRef(o) if str(o).startswith("http") else Literal(o)
+                        )
+
+                        rdf.add((URIRef(s), URIRef(p), obj_node))
+                        added_triples.add((s, p, o))
 
             rdf.serialize(destination=str(path), format="turtle")
+
         else:
-            raise ValueError(f"Unsupported output format: {fmt!r}")
+            raise ValueError(
+                f"Unsupported output format: '{fmt}'. Please use 'json' or 'ttl'."
+            )
 
-        logger.info(f"Triplets saved → [bold]{path}[/]")
+        logger.info(f"Results saved → [bold]{path}[/]")
 
     def save_graph(self, graph: nx.MultiGraph, name_suffix: str = "") -> None:
         """Serialize a NetworkX graph to a gpickle file.

graph_seeder-1.0.0.dev3/src/graph_seeder/utils/GraphStatistics.py

@@ -0,0 +1,41 @@
+import statistics
+from graph_seeder.utils.utils import get_connected_components
+
+
+class GraphStatistics:
+    """Utility class for computing statistics on a graph."""
+
+    @staticmethod
+    def compute(paths: list[dict]) -> dict:
+        """Compute statistics on the graph given the extracted paths."""
+        subjects = set()
+        predicates = set()
+        objects = set()
+        triplets = []
+
+        for path_data in paths:
+            for s, p, o in path_data.get("triples", []):
+                triplets.append((s, p, o))
+                subjects.add(s)
+                predicates.add(p)
+                objects.add(o)
+
+        unique_entities = len(subjects | objects)
+
+        components = get_connected_components(paths)
+
+        comp_sizes = [len(comp) for comp in components]
+        mean_size = statistics.mean(comp_sizes) if comp_sizes else 0
+        stdev_size = statistics.stdev(comp_sizes) if len(comp_sizes) > 1 else 0
+
+        return {
+            "Traversed triples": len(triplets),
+            "Unique triples": len(set(triplets)),
+            "Unique subjects": len(subjects),
+            "Unique predicates": len(predicates),
+            "Unique objects": len(objects),
+            "Unique entities": unique_entities,
+            "Connected components": len(components),
+            "Mean component size": round(mean_size, 2),
+            "Std dev component size": round(stdev_size, 2),
+        }

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/src/graph_seeder/utils/utils.py

@@ -221,7 +221,9 @@ def load_config(config_path: str | None, overrides: dict) -> dict:
     return cfg
 
 
-def get_connected_components(triplets: list[tuple[str, str, str]]) -> list[set[str]]:
+def get_connected_components(paths: list[dict]) -> list[set[str]]:
+    """Get the connected components from a list of structured paths."""
     graph: nx.Graph = nx.Graph()
-    graph.add_edges_from((s, o) for s, p, o in triplets)
+    for path_data in paths:
+        graph.add_edges_from((s, o) for s, p, o in path_data.get("triples", []))
     return list(nx.connected_components(graph))

{graph_seeder-1.0.0.dev2 → graph_seeder-1.0.0.dev3}/uv.lock

@@ -147,7 +147,7 @@ wheels = [
 
 [[package]]
 name = "graph-seeder"
-version = "1.0.0.dev2"
+version = "1.0.0.dev3"
 source = { editable = "." }
 dependencies = [
     { name = "lmdb" },

graph_seeder-1.0.0.dev2/src/graph_seeder/utils/GraphStatistics.py

@@ -1,32 +0,0 @@
-import networkx as nx
-
-
-class GraphStatistics:
-    """Utility class for computing statistics on a graph."""
-
-    @staticmethod
-    def compute(triplets: list[tuple[str, str, str]]) -> dict:
-        """Compute statistics on the graph given a list of triplets and the graph itself."""
-        subjects = set()
-        predicates = set()
-        objects = set()
-        triplets_graph = nx.Graph()
-
-        for s, p, o in triplets:
-            subjects.add(s)
-            predicates.add(p)
-            objects.add(o)
-            triplets_graph.add_edge(s, o)
-
-        nb_components = nx.number_connected_components(triplets_graph)
-
-        unique_entities = len(subjects | objects)
-
-        return {
-            "total_triplets": len(triplets),
-            "unique_subjects": len(subjects),
-            "unique_predicates": len(predicates),
-            "unique_objects": len(objects),
-            "unique_entities": unique_entities,
-            "connected_components": nb_components,
-        }