Traverse hestia graph of cycles

[cswh]

• to find for a specific cycle all related hestia cycles ("activities")
• in order to reach just dependencies with emissions ("elementary flows")

[cswh]

39 was the first try. but using https://api-staging.hestia.earth/swagger/#/default/get_cycles__id__deep_relations will be an easier way to implement this.

• [x] understand and document how https://api-staging.hestia.earth/swagger/#/default/get_cycles__id__deep_relations works
• [x] make a working example to get a flat list of connected cycles to a cycle
• [x] implement it nicely within the existing api calls

[cswh]

The following is derived from a lot of trying around. I am not 100% sure, if these conclusions account for the whole Hestia database.

It seems, that cycles are not directly connected within the Hestia Database. A call to

requests.get("https://api-staging.hestia.earth/cycles/CYCLE_ID/cycles").json()

for a bunch of CYCLE_IDs always returns an emtpy list.

However the cycles can be connected via impactassessments as can be seen in the section "2. Cycle Navigator", e.g. here: https://www-staging.hestia.earth/cycle/znex7uqxsfqn

To find the indirectly connected cycles down- and upstream, a different API call can be used. For example:

requests.get("https://api-staging.hestia.earth/cycles/znex7uqxsfqn/deep-relations?connections=ImpactAssessmentcycle,CycleinputsimpactAssessment&includeAggregated=true&offset=0&limit=1000").json()

yields a list of cycles and impactassessments, each with the information on "parentIds" and "childIds". Parents and childs of cycles consist purely of impactassessments and vice versa. With the contained information it is possible to construct the potential connected graph which can be opened by clicking manually on the nodes in the section "2. Cycle Navigator" on:

https://www-staging.hestia.earth/cycle/znex7uqxsfqn

I propose to use the API entry point at /cycles/CYCLE_ID/deep-relations in the form above to get the desired flat list of connected cycles. The impactassessments in the result list can be discarded for now. The limit parameter should be set big enough to account for the whole connected graph. Since the Hestia Database is not fully linked, it should not yield to many results. While trying with different cycle_ids the returned list did never consist of more than 100 elements.

Probably a good list being returned could look something like this (in a brightway exchange thinking):

[
{from: {@type="cycle", @id: PARENT_CYCLE_ID}, to: {@type: "cycle", @id: CHILD_CYCLE_ID}, product: {@type: "term", @id: PRODUCT_TERM_ID}},
...
]

Caution: The parent and cycle ids in this case refer only to cycles. To derive them, a hop via an impactassessment has to be made.

In that form with the proposed "@type" and "@id" fields, this dictionary could be used directly with the already implemented API functionality to get more neccessary information on the desired node.

[tfardet]

Deep relations returns

[{'@id': '_pgqzpzubd_3',
  '@type': 'Cycle',
  'name': 'Soybean, seed (whole) - Brazil - 2013 - Soybeans production',
  'aggregated': False,
  'childIds': ['bv2ktx0jjkub'],
  'parentIds': []},
 {'@id': '1wcs_sfkyghn',
  '@type': 'ImpactAssessment',
  'name': 'Meat, beef cattle (cold carcass weight) - Brazil - 2013',
  'aggregated': False,
  'childIds': [],
  'parentIds': ['_mlxmewvtlzx']},
...
]

For "ImpactAssessment" objects returned by deep-relations, the "parentIds" list is always of size 1 and corresponds to the "parent" cycle of that impact assessment, i.e. the impact assessment characterizes an output of that parent cycle. The parent cycle is also what is stored in the "cycle" entry of the impact assessment Hestia json.

[cswh]

So in order to find a cycle C_B producing an input for cycle C_A

C_A["parentId"] would lead to an Impact Assessment I and I["parentId"] would lead to the desired cycle C_B.

[cswh]

Is implemented with #44