# 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

### 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.

This can also be done using the `union` method.

### Accessing a non-existent `UnionDict` key

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

## 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.

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`).

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

## Miscellaneous functions

### Force a variable to be iterable

This support method will force a variable to be an iterable, allowing you to guarantee that the variable will be safe for use in, say, a `for` loop.

### Curry a function

curry(f,x)(y) = f(x,y) or = lambda y: f(x,y). This was modified from the Python Cookbook. Docstrings are also carried over.

### Test to see if an object is iterable

Perform a simple test to see if an object supports iteration

### Test to see if an object is a single char

Perform a simple test to see if an object is a single character

### Flatten a deeply nested iterable

To flatten a deeply nested iterable, use `recursive_flatten`. This method supports multiple levels of nesting, and multiple iterable types

### Test to determine if `list` of `tuple`

Perform a simple check to see if an object is not a list or a tuple

### Create a case-insensitive iterable

Create a case-insensitive object, for instance, if you want the key ‘a’ and ‘A’ to point to the same item in a dict

### Construct a distance matrix lookup function

Automatically construct a distance matrix lookup function. This is useful for maintaining flexibility about whether a function is being computed or if a lookup is being used

### Check class types

Check an object against base classes or derived classes to see if it is acceptable

### Delegate to a separate object

Delegate object method calls, properties and variables to the appropriate object. Useful to combine multiple objects together while assuring that the calls will go to the correct object.

### Wrap a function to hide from a class

Wrap a function to hide it from a class so that it isn’t a method.

### Construct a constrained container

Wrap a container with a constraint. This is useful for enforcing that the data contained is valid within a defined context. Cogent3 provides a base `ConstrainedContainer` which can be used to construct user-defined constrained objects. Cogent3 also provides `ConstrainedString`, `ConstrainedList`, and `ConstrainedDict`. These provided types fully cover the builtin types while staying integrated with the `ConstrainedContainer`.

Here is a light example of the `ConstrainedDict`