graph-seeder 1.0.0.dev2

A powerful tool to extract and densify subgraphs from Knowledge Graphs via SPARQL or LMDB, with different extraction strategies.

Graph densifier

Graph Densifier is a collection of tools that can be used for enriching, analyzing, and extracting subgraphs from knowledge graphs represented as triplet datasets.

It offers the following functions:

• Densify graphs by enriching an existing knowledge graph with additional Wikidata triplets between known entities.
• Compute statistics to analyze the graph's composition and connectivity.
• Extract paths from Wikidata dynamically by finding connections between pairs of entities.
• Extract local subgraphs from an existing dataset using shortest paths or neighborhood expansion around seed entities.

Installation

Follow these steps to set up the project locally:

1. Clone the repository

git clone https://github.com/Wimmics/graph-densifier.git
cd graph-densifier

2. Install dependencies

Option A (recommended): using uv

We recommend using uv for fast and reliable dependency management.

• Install uv by following the official guide
• Then run:

uv sync

Option B: using pip

If you prefer not to use uv, you can install dependencies with pip:

pip install -r requirements.txt

3. Environment configuration

[!note] To avoid being rate-limited or blocked when querying Wikidata, you should configure a user identity.

• Create a .env file at the root of the project
• Add the following line to the file with your Wikidata username:

USER_AGENT="graph_densify/1.0 (contact: wikidata_username)"

While this step is not strictly required to run the project, it is recommended. Without it, requests to Wikidata may be throttled or blocked during large runs, which can interrupt the graph densification and path extraction processes.

Usage

The project provides four main scripts:

1. graph_densify.py – enrich a local graph with additional Wikidata triplets.
2. statistics.py – compute statistics for a triplet dataset.
3. subgraph_extract.py – query Wikidata to find paths between entity pairs.
4. hashmap_extract_subgraph.py – extract relevant subgraphs from a local CSV graph.

1. Graph Densification (graph_densify.py)

This script enriches the input graph by querying Wikidata for additional relationships between entities already present in the graph. It identifies all unique entities in the subject and object columns and adds any newly discovered direct relations to the dataset.

Command

python src/graph_densify.py --input path/to/input.csv --output path/to/output.csv

2. Graph Statistics (statistics.py)

This script computes descriptive statistics for a triplet dataset and generates a summary CSV file in the stat/ directory.

Command

python src/statistics.py --input path/to/graph.csv

Computed Statistics

Metric	Description
total_triplets	Total number of triplets
unique_subjects	Number of unique subjects
unique_predicates	Number of unique predicates
unique_objects	Number of unique objects
unique_entities	Unique entities across subjects and objects
unique_subject_object_pairs	Distinct (subject, object) pairs
connected_components	Number of weakly connected components in the graph

3. Wikidata Path Extraction (subgraph_extract.py)

This script takes a list of entity pairs and dynamically queries Wikidata to find a short path (not necessarily the shortest) between them. It outputs the discovered path triplets as a CSV and saves the explored network as a .gpickle graph file.

Command

python src/subgraph_extract.py --input path/to/pairs.csv --output path/to/extracted_paths.csv

---

4. Local Subgraph Extraction (hashmap_extract_subgraph.py)

This script extracts subgraphs from a local graph dataset (CSV) using one of the two modes:

Mode A — Shortest paths between seed/target pairs

Extracts all shortest paths between specified source-target entity pairs.

python src/hashmap_extract_subgraph.py \
    --sub_graph path/to/main_graph.csv \
    --seed_target_pairs path/to/pairs.csv

Mode B — Radius around seed nodes

Extracts all nodes within a specified number of hops (default: 2) from a list of seed entities.

python src/hashmap_extract_subgraph.py \
    --sub_graph path/to/main_graph.csv \
    --seeds_only path/to/seeds.csv \
    --max_length 2

Output: The extracted subgraph is saved by default to data/extracted_subgraph.csv.

---

Dataset Structure

All datasets are expected to be provided as CSV files.

Main Graph Dataset

Must contain three columns representing a knowledge graph triplet:

subject	predicate	object
Q937	P36	Q90
Q90	P17	Q142

Seed-Target Pair Dataset

Used for finding paths between specific entities. Must contain two columns:

subject	object
Q937	Q304
Q90	Q183

Seed-Only Dataset

Used for neighborhood expansion. Must contain one column representing the seed entity (the column can be named seed or be the first column):

seed
Q937
Q90