-
Notifications
You must be signed in to change notification settings - Fork 14
Adding Feature & Event Sources
This page discusses how to add new feature and event datasources to Helioviewer. It's based on the work done to integrate the CCMC Flare Prediction Scoreboard into Helioviewer.
The first step is finding a data source to add. CCMC provides a HAPI for retrieving solar flare prediction data.
Once you have a data source, you need to add an API that parses the data source to conform to the Helioviewer Event Format
You must define pin abbreviations for the types of pins you plan to add. The abbreviation must be unique across all event sources.
@dgarciabriseno designed this format as a machine readable way passing generic event data to the Helioviewer web app. Any data that conforms to this specification will "drop-in" easily into the front end's features & events section.
Once you've added the API that returns results in the Helioviewer Event Format you must add a line to _loadStartingLayers to include a call to your new API. This is the only addition that needs to be made to the front end.
You must also add a new pin which has the file name of "2 letter abbreviation".png and "2 letter abbreviation"@2x.png. This must be added here on the helioviewer.org repository and here on the API side. They're required on the front end obviously for the pins. And on the API side for creating screenshots and videos.
For the new feature to show up in screenshots, you must add an internal call to the function that returns data in the Helioviewer Event Format here. Look for a function call to GetLatestNormalizedFlarePredictions to see how it is done for the flare predictions. This is the only addition needed to support screenshots and movies.
This is the difficult section since it hasn't been updated to conform to the Helioviewer Event Format due to the complicated nature of how the timeline is built... Instead it still mostly conforms to the HEK format. TODO: There is an open task here to make this conform to the Helioviewer Event Format, this involves significant front end and back end refactoring.
The image timeline data APIs have 2 possible return types.
- Event specific data
- Buckets of event counts
Type #1 is used when the user is zoomed in on the event timeline. In this case, the back end chooses a resolution between "m", "5m", and "15m". For all intents and purposes, these values have the same meaning, and event specific data should be returned.
Type #2 is used when the user is zoomed out enough that the back end decides the resolution should be "30m", "h", "D", "M", or "Y". These correspond to 30 minute blocks, hour blocks, day blocks, month blocks, and year blocks. In this case, the values returned should be an array of lists in the form [unix_timestamp in milleseconds, # of events in this bucket]
This should ideally be the same color as your pin. You only need to add your 2 letter abbreviation to this constant Statistics.php:EVENT_COLORS along with the hex color. This color will be used in the image timeline to represent this feature.
You will also need to add your abbreviation to Statistics.php:EVENT_KEYS in the same place you added the color. See Adding Color above.
Event specific data is a list of data objects where each object has the following fields:
[
x: unix timestamp in milliseconds of the event's start time,
x2: unix timestamp in milliseconds of the event's end time,
y: index of this item in the array,
kb_archivid: unique id for this event,
hv_labels_formatted: array of key value pairs which make up a human readable label,
event_type: Event type abbreviation,
frm_name: Name for the event,
frm_specificid: Version of the recognition method, or empty string,
event_peaktime: Peak time or null (as string in format Y-m-d H:i:s)
event_starttime: Start time of the event,
event_endtime: End time of the event.
concept: The overall type of event that this is,
modifier: 0
]
You must query your data source for the given time range and transform them to this format.
If the resolution is wide enough to use buckets, then you must query your data and count how many fall into certain windows depending on the given resolution. For "30m" then you must return how many events are between T - T+30m, T+30m - T+60m, T+60m - T+90m, etc. The same goes for h, D, M, and Y. Once you have these counts for your events between the given start and end times, you must return them in the following format:
[
[unix timestamp in milliseconds, count],
[unix timestamp in milliseconds + delta time, count],
[unix timestamp in milliseconds + delta time * 2, count],
etc.
]
Here's a real example of what this may look like:
[
1680588000000, # 2023-04-04 06:00:00
8
],
[
1680589800000, # 2023-04-04 06:30:00
0
],
[
1680591600000, # 2023-04-04 07:00:00
14
],
[
1680593400000, # 2023-04-04 07:30:00
0
],
Once you have a function that can return these two types of objects, hook it into Helioviewer by adding a call to your function here The function GetDataCoverageForEvent will call your function to get data for your specific event type, and it will merge it into the final result that will be used in the image timeline. It passes the resolution (m, 5m, 15m, h, D, M, Y), start time, end time, current observation time (currently unused) and the specific subgroups of events that you must query for.
Once your function successfully returns both the data objects or bucket list, then the results will be inserted into the image timeline.