Open hudson-newey opened 1 year ago
OK, a couple of notes:
In lieu of a generalized model of endpoint aggregation, each reports will probably have it's own endpoint.
This means you need to include the full payload you want me to represent in this report.
Also: the false colour image generation will be handles by a different means.
This means you need to include the full payload you want me to represent in this report.
I'll be updating the ticket with the full payload, routes, and request structure needed for the "Ecoacoustic event summary report"
I've attached the full request including filter parameters the client will be sending and the expected response in the drop downs below
POST /reports/event_summary/filter
Additionally, there will be a new provenance route for recognisers / event creators most likely under
GET /provenance/:id
//! GET /provenance/:id
//? response
{
"id": 123,
"name": "BirdNet",
"version": "1.0.0",
"description": "An avian event detector",
"score": 0.5, //* stretch goal
"score_minimum": 0.1,
"score_maximum": 0.8
}
In the request spec above, there is no field for binSize
. How will we send bin size in the requests?
My assumption is it will be one of the following:
{
"binSize": 23123124
}
{
"binSize": "season"
}
great question, currently undecided.
If we can imagine an argument for variable sized bins then maybe seconds as an number.
Probably will go with an enum - mainly because time intervals (months) can be irregularly sized
Since time series is now in scope for the acoustic event report, the response should include a document for recording coverage and analysis coverage
After discussion, I've done a mock-up of what the data structure will be client side (image bellow)
The ITimeSeriesGraph
will probably be implemented additional document under graphs.coverageData
You've mentioned that false colour spectrograms will be handled by different means
Also: the false colour image generation will be handles by a different means.
I'm assuming that spectrograms will be fetched through either: a. A new endpoint in which we can provide a date range, and get a list of spectrogram URL's returned or b. Fetch the spectrograms will be an analysis result item, so we should just request the analysis results, and perform a filter-map client side to extract and collate the spectrograms
You've mentioned that false colour spectrograms will be handled by different means
Also: the false colour image generation will be handles by a different means.
I'm assuming that spectrograms will be fetched through either: a. A new endpoint in which we can provide a date range, and get a list of spectrogram URL's returned or b. Fetch the spectrograms will be an analysis result item, so we should just request the analysis results, and perform a filter-map client side to extract and collate the spectrograms
https://github.com/QutEcoacoustics/baw-client/blob/master/src/app/visualize/visualize.js
id :bigint not null, primary key
name :string
version :string # (this is a string because we want to support version numbers like "1.0.0-beta0.1")
description: :string
score :integer
GET /provenance/:id
(show)
Request body:
This field is intentionally left blank
Response body:
{
"meta": {
"status": 200,
"message": "OK",
},
"data": model in JSON format
}
Example model for show request: Client mock response
{
id: 1,
name: "Fake Audio Event Provenance",
version: "1.0",
description: "Mock Description",
score: 0.5
}
Standard API implementation of routes
GET /provenance
(list)
GET /provenance/filter
(filter)
POST /provenance
(create)
PATCH /provenance/:id
(update)
DELETE /provenance/:id
(delete)
id :bigint not null, primary key # the id field isn't used at the moment, however, it will be used when we add the ability to save reports
name :string
generated_date :datetime not null
statistics :statistics_sub_model
event_groups :event_group_sub_model[]
site_ids :bigint[]
region_ids :bigint[]
tag_ids :bigint[]
provenance_ids :bigint[]
graphs :graphs_sub_model
statistics_sub_model Client side sub-model for report statistics
total_search_span :integer
audio_coverage_over_span :integer
analysis_coverage_over_span :integer
count_of_recordings_analyzed :integer
coverage_start_day :datetime # the date and time of the first audio recording
coverage_end_day :datetime # the date and time of the last audio recording
event_group_sub_model Client side sub-model for report event group
provenance_id :bigint
tag_id :bigint
detections :integer
buckets_with_detections :integer
score :integer
graphs_sub_model Client side sub-model for report graphs
accumulation_data :accumulation_data_sub_model[]
species_composition_data :composition_data_sub_model[]
analysis_coverage_data :analysis_coverage_sub_model[]
coverage_data :coverage_sub_model
accumulation_data_sub_model
date :datetime
count :integer
error :integer
composition_data_sub_model
date :datetime
tag_id :bigint
analysis_coverage_sub_model
date :datetime
audio_coverage :integer
analysis_coverage :integer
coverage_sub_model
failed_analysis_coverage :daterange # new data type (see below)
analysis_coverage :daterange
missing_analysis_coverage :daterange
recording_coverage :daterange
New data type "daterange"
daterange
startDate :datetime
endDate :datetime
POST /reports/audio_event_summary/filter
(filter show)
Example Request Body:
Collapsed due to large content
Client code that creates these filters
Example Response Body:
{
"meta": {
"status": 200,
"message": "OK",
},
"data": event summary report model in JSON format
}
Example model for filter show request Client mock response
Collapsed due to large content
New! Filter Show Allows you to create a single model based on filter conditions sent in the body of a POST request.
Client side tests for this new API endpoint
These routes can be added when we add the ability to cache/save reports
GET /reports/audio_event_summary/:id
(show)
GET /reports/audio_event_summary
(list)
GET /reports/audio_event_summary/filter
(filter)
POST /reports/audio_event_summary
(create)
PATCH /reports/audio_event_summary/:id
(update)
DELETE /reports/audio_event_summary/:id
(delete)
Let me know if you have any questions about the finalized spec
As part of the audio event summary reports, the client needs information to create the accumulation Data plot, species composition plot, analysis coverage plots, and false colour spectrograms.
False colour spectrograms should be returned as a url location or a collection of url locations. A collection is an option because false colour spectrograms can only be created for 24 hour periods, and therefore, should return a collection or sorted url to false colour spectrograms
We should either
/{project,region,site}/:id/audio_events/graphs
and have filter conditions)It is also up for consideration to generate the species
accumulationData
andspeciesCompositionData
client side. However, this may be poor practice and slow down the client