Install
Virtual environment creation
Before installing the package first create a virtual environment to keep the package and dependencies only in the project to be used, to create the virtual environment in the terminal within the project run the following command
py -m venv [virtual_environment_name]
Then the virtual environment is started
[virtual_environment_name]\Scripts\activate.bat
Now you can continue with the installation of the package.
Installation from GitHub
pip install git+https://github.com/CIAT-DAPA/aclimatepyapi@v0.2.0
After install the package you need to set some environmente varibles to use the geoserver, first set the geoserver username
In Windows:
set "GEOSERVER_USER=[your_username]"
In Mac or Linux:
export GEOSERVER_USER="[your_username]"
Now set the geoserver password
In Windows:
set "GEOSERVER_PASSWORD=[your_password]"
In Mac or Linux:
export GEOSERVER_PASSWORD="[your_password]"
Remove
The easiest way to remove the package is:
pip uninstall aclimate-api
How to use
The following list are recommendations which should be take into account when you try to use the package.
Import library
Once you have installed the library, you should import it in order to get access to all functions
library("aclimaterapi")
from aclimate_api.[module_name] import [module_name]
Url of the Web API and Geoserver
The first thing that you have to identify is the url which is located the Web APIAPI and the geoserver link. This parameter will be asked in all methods.
You can create a global variable with thisthese url:
url_root = "https://webapi.aclimate.org/api/"
URL_API = "https://webapi.aclimate.org/api/" URL_GEOSERVER = "https://geo.aclimate.org/geoserver/"
Functions
Get countries
The method get_geographic_country allows to users get a list of all countries.
df = get_geographic_country(url_root) print(head(df))
Get weather stations
The method get_geographic allows to users get a list of all weather stations available in the system.
df = get_geographic(url_root) print(head(df))
Get weather stations with crop information
The method get_geographic allows to users get a list of the states of the selected country with each of their municipalities and meteorological stations and for each meteorological station their productive ranges for each crop.
country_id = "61e59d829d5d2486e18d2ea8" df = get_geographic_crop(url_root, country_id) print(head(df))
Get weather stations information
The method get_geographic allows to users get a list of detailed information weather stations, and crop-related details for a selected country.
country_id = "61e59d829d5d2486e18d2ea8" ws_list = get_geographic_ws(url_root, country) print(head(ws_list))
Agronomy module
To use this module you need to import the module and create the object
from aclimate_api.agronomy import Agronomy agronomy = Agronomy(URL_API)
Get agronomy setup
The method get_agronomy allows to users get a list of cultivars and soils available into the AClimate platform.
df = agronomy.get_agronomy()df = get_agronomy(url_root)print(df)
Forecast module
To use this module you need to import the module and create the object
from aclimate_api.forecast import Forecast forecast = Forecast(URL_API)
Get climate forecast
The method get_forecast_climate, function which gets the forecast climate for a set of weather stations available into the AClimate platform.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] obj_f = forecast.get_forecast_climate(stations) print(obj_f['probabilities']) print(obj_f['performance']) print(obj_f['scenarios'])stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3")obj_f = get_forecast_climate(url_root, stations)print(obj_f$probabilities)print(obj_f$performance)print(obj_f$scenarios)
Get crop forecast
The method get_forecast_crop, function which gets the crop forecast for a set of weather stations available into the AClimate platform.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = forecast.get_forecast_crop(stations) print(df)stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3")df = get_forecast_crop(url_root, stations)print(head(df))
Get forecast id
The method get_forecast_information, function which gets access primary forecast data for each month within a desired year.
year = 2023 forecasts = forecast.get_forecast_information(year)year= 2023forecasts = get_forecast_information(url_root, year)print(forecasts)
Get subseasonal forecast
The method get_forecast_subseasonal, function which gets information from the subseasonal forecast process, including probabilities and climatic scenarios.
You can find the ids of the weather stations in the method get_geographic
stations = ["63a3744005732d2a14260392","63a374ce05732d2a14260499"] subseasonal_data = forecast.get_forecast_subseasonal(stations)stations = c("63a3744005732d2a14260392","63a374ce05732d2a14260499")subseasonal_data = get_forecast_subseasonal(url_root, stations)print(subseasonal_data)
Get previous climate forecast
The method get_forecast_climate_previous, function which gets the information obtained through the forecast process that is desired by means of the Id, the seasonal and subseasonal probabilities and the climatic scenarios.
You can find the ids of the weather stations in the method get_geographic You can find the forecast id in the method get_forecast_information
forecast_id = "657006544afb9646da8c6b78" stations= ["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] obj_fp = forecast.get_forecast_climate_previous(forecast_id, stations) print(obj_fp['probabilities']) print(obj_fp['performance']) print(obj_fp['scenarios'])forecast = "657006544afb9646da8c6b78"stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3")obj_fp = get_forecast_climate_previous(url_root, forecast, stations)print(obj_fp)
Get previous crop forecast
The method get_forecast_crop_previous, function which gets the crop forecast information for a specific forecast indicated in the parameters.
You can find the ids of the weather stations in the method get_geographic You can find the forecast id in the method get_forecast_information
forecast_id = "657006544afb9646da8c6b78" stations= ["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = forecast.get_forecast_crop_previous(forecast_id, stations) print(df)forecast = "657006544afb9646da8c6b78"stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3")df = get_forecast_crop_previous(url_root, forecast, stations)print(head(df))
Get forecast crop exceedance
The method get_forecast_crop_exc, function which gets the information obtained through of all forecast in the crop model process, yield data.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = forecast.get_forecast_crop_exc(stations) print(df)stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3")df = get_forecast_crop_exc(url_root, stations)print(head(df))
Get historical climatology
The method get_historical_climatology, function which gets the climatology of a selected weather station.
Geographic Module
To use this module you need to import the module and create the object
from aclimate_api.geographic import Geographic geographic = Geographic(URL_API)
Get countries
The method get_geographic_country allows to users get a list of all countries.
df = geographic.get_geographic_country() print(df)
Get weather stations
The method get_geographic allows to users get a list of all weather stations available in a country.
You can find the ids of the weather stationscountries in the method get_geographicget_geographic_country
stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3") df = get_historical_climatology(url_root, stations) print(df)
id_country = "636c0813e57f2e6ac61394e6" df = geographic.get_geographic(id_country) print(df)
Get historical climateweather stations with crop information
The method get_historical_historicalclimatic, function which gets the weather history of a selected weather station.
You can find the ids of the weather stations in the method get_geographic
stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3") df = get_historical_historicalclimatic(url_root, stations) print(df)
Get years with historical crop performance data
The method get_historical_historicalyieldyears, function which gets the years that contain historical crop performance data of the selected weather station.
You can find the ids of the weather stations in the method get_geographic
stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3") df = get_historical_historicalyieldyears(url_root, stations) print(df)
Get historical crop performance
The method get_historical_historicalyield, function which gets the yield data obtained through the crop model process.
You can find the ids of the weather stations in the method get_geographic
stations=c("58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3") years=c("2022","2023") df = get_historical_historicalyield(url_root, stations, years) print(head(df))
The method get_geographic allows to users get a list of the states of the selected country with each of their municipalities and meteorological stations and for each meteorological station their productive ranges for each crop.
country_id = "61e59d829d5d2486e18d2ea8" df = geographic.get_geographic_crop(country_id) print(df)
Get weather stations information
The method get_geographic allows to users get a list of detailed information weather stations, and crop-related details for a selected country.
country_id = "61e59d829d5d2486e18d2ea8" ws_list = geographic.get_geographic_ws(country_id) print(ws_list)
Get gGeoserver workspaceModule
To use this module you need to import the module and create the object
from aclimate_api.geoserver import Geoserver geoserver = Geoserver(URL_GEOSERVER)
Get geoserver workspace
The method get_geo_workspaces, function which gets all the workspaces of the GeoServer.
obj_f = geoserver.get_geo_workspaces()obj_f = get_geo_workspaces(url_root)print(obj_f)
Get geoserver mosaic stores
The method get_geo_mosaic_name, function which gets all the mosaic stores of a specific workspace.
You can find the workspace in the method get_geo_workspaces
workspace = "climate_indices_pe" obj_f = geoserver.get_geo_mosaic_name(workspace)obj_f = get_geo_mosaic_name(url_root, workspace)print(obj_f)
Get geoserver mosaics
The method get_geo_mosaics, function which gets the desired mosaic from the GeoServer.
You can find the workspace in the method get_geo_workspaces You can find the mosaic_name in the method get_geo_mosaic_name
workspace = "climate_indices_pe" mosaic_name = "freq_rh80_t_20_25" year = 2014 month = 5 day = 1 raster = geoserver.get_geo_mosaics(workspace, mosaic_name, year, month, day)raster = get_geo_mosaics(url_root, workspace, mosaic_name, year, month, day)print(raster)
Get geoserver polygon stores
The method get_geo_polygon_name, function which gets all the polygon stores of a specific workspace.
You can find the workspace in the method get_geo_workspaces
workspace = "administrative" obj_f = geoserver.get_geo_polygon_name(workspace)obj_f = get_geo_polygon_name(url_root, workspace)print(obj_f)
Get geoserver shapefiles
The method get_geo_polygons, function which gets the desired shapefile from the GeoServer.
You can find the workspace in the method get_geo_workspaces You can find the polygon_name in the method get_geo_polygon_name
workspace = "administrative" polygon_name = "ao_adm1" shapefile = get_geo_polygons(workspace, polygon_name)shapefile = get_geo_polygons(url_root, workspace, polygon_name)print(shapefile)
Developer
Configure dev environment
To set up your development environment, start by installing the necessary packages in R. You can do this by running the following commands:
install.packages("devtools") install.packages("roxygen2") install.packages("httr") install.packages("rjson") install.packages("raster") install.packages("sf")
These commands install the devtools and roxygen2 libraries, which are essential for package development.
Build package
Once you've installed the required libraries, import them into your R session by running the following commands:
library(devtools) library(roxygen2) library(httr) library(rjson) library(raster) library(sf)
After importing the libraries, set your working directory to the location of the package source code:
setwd("/path/source_code/")
Replace "/path/source_code/" with the actual location of your package's source code.
Proceed to build the package documentation by running the following command:
devtools::document()
This command generates the documentation associated with the package.
Finally, to build the package, execute the following command:
devtools::build()
This last step compiles the package, creating a compressed file containing everything needed for distribution.
Note
The final section involving devtools is optional and intended for local package creation. If you wish to contribute, follow the steps outlined in the next section, "Repository Management." By submitting a pull request to the "stage" branch, the documentation will be automatically updated, and a new release will be created.
Historical Module
To use this module you need to import the module and create the object
from aclimate_api.historical import Historical historical = Historical(URL_API)
Get historical climatology
The method get_historical_climatology, function which gets the climatology of a selected weather station.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = historical.get_historical_climatology(stations) print(df)
Get historical climate information
The method get_historical_historicalclimatic, function which gets the weather history of a selected weather station.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = historical.get_historical_historicalclimatic(stations) print(df)
Get years with historical crop performance data
The method get_historical_historicalyieldyears, function which gets the years that contain historical crop performance data of the selected weather station.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] df = historical.get_historical_historicalyieldyears(stations) print(df)
Get historical crop performance
The method get_historical_historicalyield, function which gets the yield data obtained through the crop model process.
You can find the ids of the weather stations in the method get_geographic
stations=["58504f1a006cb93ed40eebe2","58504f1a006cb93ed40eebe3"] years=["2022","2023"] df = historical.get_historical_historicalyield(stations, years) print(df)
Repository management:
3 main branches are managed.
-
master:main: No changes should be made directly, since it is updated when pulling or pushing to the stage branch -
stage: The changes tested and ready to be sent to production must be sent to this branch, for their subsequent process of automatic tests, merge into master and creation of the release.
-
develop: Branch where the development version of the project will be managed, normally changes will be sent to stage from this branch.
Release:
The release will be created automatically if changes are sent to stage, either by means of a pull request or a push.
The release consists of versioning, which consists of the following format
Release 0.0.0