Metadata-Version: 2.4
Name: fpu-barometer
Version: 0.3.1
Summary: Free Press Unlimited researcher-facing API client
Project-URL: Homepage, https://www.freepressunlimited.org
Author: Phillip Kersten, Jannes Kelso, Jos Bartman
License-Expression: MIT
License-File: LICENSE.md
Keywords: barometer,data-science,fpu,journalists,press
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# fpu-barometer

A researcher-facing Python client for **Barometer**, Free Press Unlimited's platform for querying attacks on journalists (events) and socio-political regime indicators (predictors). Use it to access **live** harmonized data from a variety of sources, to research attacks on press.

---

## Get started

Install the package by running `pip install fpu-barometer` in your python environment. Then use `import fpu_barometer` to access the package in your script.No further configuration is needed.

---

## View datasets

**Example code**
```python
datasets: dict = fpu_barometer.list_datasets()
```

This will show the available datsets, when each was last updated, and how many data points each contains.

| Dataset | Type | Description |
|---|---|---|
| ACLED | Event | The Armed Conflict Location & Event Data Project (ACLED) catalogs conflict events, protests, and political violence worldwide. |
| CPJ | Event | The CPJ dataset is maintained by the Committee to Protect Journalists—a nonprofit organization dedicated to defending press freedom and protecting journalists around the world. This dataset compiles detailed records of journalist killings, attacks, and threats. |
| GDELT | Event | The Global Database of Events, Language, and Tone (GDELT) is one of the world's most expansive and continuously updated open data initiatives. It monitors broadcast, print, and web news from nearly every corner of the globe and processes this information using automated coding, natural language processing, and sentiment analysis. FPU has filtered this dataset to news related to attacks on journalists. |
| MFRR | Event | The Media Freedom Rapid Response (MFRR) dataset is an incident-level Event dataset documenting attacks, threats, and violations against journalists, media workers, and media freedom. |
| RR | Event | The Reporters Respond (RR) dataset is an incident-based dataset collected by the FPU team throughout their work. It contains information about journalists who have applied for support from the organization, the types of assistance provided, legal threats faced by journalists, and other relevant details. |
| VDEM | Predictor | The Varieties of Democracy (V-Dem) dataset is a comprehensive source for measuring democracy across multiple dimensions, with more than 470 unique indicators. |
| ERT | Predictor | The Episodes of Regime Transformation (ERT) dataset is a specialized subset derived from the V-Dem dataset. It identifies and catalogues discrete episodes of regime transformation—both democratization (liberalizing autocracies and democratic deepening) and autocratization (democratic regression and autocratic regression)—across the world. The dataset is designed to capture the gradual and often uncertain processes of regime change rather than treating regime transitions as singular, discrete events. |

---

## Access events

**Example code**
```python
events: DataFrame = fpu_barometer.get_events(
    events = ["acled", "mfrr"],
    countries = ["FRA"],
    years = [2025, 2026]    
)
```

| Column | Meaning |
| --- | --- |
| event_id | Globally unique Event identifier, prefixed by dataset key, e.g. `acled:123` or `mfrr:456`. |
| dataset | Lowercase dataset key, e.g. `acled`, `mfrr`, `cpj`. |
| iso3 | Canonical uppercase ISO3 country code. |
| country_name | Canonical country name derived from iso3, not copied directly from source text. |
| year | Event year used for Enrichment joins with Predictor data. Derive from canonical date. |
| date | Best available date anchor for the Event. |
| date_precision | Precision/provenance of date, such as day, month, year, submission_day, or publication_day. |
| type_of_incident | All Barometer incident taxonomy tags for the Event. List-valued. |
| top_type_of_incident | Top-level taxonomy tags only. List-valued. Physical assault; Attack to property; Verbal attack; Legal incident; Interference; Other; Unknown |
| type_of_incident_leaves | Leaf-level taxonomy tags only. List-valued. |
| processed_at | UTC timestamp when the Processor produced the row. |
| n_people_affected | Minimum known affected/attacked count; use a conservative fallback of 1 when the Event exists but the count is unknown. This may undercount the actual affected population, especially for broad/general-law rows. |
| region | Source-supported subnational or regional location. |
| latitude | Decimal latitude. |
| longitude | Decimal longitude. |
| description | Narrative description or summary. |
| source_url | Primary source/report URL when available. |
| attacked_count | Numeric source-provided attacked count when available. Non-numeric broad categories should be null here even when n_people_affected falls back to 1. |
| gender | Gender of affected person/people when available. |
| media_role | Journalist/media role when available. |
| perpetrator_type | Source-supported perpetrator/actor type when available. |
---

## Access predictors

**Example code**
```python
predictors: DataFrame = fpu_barometer.get_predictors(
    predictors = ["vdem", "ert"],
    countries = ["FRA"],
    years = [2025, 2026]    
)
```

| Column | Meaning |
| --- | --- |
| `dataset` | Lowercase dataset key, e.g. `vdem` or `ert`. |
| `iso3` | Canonical uppercase ISO3 country code. |
| `country_name` | Canonical country name derived from `iso3`, not copied directly from source text. |
| `year` | Predictor year used for Enrichment joins with Event data. |
| `processed_at` | UTC timestamp when the Processor produced the row. |

For further column information, view the [VDEM](https://v-dem.net/documents/70/codebook_v16.pdf) and [ERT](https://v-dem.net/documents/9/ert_codebook.pdf) codebooks.

---

## Combine events and predictors

**Example code**
```python
enriched: DataFrame = fpu_barometer.enrich_events(
    events=["acled", "mfrr"],
    predictors = ["vdem", "ert"],
    countries = ["FRA"],
    years = [2025, 2026]    
)
```

Joins predictor columns onto event rows, matching by country and year.
