diff --git a/README.md b/README.md index b7be5dc..805868e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ -# Data Bridges Connect +# Data Bridges Knots This Python module allows you to get data from the WFP Data Bridges API, including household survey data, market prices, exchange rates, GORP (Global Operational Response Plan) data, and food security data (IPC equivalent). It is a wrapper for the [Data Bridges API Client](https://github.com/WFP-VAM/DataBridgesAPI), providing an easier way to data analysts to get VAM and monitoring data using their language of choice (Python, R and STATA). ## Installation -> NB This is the dev version of the data_bridges_utils and API client package, it is frequently updated yet not stable. +> NB This is the dev version of the data_bridges_knots and API client package, it is frequently updated yet not stable. -You can install the `data_bridges_utils` package using `pip` and the Git repository URL: +You can install the `data_bridges_knots` package using `pip` and the Git repository URL: ``` -pip install --force-reinstall git+https://github.com/WFP-VAM/DataBridgesConnect.git@dev +pip install git+https://github.com/WFP-VAM/DataBridgesKnots.git ``` ## Configuration @@ -32,75 +32,24 @@ pip install --force-reinstall git+https://github.com/WFP-VAM/DataBridgesConnect. Run the following code to extract household survey data. ```python -from data_bridges_utils import DataBridgesShapes -CONFIG_PATH = "data_bridges_api_config.yaml" +from data_bridges_knots import DataBridgesShapes -client = DataBridgesShapes(CONFIG_PATH) - -# Get household data for survey id -survey_data = client.get_household_survey(survey_id=3329, access_type='full') -print(survey_data.head()) -``` -A sample python file with additional examples for other endpoints is provided in the repo. - -### STATA -1. Make sure you declare where your Python instance is by setting ```python set exec "path/to/python/env"``` -2. Run the following code to extract household survey data and loading it into STATA as a flat dataset with value labels. Make sure to edit your ```stata_path```and ```stata_version``` to match the one installed in your system. - -```stata -python set exect "path/to/python/env" - -python: - -""" -Read a 'base' Household dataset from Data Bridges and load it into STATA. -Only works if user has STATA 18+ installed and added to PATH. -""" - -from data_bridges_utils import DataBridgesShapes, map_value_labels -from data_bridges_utils.load_stata import load_stata -import stata_setup - -# set installation path for STATA -stata_path = r"C:/Program Files/Stata18" -# set stata version -stata_version = "se" +CONFIG_PATH = r"data_bridges_api_config.yaml" -stata_setup.config(stata_path, stata_version) -from sfi import Data, Macro, SFIToolkit, Frame, Datetime as dt +client = DataBridgesShapes(CONFIG_PATH) -# Path to YAML file containing Data Bridges API credentials -CONFIG_PATH = r"data_bridges_api_config.yaml" +#%% XSLForm definition and Household dataset -# Example dataset and questionnaire from 2023 Congo CFSVA CONGO_CFSVA = { 'questionnaire': 1509, 'dataset': 3094 } - -# Initialize DataBridges client with credentials from YAML file -client = DataBridgesShapes(CONFIG_PATH) - -# Get houhold data for survey id -survey_data = client.get_household_survey(survey_id=CONGO_CFSVA["dataset"], access_type='base') # base is the standardized-only dataset +# get household survey data +survey_data = client.get_household_survey(survey_id=CONGO_CFSVA["dataset"], access_type='full') +# get XLSForm data questionnaire = client.get_household_questionnaire(CONGO_CFSVA["questionnaire"]) -# Map the categories to survey_data -mapped_survey_data = map_value_labels(survey_data, questionnaire) - -# Get variable labels -variable_labels = get_column_labels(questionnaire) -# Get value labels -value_labels = get_value_labels(questionnaire) - -# Return flat dataset with value labels -survey_data_with_value_labels = map_value_labels(survey_data, questionnaire) - -# Load into STATA dataframe -ds = load_stata(survey_data_with_value_labels, stata_path, stata_version) - -end ``` ## Contributing diff --git a/ROADMAP.md b/ROADMAP.md index 80f20a9..dc82881 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ This document outlines the planned features and improvements for the `DataBridgesUtils` package, which provides a wrapper for the WFP Data Bridges API. -## Upcoming Release: 1.0.0 (DEV) +## Upcoming Release: 0.1.0 (DEV) ### Wrapper Endpoints diff --git a/data_bridges_utils/__init__.py b/data_bridges_knots/__init__.py similarity index 81% rename from data_bridges_utils/__init__.py rename to data_bridges_knots/__init__.py index 21f08ca..9d0deb0 100644 --- a/data_bridges_utils/__init__.py +++ b/data_bridges_knots/__init__.py @@ -4,7 +4,7 @@ Wrapper for DataBridges client. """ -from .get_data import DataBridgesShapes +from .client import DataBridgesShapes from .labels import get_column_labels, get_value_labels, map_value_labels __all__ = ['DataBridgesShapes', 'labels'] diff --git a/data_bridges_utils/get_data.py b/data_bridges_knots/client.py similarity index 100% rename from data_bridges_utils/get_data.py rename to data_bridges_knots/client.py diff --git a/data_bridges_utils/labels.py b/data_bridges_knots/labels.py similarity index 100% rename from data_bridges_utils/labels.py rename to data_bridges_knots/labels.py diff --git a/data_bridges_utils/load_stata.py b/data_bridges_knots/load_stata.py similarity index 100% rename from data_bridges_utils/load_stata.py rename to data_bridges_knots/load_stata.py diff --git a/examples/example_R.R b/examples/example_R.R index 96b3656..66c3b2a 100644 --- a/examples/example_R.R +++ b/examples/example_R.R @@ -4,12 +4,12 @@ library(dplyr) # Set up Python environment # use_python("/path/to/python/env") -python_path <- "C:/Users/alessandra.gherardel/AppData/Local/miniconda3/envs/data_bridges_utils/python.exe" +python_path <- "C:/Users/alessandra.gherardel/AppData/Local/miniconda3/envs/data_bridges_knots/python.exe" use_python(path.expand(python_path)) # Import DataBridgesShapes class -databridges_utils <- import("data_bridges_utils") -DataBridgesShapes <- databridges_utils$DataBridgesShapes +databridges_knots <- import("data_bridges_knots") +DataBridgesShapes <- databridges_knots$DataBridgesShapes # Initialize DataBridges client with credentials from YAML file CONFIG_PATH <- "data_bridges_api_config.yaml" diff --git a/examples/example_STATA.do b/examples/example_STATA.do index 89bf2bd..7d46ba9 100644 --- a/examples/example_STATA.do +++ b/examples/example_STATA.do @@ -7,9 +7,9 @@ Read a 'full' Household dataset from Data Bridges and load it into STATA. Only works if user has STATA 18+ installed and added to PATH. """ -from data_bridges_utils import DataBridgesShapes -from data_bridges_utils.labels import get_column_labels, get_value_labels, map_value_labels -from data_bridges_utils.load_stata import load_stata +from data_bridges_knots import DataBridgesShapes +from data_bridges_knots.labels import get_column_labels, get_value_labels, map_value_labels +from data_bridges_knots.load_stata import load_stata import numpy as np import stata_setup from sfi import Data, Macro, SFIToolkit, Frame, Datetime as dt diff --git a/examples/example_python.py b/examples/example_python.py index ca988fd..b1f074f 100644 --- a/examples/example_python.py +++ b/examples/example_python.py @@ -1,5 +1,5 @@ """ -Reads Household Data from Data Bridges. The script uses the DataBridgesShapes class from the data_bridges_utils module to interact with the Data Bridges API and retrieve various datasets, including: +Reads Household Data from Data Bridges. The script uses the DataBridgesShapes class from the data_bridges_knots module to interact with the Data Bridges API and retrieve various datasets, including: - Household survey data - GORP (Global Operational Response Plan) data - Exchange rates and prices for Afghanistan @@ -9,8 +9,8 @@ """ #%% -from data_bridges_utils import DataBridgesShapes -from data_bridges_client.load_stata import load_stata +from data_bridges_knots import DataBridgesShapes +from data_bridges_knots.load_stata import load_stata CONFIG_PATH = r"data_bridges_api_config.yaml" diff --git a/pyproject.toml b/pyproject.toml index bbadce2..0bc7a20 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,8 +3,8 @@ requires = ["setuptools>=61.0.0", "wheel"] build-backend = "setuptools.build_meta" [project] -name = "data_bridges_utils" -version = "1.0.0" +name = "data_bridges_knots" +version = "0.1.0" authors = [{ name = "Alessandra Gherardelli", email = "alessandra.gherardelli@wfp.org" }, {name = "Valerio Giuffrida", email = "valerio.giuffrida@wfp.org"}] description = "Wrapper for Data Bridges API client" readme = "README.md" @@ -18,7 +18,7 @@ dependencies = [ 'pandas>=2', 'pystata', 'stata-setup', - 'data-bridges-client @ git+https://github.com/WFP-VAM/DataBridgesAPI.git@hotfix-4.1.0', + 'data-bridges-client @ git+https://github.com/WFP-VAM/DataBridgesAPI.git', ] [project.optional-dependencies] @@ -28,4 +28,4 @@ data-bridges-utils-STATA = ["stata-setup", "pystata"] data-bridges-utils-R = [] [tool.setuptools] -packages = ["data_bridges_utils"] +packages = ["data_bridges_knots"] diff --git a/setup.py b/setup.py index 8d2876e..5bfded6 100644 --- a/setup.py +++ b/setup.py @@ -6,8 +6,8 @@ long_description = f.read() setup( - name='data_bridges_utils', - version='1.0.0', + name='data_bridges_knots', + version='0.1.0', description='Wrapper for Data Bridges API client', long_description=long_description, long_description_content_type='text/markdown',