Package: awherepy
aWherePyaWherePy provides a Python solution to work with theaWhere API.Why aWherePy?Prior to aWherePy, aWhere's agronomic and weather data API was only accessible with R. aWherePy creates a Python solution for the aWhere API and provides Python code to:Call the aWhere API;Extract data from the aWhere API returns;Clean and georeference extracted data;Track crops and agricultural data over time;Create an aWhere-sized (9 km x 9 km) grid from a shapefile; and,Rasterize existing remote sensing and GIS data to the aWhere grid.aWherePy allows for the creation of reproducible science workflows with Python scripts and/or Jupyter Notebooks and creates the vehicle to integrate aWhere data with other geospatial and remote sensing data within these platforms.aWherePy contains seven modules:agronomics;crops;fields;grids;models:plantings; and,weather.aWherePyweatherandagronomicsmodules provide the functionality to get historical norms, observed values, and forecast values for weather and agriculture metrics that are formatted, georeferenced, and ready for data analysis and visualization.aWherePygridsmodule provides functionality to rasterize data to the aWhere grid (9x9 km cells). This allows you to integrate other geospatial and remote sensing data (e.g. world population data, normalized difference vegetation index data) with aWhere API data to create advanced analytical insights.aWherePyfields,crops,plantings, andmodelsmodules provide access to advanced agricultural models that track crop data over time and produce information that allows you to make real-time agricultural decisions and adjustments.aWherePy Package StructureaWherePy reflects the currently capabilities of the aWhere API. This section outlines the structure of the aWherePy package, as it relates to the seven package modules.awherepy/Contains Python scripts for the aWherePy modules (e.g.agronomics.py). Also contains two sub-folders, one with example data and one with module test scripts.awherepy/example-dataContains datasets used in the aWherePy tests and vignette gallery examples.awherepy/testsContains Python scripts for the aWherePy tests (e.g.test_agronomics.py).docs/Contains files used to organize and populate the aWherePy documentation.examples/Contains Python scripts used to in the aWherePy vignette gallery (e.g.work_with_agronomics.py).View Example aWherePy ApplicationsYou can view aWherePy applications in thevignette gallery, which demonstrates functionality for all seven aWherePy modules.In addition, the aWherePy package containsPython scriptsto run the example applications for each module as well as theexample dataused within the Python scripts.Install aWherePyInstalling aWherePy 0.1.0 directly from GitHub with pip will fail due to incompatibilities with pip and thertreepackage (specificallyrtree>=0.9.0), which is required for aWherePy functionality.The recommended method to install aWherePy 0.1.0 for local testing and evaluation is to fork or clone the repository, install Conda, create a Conda environment with the necessary packages, and run the complete test suite.Fork or Clone aWherePyOnce you have forked aWherePy or copied the aWherePy clone link, you can run the following terminal command within a local directory to initialize the repository.If fork:$gitclonehttps://github.com/YOUR-USERNAME/awherepy.gitIf clone:$gitclonehttps://github.com/calekochenour/awherepy.gitInstall CondaYou must install Conda -Miniconda(recommended) orAnaconda- in order to create a Conda environment that will run the complete aWherePy test suite.Create aWherePy Development Conda EnvironmentThe root directory of aWherePy contains theenvironment-dev.ymlfile, which when used to create a Conda environment, provides all packages (functionality and testing) to run the complete aWherePy test suite.From the terminal, you can create the development Conda environment.Create environment:$condaenvcreate-fenvironment-dev.ymlActivate Conda Environment and Run aWherePy Test SuiteOnce the aWherePy development environment is created, you can activate it and run the complete test suite.Activate environment:$condaactivateawherepy-devRun test suite:$pytestNote: Before runningpytest, make sure that you are in the root aWherePy folder.Use aWherePy within TerminalOnce installed with a fork or clone, you can also use aWherePy for reasons other than testing. For example, you can import aWherePy into Python:>>>importawherepyasawYou can also import the individual modules into Python:>>>importawherepy.agronomicsasawa>>>importawherepy.cropsasawc>>>importawherepy.fieldsasawf>>>importawherepy.gridasawg>>>importawherepy.modelsasawm>>>importawherepy.plantingsasawp>>>importawherepy.weatherasawwaWhere API AuthenticationIn order to work with aWherePy, you must possess a valid API key and API secret (associated an activeaWhere account). All modules (with the exception of grids) requires the API key and API secret to authenticate prior to making any API requests. Otherwise, the functions within the modules will raise errors indicating invalid credentials.The credentials used in all examples, tests, and documentation are stored and shown as environment variables in the following way:>>># Define aWhere API key and secret>>>awhere_api_key=os.environ.get("AWHERE_API_KEY")>>>awhere_api_secret=os.environ.get("AWHERE_API_SECRET")For both aWherePy continuous integration builds (Travis CI,AppVeyor), the API key and secret are stored as secure environment variables, which allows the full suite of tests to run and the code coverage to be updated upon completion of the build.The aWhere API credentials are not transferable and will not be downloaded when you install, fork, or clone aWherePy. Because of this, all tests (with the exception of the grids module) will fail when run locally, unless you have a valid aWhere API key and API secret. Note that credentials can be stored in different ways locally (e.g. environment variables, text file, other means), but tests may have to be altered to fit a method other than environment variables, as shown in the examples, tests, and documentation.Example UsageThis example shows how to get weather data for a single aWhere grid cell near Rocky Mountain National Park (RMNP), Colorado, using the aWherePy grids and weather modules.>>># Imports>>>importos>>>importawherepy.gridsasawg>>>importawherepy.weatherasaww>>># Define aWhere API key and secret>>>awhere_api_key=os.environ.get('AWHERE_API_KEY')>>>awhere_api_secret=os.environ.get('AWHERE_API_SECRET')>>># Define path to RMNP boundary>>>rmnp_bound_path=os.path.join(..."..","awherepy","example-data","colorado_rmnp_boundary.shp"...)>>># Create aWhere grid and EPSG 4326 boundary for RMNP>>>rmnp_grid,rmnp_bound_4326=awg.create_grid(rmnp_bound_path,...buffer_distance=0.12...)>>># Extract RMNP grid centroids to list>>>rmnp_grid_centroids=awg.extract_centroids(rmnp_grid)>>># Get first centroid>>>analysis_centroid=rmnp_grid_centroids[0]>>># Define RMNP norms kwargs>>>rmnp_weather_norms_kwargs={..."location":(analysis_centroid[0],analysis_centroid[1]),..."start_date":"05-04",..."end_date":"05-13",...}>>># Get RMNP weather norms, 05-04 to 05-13>>>rmnp_weather_norms=aww.get_weather_norms(...awhere_api_key,awhere_api_secret,kwargs=rmnp_weather_norms_kwargs...)>>># Get precipitation average from weather norms data>>>rmnp_precip_norms=rmnp_weather_norms[["precip_avg_mm"]]>>># Define RMNP observed weather kwargs>>>rmnp_weather_observed_kwargs={..."location":(analysis_centroid[0],analysis_centroid[1]),..."start_date":"2014-05-04",..."end_date":"2014-05-13",...}>>># Get observed weather>>>rmnp_weather_observed=aww.get_weather_observed(...awhere_api_key,awhere_api_secret,kwargs=rmnp_weather_observed_kwargs...)>>># Get precipitation amount from observed weather data>>>rmnp_precip_observed=rmnp_weather_observed[["precip_amount_mm"]]aWherePy DocumentationFor information about how to use aWherePy modules and functions, see example applications, and view all other aWherePy documentation-related material, review theaWherePy documentation.Related PackagesThere are no existing Python packages that provide similar functionality for the aWhere API, which is the primary reason aWherePy was created. aWherePy is based on theaWhere R Library, which is an R package created by aWhere for use with the aWhere API.Active MaintainersContributions to aWherePy are welcome. Below are the current active package maintainers. Please see thecontributors pagefor a complete list of all of maintainers.How to ContributeContributions to aWherePy are welcome. Please see thecontributing guidelinesfor more information about submitting pull requests or changes to aWherePy.LicenseBSD-3