nested_dict 1.0.7

(Documentation hosted at ``<wwwfgu.anat.ox.ac.uk/~lg/oss/nested_dict> here``_ .)

***************************************
nested dictionaries
***************************************
**nested_dict** extends `collections.defaultdict
<http://docs.python.org/library/collections.html#defaultdict-objects>`_
to allow dictionaries with multiple levels of nesting to be created on the fly::


from nested_dict import *

nd = nested_dict()

nd["a"]["b"]["c"] = 311
nd["d"]["e"] = 311

Each nested level is create magically when accessed, a process known as
`"auto-vivification" <http://en.wikipedia.org/wiki/Autovivification>`_ in perl.


******************************************************************************
nested dictionaries of sets / lists and other collections
******************************************************************************
**nested_dict** also extends `collections.defaultdict
<http://docs.python.org/library/collections.html#defaultdict-objects>`_
to allow dictionaries of lists, sets or other collections with a specified
level of nesting level.


==================================================
1) The old fashioned way using ugly syntax
==================================================
::

d = dict()

d.setdefault(""1st group", []).append(3)
d.setdefault(""2nd group", []).append(5)
d.setdefault(""2nd group", []).append(8)
d.setdefault(""1st group", []).append(4)
d.setdefault(""2nd group", []).append(5)

====================================================================================================
2) ``default_dict`` adds ``list``\ s automatically when required
====================================================================================================

::

from collections import defaultdict

dd = defaultdict(list)

dd["1st group"].append(3)
dd["2nd group"].append(5)
dd["2nd group"].append(8)
dd["1st group"].append(4)
dd["2nd group"].append(5)

====================================================================================================
3) ``nested_dict`` adds ``list``\ s automatically when required for nested
dictionaries
====================================================================================================

::

from nested_dict import nested_dict

# specify two levels of nesting
nd = nested_dict(2, list)

nd["1st group"]["subset a"].append(3)
nd["2nd group"]["subset a"].append(5)
nd["2nd group"]["subset b"].append(8)
nd["1st group"]["subset a"].append(4)
nd["2nd group"]["subset b"].append(5)

print nd

gives::

{'1st group': {'subset a': [3, 4]},
'2nd group': {'subset b': [8, 5],
'subset a': [5]}}


*********************************
More examples:
*********************************

==================================
"Auto-vivifying" nested dict
==================================
::

nd= nested_dict()
nd["mouse"]["chr1"]["+"] = 311
nd["mouse"]["chromosomes"]="completed"
nd["mouse"]["chr2"] = "2nd longest"
nd["mouse"]["chr3"] = "3rd longest"

for k, v in nd.iteritems_flat():
print "%-30s=-%20s" % (k,v)

Gives
::

('mouse', 'chr3') =- 3rd longest
('mouse', 'chromosomes') =- completed
('mouse', 'chr2') =- 2nd longest
('mouse', 'chr1', '+') =- 311

====================================================================
Specifying the autovivified object
====================================================================
If you wish the nested dictionary to hold a collection rather than a scalar,
you have to write::

nd["mouse"]["chr2"] = list()
nd["mouse"]["chr2"].append(12)

or::

nd["mouse"]["chr2"] = set()
nd["mouse"]["chr2"].add(84)

Which doesn't seem very "auto" at all!

Instead, specify the collection in the constructor of **nested_dict**::

# two levels of nesting
nd2 = nested_dict(2, list)
nd2["mouse"]["chr2"].append(12)

# three levels of nesting
nd3 = nested_dict(3, set)
nd3["mouse"]["chr2"]["categorised"].add(3)

# counts
nd4 = nested_dict(2, int)
nd4["mouse"]["chr2"]+=4
nd4["human"]["chr1"]+=3
nd4["human"]["chr3"]+=4