oda-data 2.1.2__tar.gz → 2.2.0__tar.gz

{oda_data-2.1.2 → oda_data-2.2.0}/PKG-INFO

@@ -1,27 +1,21 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: oda_data
-Version: 2.1.2
+Version: 2.2.0
 Summary: A python package to work with Official Development Assistance data from the OECD DAC.
+Author-email: Jorge Rivera <jorge.rivera@one.org>, Miguel Haro Ruiz <miguel.haroruiz@one.org>
 License: MIT
-Author: Jorge Rivera
-Author-email: jorge.rivera@one.org
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: cachetools (>=5.5.1,<7.0.0)
-Requires-Dist: oda-reader (>=1.2,<2.0)
-Requires-Dist: pandas (>=2)
-Requires-Dist: pyarrow (>=14,<22)
-Requires-Dist: pydeflate (>=2.0.1)
-Requires-Dist: thefuzz (>=0.22.1)
-Project-URL: Documentation, https://github.com/ONEcampaign/oda_data_package
 Project-URL: Homepage, https://github.com/ONEcampaign/oda_data_package
 Project-URL: Repository, https://github.com/ONEcampaign/oda_data_package
+Project-URL: Documentation, https://github.com/ONEcampaign/oda_data_package
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cachetools>=6.2.0
+Requires-Dist: pandas[excel,parquet,performance]>=2.3.2
+Requires-Dist: pydeflate>=2.1.3
+Requires-Dist: reader>=3.18
+Requires-Dist: thefuzz>=0.22.1
+Dynamic: license-file
 
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
 [![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
@@ -345,4 +339,3 @@ request it via the [issues page](https://github.com/ONEcampaign/oda_data_package
 
 ## Contributing
 Interested in contributing to the package? Please reach out.
-

{oda_data-2.1.2 → oda_data-2.2.0}/oda_data/__init__.py

@@ -2,29 +2,33 @@ from importlib.metadata import version
 
 __version__ = version("oda_data")
 
+from oda_reader import clear_cache, disable_cache, enable_cache, set_cache_dir
+
 from oda_data import tools
-from oda_reader import set_cache_dir, disable_cache, enable_cache, clear_cache
 from oda_data.api.oecd import OECDClient
 from oda_data.api.sources import (
+    AidDataData,
+    CRSData,
     DAC1Data,
     DAC2AData,
     MultiSystemData,
-    CRSData,
-    AidDataData,
 )
 from oda_data.indicators.research.policy_markers import bilateral_policy_marker
 from oda_data.tools.compatibility import ODAData
 from oda_data.tools.gni import add_gni_share_column
 from oda_data.tools.groupings import provider_groupings, recipient_groupings
 from oda_data.tools.names.add import add_names_columns
-from oda_data.tools.sector_lists import add_sectors, add_broad_sectors
+from oda_data.tools.sector_lists import add_broad_sectors, add_sectors
+from oda_data.indicators.research import sector_imputations
 
 
 def set_data_path(path):
     from pathlib import Path
-    from oda_data.config import ODAPaths
+
     from pydeflate import set_pydeflate_path
 
+    from oda_data.config import ODAPaths
+
     """Set the path to the data folder."""
     global ODAPaths
 
@@ -56,4 +60,5 @@ __all__ = [
     "disable_cache",
     "enable_cache",
     "clear_cache",
+    "sector_imputations",
 ]

oda_data-2.2.0/oda_data.egg-info/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: oda_data
+Version: 2.2.0
+Summary: A python package to work with Official Development Assistance data from the OECD DAC.
+Author-email: Jorge Rivera <jorge.rivera@one.org>, Miguel Haro Ruiz <miguel.haroruiz@one.org>
+License: MIT
+Project-URL: Homepage, https://github.com/ONEcampaign/oda_data_package
+Project-URL: Repository, https://github.com/ONEcampaign/oda_data_package
+Project-URL: Documentation, https://github.com/ONEcampaign/oda_data_package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cachetools>=6.2.0
+Requires-Dist: pandas[excel,parquet,performance]>=2.3.2
+Requires-Dist: pydeflate>=2.1.3
+Requires-Dist: reader>=3.18
+Requires-Dist: thefuzz>=0.22.1
+Dynamic: license-file
+
+[![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
+[![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# The ODA Data Package
+This is a Python package designed for accessing, processing, and analyzing Official Development Assistance (ODA) data from OECD DAC. With an intuitive API, it simplifies common tasks like retrieving ODA indicators, converting currencies, filtering data, and handling bulk downloads.
+
+**Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
+will not work. The previous 1.5.x version remains available on PyPI and we will continue to support it at least until
+August 2025.**
+
+Interacting with the DAC databases can be a complex task. There are many databases, tables, and web interfaces which
+can be used to get the data you need. This means that getting the right ODA data can require expert knowledge not only
+of ODA, but also of how the DAC databases and tools are organised.
+
+This package aims to simplify this process and make it easier for users to get the data they need.
+
+Please submit questions, feedback or requests via 
+the [issues page](https://github.com/ONEcampaign/oda_data_package/issues).
+
+## Getting started
+
+### Installation
+
+The latest version of the package can be installed using pip:
+
+```bash
+pip install oda-data --upgrade
+```
+
+The package is compatible with Python 3.10 and above.
+
+## Basic usage
+
+Most users can get the data they need by using the `OECDClient` class.
+
+An object of this class can handle:
+- getting data for specific indicators (one or more)
+- filtering the data for specific donors, recipients(if relevant), years.
+- returning the data in a variety of currency/prices combinations.
+
+At a minimum, the class expects users to specify years. By default it would then get 
+data for all providers, for all recipients (if applicable), as net disbursements in USD, in current prices,
+using the OECD data-explorer API.
+
+In the example below, we get all data for Total ODA (net disbursements), for 2012 to 2022.
+
+```python
+from oda_data import OECDClient, set_data_path
+
+# set the path to the folder where the raw data should be cached
+set_data_path("path/to/data/folder")
+
+# create object, specifying key details of the desired output
+indicator = OECDClient(years=range(2012, 2023))
+
+# Get the desired indicator
+data = indicator.get_indicators("DAC1.10.1010")
+```
+
+Here's an example to get Bilateral ODA for France and the US, for 2020 and 2021. The data will be in grant equivalents, in constant 2019 Euros.
+
+```python
+from oda_data import OECDClient, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# create object, specifying key details of the desired output
+client = OECDClient(
+    years=[2020, 2021],
+    providers=[4, 302],  # Example provider codes
+    measure="grant_equivalent",  # Options: "commitment", "grant_equivalent", etc.
+    currency="EUR",  # Default is USD; others include EUR, GBP, CAD, LCU
+    base_year=2019,  # Adjust data to constant prices of the specified year
+)
+
+# Get the desired indicator
+data = client.get_indicators("DAC1.10.11015")
+```
+
+If you intend to download many indicators, we recommend using the Bulk download file instead. The OECD data-explorer
+API has pretty low usage limits, and you could get a temporary block if you make too many repeated calls. While downloading a particular bulk file may time a few minutes, subsequently getting indicator data is much faster.
+
+```python
+from oda_data import OECDClient, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# define a list of indicators to get
+research_indicators = ["DAC1.10.1100", "DAC1.10.1410", "DAC1.10.2102", "DAC1.10.1500"]
+
+# create object, specifying key details of the desired output
+client = OECDClient(
+    years=[2019, 2020, 2021],
+    measure="net_disbursement",  # Options: "commitment", "grant_equivalent", etc.
+    currency="LCU",  # To get the data in providers' own currencies
+    use_bulk_download=True
+)
+
+# Get the desired indicators
+data = client.get_indicators(research_indicators)
+```
+
+### OECDClient
+
+Over three thousand indicators are currently supported. They are mostly produced by filtering (and sometimes aggregating) data from the different DAC Tables and databases.
+
+You can get a dictionary with all supported indicators, with their code, name, description and source by using the `.available_indicators()` method:
+
+```python
+from oda_data import OECDClient
+
+all_indicators = OECDClient.available_indicators()
+```
+
+Alternatively, you can export the indicators to a CSV by using the `.export_available_indicators()` method.
+
+```python
+from oda_data import OECDClient
+
+OECDClient.export_available_indicators(export_folder="path/to/folder/")
+```
+
+### Providers
+You can get a dictionary with all available providers, with their code and name, by using the `.available_providers()` method:
+
+```python
+from oda_data import OECDClient
+
+providers = OECDClient.available_providers()
+```
+
+### Recipients
+You can get a dictionary with all available recipients, with their code and name, by using the `.available_recipients()` method:
+
+```python
+from oda_data import OECDClient
+
+recipients = OECDClient.available_recipients()
+```
+
+### Currencies
+You can get a dictionary with all available currencies, with their code and name, by using the `.available_currencies()` method:
+
+```python
+from oda_data import OECDClient
+
+currencies = OECDClient.available_currencies()
+```
+
+## Accessing the data
+For more advanced users, you can use this package to get and work with different tables and databases from the OECD DAC.
+
+### DAC 1
+The `DAC1Data` class can retrieve and return DAC 1 data.
+
+You can optionally specify:
+- years: to filter the data for specific years
+- providers: to filter the data for specific providers (based on their code).
+- indicators: to filter the data for a specific indicator (for DAC1 this means AIDTYPE_CODE)
+
+Not specifying any or all of these parameters will return all the available data.
+
+After instantiating the object, you can call:
+- `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
+- `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
+
+```python
+from oda_data import DAC1Data, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# instantiate a DAC1Data object
+dac1 = DAC1Data()
+
+# Perform a bulk download
+dac1.download(bulk=True)
+
+# Read the stored data in full
+data = dac1.read(using_bulk_download=True)
+```
+
+Use cases can be quite elaborate. For example, here we will download data for France for 2022 only, for total ODA (net flows).
+
+When reading, we will also filter to get only current prices, and to only read a few columns.
+
+```python
+from oda_data import DAC1Data, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# instantiate a DAC1Data object
+dac1 = DAC1Data(years=2022, providers=4, indicators=1010)
+
+# Get the data by calling on read. It will be downloaded since it isn't already available.
+data = dac1.read(
+    additional_filters=[("amount_type", "==", "Current prices")],
+    columns=["donor_name", "aid_type", "fund_flows", "amount_type", "year", "value"],
+)
+```
+
+
+### DAC 2A
+The `DAC2AData` class can retrieve and return DAC2a data.
+
+You can optionally specify:
+- years: to filter the data for specific years
+- providers: to filter the data for specific providers (based on their code).
+- recipients: to filter the data for specific recipients (based on their code).
+- indicators: to filter the data for a specific indicator (for DAC2a this means AIDTYPE_CODE)
+
+Not specifying any or all of these parameters will return all the available data.
+
+After instantiating the object, you can call:
+- `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
+- `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
+
+```python
+from oda_data import DAC2AData, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# instantiate a DAC1Data object
+dac2a = DAC2AData()
+
+# Perform a bulk download
+dac2a.download(bulk=True)
+
+# Read the stored data in full
+data = dac2a.read(using_bulk_download=True)
+```
+
+Use cases can be quite elaborate. For example, here we will download data for France - Togo for 2023 only, for imputed
+multilateral aid.
+
+When reading, we will also filter to get only current prices, and to only read a few columns.
+
+```python
+from oda_data import DAC2AData, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# instantiate a DAC2aData object
+dac2a = DAC2AData(years=2022, providers=4, recipients=283, indicators=106)
+
+# Get the data by calling on read. It will be downloaded since it isn't already available.
+data = dac2a.read(
+    additional_filters=[("amount_type", "==", "Current prices")],
+    columns=[
+        "donor_name",
+        "recipient_name",
+        "aid_type",
+        "flow_type_name",
+        "amount_type",
+        "year",
+        "value",
+    ],
+)
+```
+
+### CRS
+The `CRSData` class can retrieve and return CRS data.
+
+You can optionally specify:
+- years: to filter the data for specific years
+- providers: to filter the data for specific providers (based on their code).
+- recipients: to filter the data for specific recipients (based on their code).
+
+Not specifying any or all of these parameters will return all the available data.
+
+You can refer to the examples above for DAC1 and DAC2a to understand the usage of these classes.
+**Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the 
+bulk option when using the CRS class.
+
+```python
+from oda_data import CRSData, set_data_path
+
+# set the path to the folder where the data should be stored
+set_data_path("path/to/data/folder")
+
+# instantiate a CRSData object
+crs = CRSData(years=range(2010, 2024))
+
+# Get the data by calling on read. It will be downloaded since it isn't already available.
+data = crs.read(using_bulk_download=True)
+```
+
+
+### MultiSystem
+The `MultiSystemData` class can retrieve and return Providers Total Use of the Multilateral System data.
+
+You can optionally specify:
+- years: to filter the data for specific years
+- providers: to filter the data for specific providers (based on their code).
+- recipients: to filter the data for specific recipients (based on their code).
+- indicators: to filter for specific indicators (aid_to_or_thru in this case)
+- sectors: to filter for specific sectors (if its aid through the multilateral system only)
+
+Not specifying any or all of these parameters will return all the available data.
+
+You can refer to the examples above for DAC1 and DAC2a to understand the usage of these classes.
+**Note**: given the speed and rate-limiting of the dac-explorer APIs, consider using the bulk option
+unless you're looking for something very specific.
+
+
+## Key features
+
+- **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the 
+analysis.
+- **Get data in the currency and prices you need** - ODA data is only available in US dollars (current or constant 
+prices) and local currency units (current prices). The package allows you to view the data in US dollars, Euros,
+British Pounds and Canadian dollars, in both current and constant prices. We can add any other DAC currency if you
+request it via the [issues page](https://github.com/ONEcampaign/oda_data_package/issues)
+
+## Contributing
+Interested in contributing to the package? Please reach out.

oda_data-2.2.0/oda_data.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+oda_data/__init__.py
+oda_data/config.py
+oda_data/logger.py
+oda_data.egg-info/PKG-INFO
+oda_data.egg-info/SOURCES.txt
+oda_data.egg-info/dependency_links.txt
+oda_data.egg-info/requires.txt
+oda_data.egg-info/top_level.txt

oda_data-2.2.0/oda_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oda_data-2.2.0/oda_data.egg-info/requires.txt

@@ -0,0 +1,5 @@
+cachetools>=6.2.0
+pandas[excel,parquet,performance]>=2.3.2
+pydeflate>=2.1.3
+reader>=3.18
+thefuzz>=0.22.1

oda_data-2.2.0/oda_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+oda_data

oda_data-2.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "oda_data"
+version = "2.2.0"
+description = "A python package to work with Official Development Assistance data from the OECD DAC."
+requires-python = ">=3.10"
+
+license = {text = "MIT"}
+readme = "README.md"
+authors = [
+    {name = "Jorge Rivera", email = "jorge.rivera@one.org"},
+    {name = "Miguel Haro Ruiz", email = "miguel.haroruiz@one.org"}
+]
+
+dependencies = [
+    "cachetools>=6.2.0",
+    "pandas[excel,parquet,performance]>=2.3.2",
+    "pydeflate>=2.1.3",
+    "reader>=3.18",
+    "thefuzz>=0.22.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ONEcampaign/oda_data_package"
+Repository = "https://github.com/ONEcampaign/oda_data_package"
+Documentation = "https://github.com/ONEcampaign/oda_data_package"
+
+[tool.setuptools.packages.find]
+include = ["oda_data"]

oda_data-2.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oda_data-2.1.2/oda_data/.raw_data/README.md

@@ -1,3 +0,0 @@
-# Raw Data
-This directory is used to store the raw data, as downloaded from the OECD website, if the user does not provide
-a path when importing the package.

oda_data-2.1.2/oda_data/api/constants.py

@@ -1,167 +0,0 @@
-# Constants
-from typing import Literal
-
-from oda_data.clean_data.schema import ODASchema
-
-MarkerScore = Literal[
-    "significant",
-    "principal",
-    "not_targeted",
-    "not_screened",
-    "total_targeted",
-    "total_allocable",
-]
-
-PolicyMarker = Literal[
-    "gender", "environment", "nutrition", "disability", "biodiversity"
-]
-
-CURRENCIES: dict[str, str] = {
-    "USD": "USA",
-    "EUR": "EUI",
-    "GBP": "GBR",
-    "CAD": "CAN",
-    "LCU": "LCU",
-}
-
-PRICES = {
-    "DAC1": {"column": "amounttype_code"},
-    "DAC2A": {"column": "data_type_code"},
-}
-
-MEASURES: dict[str, dict] = {
-    "DAC1": {
-        "commitment": {
-            "column": "flows_code",
-            "filter": 1150,
-        },
-        "commitment_grant": {
-            "column": "flows_code",
-            "filter": 1151,
-        },
-        "commitment_non_grant": {
-            "column": "flows_code",
-            "filter": 1152,
-        },
-        "grant_equivalent": {
-            "column": "flows_code",
-            "filter": 1160,
-        },
-        "net_disbursement": {
-            "column": "flows_code",
-            "filter": 1140,
-        },
-        "net_disbursement_grant": {
-            "column": "flows_code",
-            "filter": 1121,
-        },
-        "gross_disbursement": {
-            "column": "flows_code",
-            "filter": 1120,
-        },
-        "gross_disbursement_non_grant": {
-            "column": "flows_code",
-            "filter": 1122,
-        },
-        "received": {
-            "column": "flows_code",
-            "filter": 1130,
-        },
-    },
-    "DAC2A": {
-        "net_disbursement": {
-            "column": "flow_type_code",
-            "filter": "D",
-        },
-        "gross_disbursement": {
-            "column": "flow_type_code",
-            "filter": "D",
-        },
-    },
-    "CRS": {
-        "commitment": {"column": "usd_commitment", "filter": None},
-        "grant_equivalent": {"column": "usd_grant_equiv", "filter": None},
-        "gross_disbursement": {"column": "usd_disbursement", "filter": None},
-        "received": {"column": "usd_received", "filter": None},
-        "expert_commitment": {"column": "usd_expert_commitment", "filter": None},
-        "expert_extended": {"column": "usd_expert_extended", "filter": None},
-        "export_credit": {"column": "usd_export_credit", "filter": None},
-    },
-    "Multisystem": {
-        "commitment": {
-            "column": "flow_type",
-            "filter": "Commitments",
-        },
-        "gross_disbursement": {
-            "column": "flow_type",
-            "filter": "Disbursements",
-        },
-    },
-}
-
-Measure = Literal[
-    "commitment",
-    "commitment_grant",
-    "commitment_non_grant",
-    "expert_commitment",
-    "expert_extended",
-    "export_credit",
-    "grant_equivalent",
-    "gross_disbursement",
-    "gross_disbursement_non_grant",
-    "net_disbursement",
-    "net_disbursement_grant",
-    "received",
-]
-
-
-_EXCLUDE = [
-    "amounttype_code",
-    "amount_type",
-    "base_period",
-    "data_type_code",
-    "unit_measure_name",
-    "unit_measure_code",
-]
-
-EXTENDED_PROVIDER_PURPOSE_GROUPER = [
-    ODASchema.PROVIDER_CODE,
-    ODASchema.PROVIDER_NAME,
-    ODASchema.AGENCY_CODE,
-    ODASchema.AGENCY_NAME,
-    ODASchema.RECIPIENT_CODE,
-    ODASchema.FLOW_MODALITY,
-    ODASchema.FINANCE_TYPE,
-    ODASchema.PURPOSE_CODE,
-    ODASchema.YEAR,
-    ODASchema.CURRENCY,
-    ODASchema.PRICES,
-]
-
-PROVIDER_PURPOSE_GROUPER = [
-    ODASchema.PROVIDER_CODE,
-    ODASchema.PROVIDER_NAME,
-    ODASchema.AGENCY_CODE,
-    ODASchema.AGENCY_NAME,
-    ODASchema.PURPOSE_CODE,
-    ODASchema.RECIPIENT_CODE,
-    ODASchema.YEAR,
-    ODASchema.CURRENCY,
-    ODASchema.PRICES,
-]
-
-CHANNEL_PURPOSE_GROUPER = [
-    ODASchema.CHANNEL_CODE,
-    ODASchema.PURPOSE_CODE,
-    ODASchema.RECIPIENT_CODE,
-    ODASchema.YEAR,
-    ODASchema.CURRENCY,
-    ODASchema.PRICES,
-]
-
-CHANNEL_PURPOSE_SHARE_GROUPER = [
-    ODASchema.YEAR,
-    ODASchema.CURRENCY,
-    ODASchema.PRICES,
-    ODASchema.CHANNEL_CODE,
-]