Metadata-Version: 2.4
Name: histwardb
Version: 0.1.0
Summary: A dynamic, programmatic historical and sovereign war dataset built on Wikidata.
Author: Vincenzo Manto
License: MIT License
        
        Copyright (c) 2026 Vincenzo Manto
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/VincenzoManto/histwardb
Project-URL: Repository, https://github.com/VincenzoManto/histwardb
Project-URL: Issues, https://github.com/VincenzoManto/histwardb/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: requests>=2.28
Requires-Dist: plotly>=5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# HistWarDB 🌍⚔️
> *Advanced Historical & Sovereign War Dataset powered by Wikidata*

[![Tests](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml/badge.svg)](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/1410596751.svg)](https://doi.org/10.5281/zenodo.23243673)

**HistoricalWarDB** (HistWarDB) is a dynamic, programmatic Python toolkit designed to extract, clean, and analyze global warfare data from Wikidata spanning from 1700 to the present. Built for researchers, historians, and data scientists, it bridges the gap between crowdsourced knowledge and rigorous historical data pipelines, supporting both modern sovereign states and historical empires.

---

## Key Features

* **Dynamic SPARQL Pipeline:** Fetches conflicts using 25-year temporal chunks to bypass query limits and ensure high data completeness.
* **Rigorous Anti-Noise Filtering:** Automatically excludes peacekeeping missions (`wd:Q35349`), military exercises (`wd:Q1151430`), and non-state actors.
* **Historical State Support:** Seamlessly tracks historical entities (e.g., *German Empire*, *Qing dynasty*, *Kingdom of Montenegro*) with built-in lifespan sanity checks.
* **Flexible Analytical Views:** Instantly transforms data into long formats, binary matrices (`0/1`), conflict name mappings, or custom `LIKE` keyword search results.
* **Interactive Visualizations:** Out-of-the-box Plotly heatmap generation to visualize global conflict intensity over centuries.
* **Tested and reproducible:** Network I/O, SPARQL query construction, and data-cleaning logic are separated into independent, unit-tested modules — no live Wikidata access required to run the test suite.

---

## Project layout

```
src/histwardb/
    query.py   # SPARQL query construction (pure, no I/O)
    core.py    # HistWarDB class: fetch, parse, clean, analytical views
tests/         # pytest suite (parsing, filtering, views, mocked network)
HistWarDB.ipynb  # usage demo notebook (Colab-compatible)
```

## Installation

```bash
pip install git+https://github.com/VincenzoManto/histwardb.git
```

For local development (editable install + test/lint tooling):

```bash
git clone https://github.com/VincenzoManto/histwardb.git
cd histwardb
pip install -e ".[dev]"
```

---

## Quick Start

```python
from histwardb import HistWarDB

# Initialize the dataset from 1700 to 2026
gwd = HistWarDB(start_year=1700, end_year=2026)

# Query specific countries in long format
france_uk_wars = gwd(countries=["France", "United Kingdom"], view="long", only_in_war=True)
print(france_uk_wars.head())

# Get a binary matrix for specific historical periods
binary_view = gwd(countries="German Empire", view="binary", from_date="1900-01-01", to_date="1918-12-31")

# Plot an interactive heatmap for the top 15 conflict-prone states
gwd.plot_heatmap(top_n=15, from_year=1800, to_year=2026).show()
```

---

## Supported Views (`view` parameter)

The dataset interface supports multiple analytical views via the `gwd(...)` call:

* **`"long"`**: Standard tidy DataFrame containing columns: `Country`, `Year`, `War_State`, and `Active_Conflicts`.
* **`"binary"`**: Wide pivot table with countries as rows, years as columns, and binary values (`1` = at war, `0` = peace).
* **`"names"`**: Wide pivot table containing the literal names of active conflicts per year.
* **`"list"`**: Alphabetical list of all unique conflict names extracted under current filters.
* **`"countries"` / `"conflicts"`**: Sorted lists of active entities or unique conflicts matching the query criteria.

---

## Testing

The test suite never queries the live Wikidata endpoint. The `HistWarDB`
class accepts an injectable `session` object for its HTTP calls, and all
parsing/filtering logic (`histwardb.core.parse_bindings`,
`clean_dataframe`, `build_long_grid`) is pure and tested against static
fixtures:

```bash
pip install -e ".[dev]"
pytest --cov=histwardb
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

---

## Citation

If you use **HistWarDB** in your academic research, working paper, or data science project, please cite it using the following format (also available in machine-readable form in [`CITATION.cff`](CITATION.cff)):

```bibtex
@software{histwardb2026,
  author = {Vincenzo Manto},
  title = {HistWarDB: A Dynamic Wikidata-Based Historical War Dataset},
  year = {2026},
  url = {https://github.com/VincenzoManto/histwardb}
}
```

---

## License

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.
