Define Use Cases that end-user API to query data should support

[dlebauer]

• define use cases (@dlebauer)
• what features should an API have?
  • query by genotype? query by location? time? sensor type? individual plants (entities in BETYdb).
  • what features will make it easy to document and integrate with other API's?
  • What is the value of an API Framework such as Swagger?
• what framework does the current BETYdb API use? What features does it have? What would make it easier to use / extend?

Use cases

def: a few sentences that describe a task someone wants to accomplish.
will help prioritize feature development and project organization, and get feedback.

ex1: someone is looking at an image in Clowder, have identified a particular trait, and want to find all plants with this trait (within some range or greater than, e.g. top 10% biomass) and the find other data assoc. w/ these plants

ex2: I have an interesting thing I’ve noticed, can I find all plants w/ same feature +/- X%

ex3: Want to upload data so someone else can get to it and its metadata

ex4: want to publish a collection from Clowder

references

• BETYdb API documentation
• Zapier Intro to API design
• Wickham API design best practices

[max-zilla]

Here are some examples, Not all of these will be valid but perhaps it will engender discussion... these examples might be scattershot across the various components.

Inherent to all of these use cases: "is this realistic? do we need to support this? does this capability already exist, through the stated path or through a different path?"

End-users working with existing data in Clowder

1. Browse a gallery of daily images of the same plant across 2 weeks.
2. Search for images by metadata fields (e.g. one particular sensor with a value exceeding some threshold), and download the results
3. Search for images with ranges/fuzzy-matching (e.g. all images of plant with height +-X cm or X% of nominal value)
4. Read about the specification of the sensors that gathered these data to understand what the value represents.

end-users with a bit more ambition...
5. Show a histogram of some metadata field/trait values for all images in a Dataset (this one is getting out there...)
6. Search for all images with some value outside 2 standard deviations of the average value for that day and field
7. Load a selection of images from one of the use cases above into an analysis VM with PlantCV, etc available for study.
8. Export some tabular structuring of selected metadata fields from a batch of images, e.g. a CSV with identifier, trait1, trait2, trait3, date

developer-oriented
9. augment the Clowder image extractor to ingest a new data format that is proprietary/internal
10. write SQL queries against BETYdb directly to bulk-upload data into e.g. the Traits table
11. Stand up new instance of BETYdb for my own use

[dlebauer]

1. Find all plots where [accession X] was planted
   1. Find all points and dates where seeds of [accession X] were planted
   2. find bounding boxes associated with these plots
   3. use bounding boxes to query data from [sensor X](e.g. raster image) from [date range](in Clowder)
2. find all trait values (in BETYdb traits table, summarized to plant or plot level) associated with [accession X] collected using [method X]
3. after sensor data have been processed geospatially orthorectified and aligned with overlap and artifacts removed, use bounding boxes to clip / select data from some set of sensors
4. return experimental design 'plot plan' from PostGIS database (BETYdb)
5. return information about accessions from BETYdb cultivars table and also in BMS,
6. return information about lineage, seed packets, experimental design from BMS,
7. Load field measurements collected in FieldBook APP into BMS
8. Import traits from BMS to BETYdb and vice-versa
   The reason we are using both BETYdb and BMS despite substantial overlap is that BETYdb has better support for geospatial data, numeric traits, and large external raster files; BMS does a better job at tracking experimental design, lineage, genomics, and can (apparently now or in the near future) import directly from the FieldBook app.

[dlebauer]

@max-zilla assigning to you since you are working on the cross-database search