feat: added treemap visualisation class

[antalszava]

Description

This PR updates the plotting functionality that's on a feature branch such that it can handle redundancies in the naming.

It renders well the relevant cases discussed in #188.

Please verify that you have completed the following steps

• I have self-reviewed my code.
• I have included test cases validating introduced feature/fix.
• I have updated documentation. N/A: no documentation yet for this feature.

[antalszava]

Hi @Brendan-Reid1991, I've updated the PR as per the comments. Thank you for the feedback!

Note some changes in logic to iron things out:

• TreeMap may accept Routine too - in such cases, such a routine is compiled so that the TreeMap can operate on a compiled routine - the main reason for this is that it eased the validation check of numeric routines (see more details in the next point);
• The check to see if a routine is numeric seemed to have gone down a rabbit hole of its sort: for simple Routine objects, the resources attribute is empty; hence I defaulted to only validation checking compiled routines.

Then, my findings were the following. If the input resource value

• Was a string, then the corresponding resource value type of the compiled routine was a sympy.Symbol whose string value was the original input string;
• Was a float or int, then it remained a float or int;
• Was not defined, then it may be defined by bartiq under the hood by inference from the resource values of the (potential) children of the said routine - in such a case the type of this object was either a sympy.Symbol with the distinct pattern of child_name.resource_name or a more involved sympy Expr object created as a mixture of the resource values of multiple children.

Assuming that input resource values to a routine are either only string, float or int, checking that a routine is numeric seems to boil down to checking that all the resource values of the compiled routine (and its potential children, grandchildren, etc.) exhibit the child_name.resource_name pattern if their type is sympy.Symbol or are otherwise a Number or sympy.Expr. So, such a validation was added to define CompiledRoutine.is_numeric.

I've also added the requested test cases.

Let me know how the changes look in this form. 👍

[Brendan-Reid1991]

@antalszava Thank you! This looks great.

The one thing I'm unsure about is the new methods on Routine objects. Since a Routine object is distinct from a CompiledRoutine, I'm not sure it is kosher to accept Routine and then compile it behind the scenes. Since a tree map is a) nested and b) numeric by design, accepting:

• a numeric, uncompiled routine violates a), since the proper relationships and have not been determined (and it is not the job of the tree map class to compile!)
• a symbolic, uncompiled routine violates a) and b), and a treemap of symbolic equations would be nigh impossible to represent cleanly.
• a symbolic compiled routine violates b), and we use the same reasoning as above
• a numeric compiled routine doesn't violate either of these, and should be the only acceptable input.

Furthermore, while I appreciate the forethought of testing all the children and grandchildren for numerics, it is unnecessary if the input to TreeMap is type hinted as only a CompiledRoutine. The compilation procedure in bartiq ensures that that nth level inherits from the (n+1)th level, where 0th is the root, 1st is the first layer of children etc. So, a CompiledRoutine object with numeric top level resources and symbolic lower level resources should not be possible. I know this to be true, but whether or not we have thought of all possible "unintended ways of using bartiq" and tried to catch them, I can't say**. But this would not be the job of TreeMap to catch.

By only accepting numeric, CompiledRoutines, we also avoid the issue of the child_name.resource_name format of the unevaluated resource values. Essentially, the user has to evaluate their routine to be accepted by TreeMap. It will be enough to type hint for CompiledRoutine, and then do a check on the top level resources to ensure they are all Number types. You've done more work than you needed to! But I appreciate it.

I can merge this today, with the following changes:

• Remove new methods from _routine.py
• Change type hinting for TreeMap to only accept CompiledRoutines, and check for all numeric top level resources.
• Move from if resource not in self.valid_resources check from plot into get_dataframe, as get_dataframe is also public, and plot calls get_dataframe. So it only needs to exist in get_dataframe!
• Line 127 in visualizations.py should be changed from "Contribution" -> contribution to avoid string duplication.

Thank you again!

**NB: We did not intend Routine/CompiledRoutine objects to be manually created, so there may be a way to strong-arm it. This falls under "unintended ways of using bartiq" though.

[Brendan-Reid1991]

And isort failed! Looks like some command modified the import layout, could be a default formatter issue. isort --profile=black . will fix it.

[antalszava]

Hi @Brendan-Reid1991, sure, thank you for the guidance. 👍

By only accepting numeric, CompiledRoutines, we also avoid the issue of the child_name.resource_name format of the unevaluated resource values. Essentially, the user has to evaluate their routine to be accepted by TreeMap. It will be enough to type hint for CompiledRoutine, and then do a check on the top level resources to ensure they are all Number types. You've done more work than you needed to! But I appreciate it.

The reason for the complex logic I've implemented before was that when creating a routine by hand, I could create one where I don't specify the resource of the top-level routine, but only those of the children and then the top-level resource value is symbolic, and the low level ones can still be numeric.

E.g.,

from qref import SchemaV1

from bartiq import Routine, compile_routine
from bartiq.symbolics.sympy_backend import SympyBackend
from bartiq.visualizations import TreeMap, _dataframe_with_unique_routine_names

input_schema = SchemaV1(
    program={
        "name": "root",
        "children": [
            {
                "name": "child1",
                "children": [
                    {
                        "name": "child3",
                        "resources": [
                            {"name": "success_rate", "type": "multiplicative", "value": 7260.0},
                        ],
                    },
                ],
                "resources": [
                    {"name": "success_rate", "type": "multiplicative", "value": 3630.0},
                ],
            },
            {
                "name": "child2",
                "resources": [
                    {"name": "success_rate", "type": "multiplicative", "value": 2320.0},
                ],
            },
        ],
    },
    version="v1",
)

backend = SympyBackend()
routine_from_qref = Routine.from_qref(input_schema, backend=backend)
c_routine = compile_routine(routine_from_qref).routine
type(c_routine.resources['success_rate'].value)

gives

sympy.core.mul.Mul

I intended to check for such cases too - based on the explanation, my understanding now is that likely that's not something bartiq would produce.

I've carried out the changes mentioned. Thank you for the pointers.

And isort failed! Looks like some command modified the import layout, could be a default formatter issue. isort --profile=black . will fix it.

My bad! Had a higher version of isort locally which made the changes - now should be good.

[Brendan-Reid1991]

Amazing @antalszava ! I've approved there now, once the pipeline passes I'll ping Michal to merge and make sure you get your bounty :)