Update explain behavior to support the visualizer flyout function.

[jawache]

The vizualizer fly out needs to be able to show inputs and outputs properly, e.g. in this example I'm hovering over a pipeline and two outputs are highlighted. One is an input and one is an output, the current underlying data in the manifest file doesn't show inputs/outputs (yes, I know I asked for it in this way, I was wrong!) so we need to add them back in.

Can we also call the field in the manifest, "key" or something other than "explain", I feel explain should do more than just describe the fields.

Details for Narek

We basically want to revert the changes in this PR
#971

So instead of returning

param-name
  plugins: //what plugins use this param?
  unit: 
  description:
  aggregation-method:

we should instead return:

plugin-name:
  inputs:
    param-1:
      description:
      unit: 
      aggregation-method:

So the parameter details are organized by plugin, then inputs/outputs. The aggregation method should still be returned. It is understood that this will lead to repetition of the parameters in the explain block if theyare used in multiple plugins. This is fine, as long as the aggregation method and unit are the same for identically named parameters.

Example

Here's a snippet of the explain block from a manifest I just ran:

explain:
  data-transferred:
    plugins:
      - network-energy-to-transfer-call-data
    unit: GB
    description: >-
      Data transferred over network, in GB. Estimated from values here
      https://tactiq.io/learn/zoom-data-usage-facts.
    aggregation-method:
      time: sum
      component: sum
  kwh-per-gb-network:
    plugins:
      - network-energy-to-transfer-call-data
    unit: kWh/GB
    description: >-
      Coefficient relating energy expendidture to 1GB of data transferred over
      network. Taken from Orbinger et al 2021
      (https://www.sciencedirect.com/science/article/abs/pii/S0921344920307072)
    aggregation-method:
      time: copy
      component: copy
  energy:
    plugins:
      - network-energy-to-transfer-call-data
      - energy-to-carbon
      - sum-energy-components
    unit: kWh
    description: >-
      Total Energy consumed by the server to handle zoom call, for the given
      timestep.
    aggregation-method:
      time: sum
      component: sum

and this is what it should look like after the proposed changes have been made:

explain:
  network-energy-to-transfer-call-data:
    inputs:
      data-transferred:
        unit: GB
        aggregation-method:
          time: sum
          component: sum
        description: >-
          Data transferred over network, in GB. Estimated from values here
          https://tactiq.io/learn/zoom-data-usage-facts.
      kwh-per-gb-network:
        unit: kWh/GB
        aggregation-method:
          time: copy
          component: copy
        description: >-
          Coefficient relating energy expendidture to 1GB of data transferred over
          network. Taken from Orbinger et al 2021
          (https://www.sciencedirect.com/science/article/abs/pii/S0921344920307072)
    outputs:
      energy:
        unit: kWh
        description: >-
          Total Energy consumed by the server to handle zoom call, for the given
          timestep.
        aggregation-method:
          time: sum
          component: sum

  next-plugin...

If two instances of the same parameter are seen with different units or aggregation methods then we should error out.

[zanete]

@jawache assuming this is one is for @narekhovhannisyan ?

[jawache]

@zanete yes, but let's make sure whatever format we come up with works for @osamajandali

[zanete]

@jmcook1186 please refine this with acceptance criteria so @narekhovhannisyan could work on this, and after that it will be easier for @osamajandali to adjust visualiser code

[jmcook1186]

@narekhovhannisyan @zanete added detail to the ticket for the IF side of this.

[zanete]

PR expected soon

[jawache]

@jmcook1186 I was thinking it makes some sense for the plugins to also have optional textual descriptions same a parameters. Right now we're using long strings in the plugin name itself to describe what it is for, but perhaps we can have a description for the plugins themselves also in the initialise block. Maybe some plugins could return descriptions themselves and the built-ins you can define the description in the config. So energy-in-kwh could have a description that is more human readable with somewhat of an explanation as to why e.g. "convert energy to kwh so that it can be used in the XXX calculation methodology"

Also I see you're point on the replication of data, but the manifest files are already super long. I vaguely remember I was against the idea of just fleshing out the initialize block in an output manifest originally with the explain data, I'm not sure what my argument was then but it's making sense now. It also has the advantage that the visualizer could also just display the config associate with the plugin when you hover over it, or just gives more freedom to Osama to get additional data related to a plugin and display it in the fly out.