analysis-ready data tutorial

[jreiberkyle]

Create a tutorial that shows how Planet APIs can simplify production of analysis-ready data (ARD) for two real-world use cases. The tutorial will focus on teaching a workflow that starts with making a Data API search and covers building an Orders API request that includes a Toolchain of Tool operations. This tutorial is targeted to users who have little to no geospatial processing experience - the tutorial will show an API-savvy user how to use Planet's platform to do the "geospatial heavy lifting" as long as they understand how to put the right tools together to extract a meaningful result. The learning objective of this tutorial is to teach the distinction between Data and Orders APIs and ability to understand, create & interpret payloads for all of the above based on "real-world" requirements.

The use cases to address are:

• As a software engineer I want to learn the best practices for searching and ordering ARD through the data and orders apis.
• As a software engineer at an ag-tech company, I'd like to be able to order Planet imagery programmatically in a way that enables the data scientist at my organization to create time-series algorithms (e.g. monitoring ndvi curves over time) without further data cleaning and processing.

General tutorial outline:

1. Begin with a Data API search: define an AOI, set a cloud filter and usable pixels filter as described in the user stories here. As this is just simple search parameters, the real utility of the tutorial here is going to be explaining what those filters do & how (i.e., usable pixels is based on a UDM2 mask)
2. Extract resulting item_ids here, and show the relationship between Data API (searching) and Orders API (operations)
3. Walk the user through selecting the appropriate Product Bundle (see product-bundles-reference ) for their ARD-workflow needs. In this case, we want to use SR imagery. Include a link to relevant docs explaining what SR is/why SR saves time here
4. Walk the user through choosing appropriate Tools (see tools-reference ) and constructing a Toolchain for their order:
   • clip imagery to AOI: again, a light-touch explanation of what & why is good here. Imagine user asking why we need to "clip" if we already searched using an AOI in Data API, etc.

[jreiberkyle]

Changelog:

• remove harmonization as we are only using planetscope imagery
• add an introduction and best practices run through of data/orders api usage
• remove second use case (because it is functionally similar to the first one)
• add a new use case to address a significant ag need: As an agriculture customer, I'd like to create an imagery pipeline that provides for trialing different fungicides by ordering Planet imagery within a single field (AOI), cutting the imagery into multiple field blocks (grid within AOI), and comparing values across blocks in two ways. First, comparison is performed by extracting median, mean, variance NDVI values for each day (using random point sampling) in each block. Second, comparison is performed by random point selection in each block.
  • this use case should use tiling
• remove third use case, as tiling is only possible on one image and therefore isn't well suited to a time stack of imagery