Metadata-Version: 2.4
Name: graph-seeder
Version: 1.0.0.dev2
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
Requires-Dist: networkx<4.0.0,>=3.2.1
Requires-Dist: pandas<3.0.0,>=2.3.3
Requires-Dist: rdflib>=7.6.0
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=15.0.0
Requires-Dist: sparqlwrapper>=2.0.0
Requires-Dist: urllib3>=2.6.3
Description-Content-Type: text/markdown

# 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

```bash
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](https://docs.astral.sh/uv/#installation) by following the official guide
- Then run:

```bash
uv sync
```

#### Option B: using pip

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

```bash
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:
> ```bash
> 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

```bash
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

```bash
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

```bash
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.

```bash
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.

```bash
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  |
