Plums-Microlib Taxonomy

The Plums taxonomy module implements a taxonomy creation, modification and look-up API.

It mainly consists in 3 classes:

  • The Label class which is the base class for all Taxonomy creation: it implements the actual tree logic and the creation API.

  • The Tree class which is a reader/helper class to facilitate lookups, iterative walks and comparisons.

  • The Taxonomy class which is a special kind of Tree with a fixed, virtual root to allow multiple rooted taxonomies.

The Taxonomy API

Trees helper classes

Taxonomies iterators

class plums.commons.data.taxonomy.iterator.TreeIteratorBase(tree, max_depth=None)[source]

Bases: object

Abstract Base Class for all Tree iterator classes.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to iterate.

class plums.commons.data.taxonomy.iterator.DefaultTreeIterator(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates in a top-down manner and gives interfaces to other iteration flavors.

It starts at the tree root and go down until it reaches a leaf label. It then steps upward and searches for the next leafs.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

The iterator will yield: f, b, a, d, c, e, g, i then h.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root)

  • which to iterate. (on) –

top_down()[source]

Make an iterator which iterate through a Tree in a top-down order.

See also

The TopDownTreeIterator class.

Yields (Label): A tree Label node.

bottom_up()[source]

Make an iterator which iterate through a Tree in a bottom-up order.

See also

The BottomUpTreeIterator class.

Yields (Label): A tree Label node.

depth_wise_top_down()[source]

Make an iterator which iterate through a Tree in a depth-wise top-down order.

See also

The TopDownDepthWiseTreeIterator class.

Yields (Iterable[Label]): An iterator over an ensemble of Label nodes.

depth_wise_bottom_up()[source]

Make an iterator which iterate through a Tree in a depth-wise bottom-up order.

See also

The BottomUpDepthWiseTreeIterator class.

Yields (Iterable[Label]): An iterator over an ensemble of Label nodes.

floor(depth)[source]

Make an iterator which iterate through a Tree given depth floor.

Parameters

depth (int) – The Label depth (relative to tree root) on which to iterate.

See also

The FloorTreeIterator class.

Yields (Label): A tree Label node.

class plums.commons.data.taxonomy.iterator.TopDownTreeIterator(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates in a top-down manner.

It starts at the tree root and go down until it reaches a leaf label. It then steps upward and searches for the next leafs.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

The iterator will yield: f, b, a, d, c, e, g, i then h.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to iterate.

class plums.commons.data.taxonomy.iterator.BottomUpTreeIterator(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates in a bottom-up manner.

It starts at a leaf and go up until it reaches the tree root. It then steps downward and searches for the next leafs to start from.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

The iterator will yield: h, i, g, e, c, d, a, b then f.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root)

  • which to iterate. (on) –

class plums.commons.data.taxonomy.iterator.FloorTreeIterator(tree, depth)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates over all labels in a given depth.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

If depth is 2, the iterator will yield: a, d then i.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • depth (int) – The Label depth (relative to tree root) on which to iterate.

class plums.commons.data.taxonomy.iterator.TopDownDepthWiseTreeIterator(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates through a Tree in a depth-wise top-down manner.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

The iterator will yield: (f, ), (b, g), (a, d, i) then (c, e, h).

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to iterate.

class plums.commons.data.taxonomy.iterator.BottomUpDepthWiseTreeIterator(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.iterator.TreeIteratorBase

A Tree iterator class which iterates through a Tree in a depth-wise bottom-up manner.

For example, given the following:

f
├── b
│   ├── a
│   ╰── d
│       ├── c
│       ╰── e
╰── g
    ╰── i
        ╰── h

The iterator will yield: (c, e, h), (a, d, i), (b, g) then (f, ).

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to iterate.

Taxonomies accessors

class plums.commons.data.taxonomy.accessor.TreeAccessorBase(tree, max_depth=None)[source]

Bases: object

Abstract Base Class for all Tree accessor classes.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to allow access.

class plums.commons.data.taxonomy.accessor.DefaultTreeAccessor(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.accessor.TreeAccessorBase

Tree accessor class which retrieve Label from their name and exposes other access flavors as properties.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to allow access.

property name

Access Label from their name.

Type

NameTreeAccessor

property id

Access Label from their id.

Type

IdTreeAccessor

class plums.commons.data.taxonomy.accessor.NameTreeAccessor(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.accessor.TreeAccessorBase

Tree accessor class which retrieve Label from their name.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to allow access.

class plums.commons.data.taxonomy.accessor.IdTreeAccessor(tree, max_depth=None)[source]

Bases: plums.commons.data.taxonomy.accessor.TreeAccessorBase

Tree accessor class which retrieve Label from their id.

Parameters

  • tree (Tree) – The tree on which to iterate.

  • max_depth (int) – Optional. Default to None. If provided, the maximum Label depth (relative to tree root) on which to allow access.