Useful Utilities

UnionDict – a dict with set like operations and keys as attributes

This object combines the key-element storage of a dict with the union operation of a set() object. It is used in the cogent3.draw module, primarily for the figure and layout attributes.

Accessing elements of a UnionDict

Keys in a UnionDict can be accessed like attributes

from cogent3.util.union_dict import UnionDict

data = UnionDict(a=2, b={"c": 24, "d": [25]})
data.a
2
data["a"]
2
data.b.d
[25]

Updating a UnionDict

If you use the | bitwise operator to compare two dicts and the left one is a UnionDict, a union operation is performed.

from cogent3.util.union_dict import UnionDict

data = UnionDict(a=2, b={"c": 24, "d": [25]})
data.b |= {"d": 25}
data.b
{'c': 24, 'd': 25}

This can also be done using the union method.

data.b.union({"d": [25]})
data.b
{"c": 24, "d": [25]}
{'c': 24, 'd': [25]}

Accessing a non-existent UnionDict key

from cogent3.util.union_dict import UnionDict

data = UnionDict(a=2, b={"c": 24, "d": [25]})
data["k"]
---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Cell In[7], line 4
      1 from cogent3.util.union_dict import UnionDict
      2 
      3 data = UnionDict(a=2, b={"c": 24, "d": [25]})
----> 4 data["k"]

KeyError: 'k'

But if accessing as an attribute, you get an attribute error.

data.k
---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
File ~/work/cogent3.github.io/cogent3.github.io/doc/cogent3/src/cogent3/util/union_dict.py:35, in UnionDict.__getattr__(self, item)
     34 try:
---> 35     return super().__getattr__(item)
     36 except AttributeError:

AttributeError: 'super' object has no attribute '__getattr__'

During handling of the above exception, another exception occurred:

AttributeError                            Traceback (most recent call last)
Cell In[8], line 1
----> 1 data.k

File ~/work/cogent3.github.io/cogent3.github.io/doc/cogent3/src/cogent3/util/union_dict.py:38, in UnionDict.__getattr__(self, item)
     36 except AttributeError:
     37     msg = f"'{item}' not a key or attribute"
---> 38     raise AttributeError(msg)

AttributeError: 'k' not a key or attribute

Using Cogent3’s optimisers for your own functions

You have a function that you want to maximise/minimise. The parameters in your function may be bounded (must lie in a specific interval) or not. The cogent3 optimisers can be applied to these cases. The Powell (a local optimiser) and SimulatedAnnealing (a global optimiser) classes in particular have had their interfaces standardised for such use cases. We demonstrate for a very simple function below.

We write a simple factory function that uses a provided value for omega to compute the squared deviation from an estimate, then use it to create our optimisable function.

import numpy

def DiffOmega(omega):
    def omega_from_S(S):
        omega_est = S / (1 - numpy.e ** (-1 * S))
        return abs(omega - omega_est) ** 2

    return omega_from_S

omega = 0.1
f = DiffOmega(omega)

We then import the minimise function and use it to minimise the function, obtaining the fit statistic and the associated estimate of S. Note that we provide lower and upper bounds (which are optional) and an initial guess for our parameter of interest (S).

from cogent3.maths.optimisers import maximise, minimise

S = minimise(
    f,  # the function
    xinit=1.0,  # the initial value
    bounds=(-100, 100),  # [lower,upper] bounds for the parameter
    local=True,  # just local optimisation, not Simulated Annealing
    show_progress=False,
)
assert 0.0 <= f(S) < 1e-6
print("S=%.4f" % S)
S=-3.6150

The minimise and maximise functions can also handle multidimensional optimisations, just make xinit (and the bounds) lists rather than scalar values.