Merge pull request #4 from WFP-VAM/main-test

Renamed package to DataBridgesKnots and uses client 4.0.0 (stable)

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

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
 

data_bridges_utils/__init__.py → 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']

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"

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

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"
 

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 = "[email protected]" }, {name = "Valerio Giuffrida", email = "[email protected]"}]
 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"]

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',