Astronomical Dendrograms in Python

The astrodendro package provides an easy way to compute dendrograms of observed or simulated Astronomical data in Python.

About dendrograms

The easiest way to think of a dendrogram is to think of a tree that represents the hierarchy of the structures in your data. If you consider a two-dimensional map of a hierarchical structure that looks like:

_images/schematic_structure_1.png

the equivalent dendrogram/tree representation would look like:

_images/schematic_tree.png

A dendrogram is composed of two types of structures: branches, which are structures which split into multiple sub-structures, and leaves, which are structures that have no sub-structure. Branches can split up into branches and leaves, which allows hierarchical structures to be adequately represented. The term trunk is used to refer to a structure that has no parent structure.

Mapping these terms back onto the structure gives the following:

_images/schematic_structure_2.png

For an example of use of dendrograms on real data, see Goodman, A. et al (2009).

Documentation

Reporting issues and getting help

Please help us improve this package by reporting issues via GitHub. You can also open an issue if you need help with using the package.

Developers

This package was developed by:

  • Thomas Robitaille

  • Chris Beaumont

  • Adam Ginsburg

  • Braden MacDonald

  • Erik Rosolowsky

Acknowledgments

Thanks to the following users for using early versions of this package and providing valuable feedback:

  • Katharine Johnston

Citing astrodendro

If you make use of this package in a publication, please consider adding the following acknowledgment:

This research made use of astrodendro, a Python package to compute dendrograms of Astronomical data (http://www.dendrograms.org/)

If you make use of the analysis code (Computing Dendrogram Statistics) or read/write FITS files, please also consider adding an acknowledgment for Astropy (see http://www.astropy.org for the latest recommended citation).

Public API

astrodendro Package

Functions

periodic_neighbours(axes)

Utility for computing neighbours on datasets with periodic boundaries.

pp_catalog(structures, metadata[, fields, ...])

Iterate over a collection of position-position (PP) structures, extracting several quantities from each, and building a catalog.

ppv_catalog(structures, metadata[, fields, ...])

Iterate over a collection of position-position-velocity (PPV) structures, extracting several quantities from each, and building a catalog.

Classes

BasicDendrogramViewer(dendrogram)

Dendrogram()

This class is used to compute and represent a dendrogram for a given dataset.

DendrogramPlotter(dendrogram)

A class to plot a dendrogram object.

Structure(indices, values[, children, idx, ...])

A structure in the dendrogram, for example a leaf or a branch.

astrodendro.analysis Module

Functions

ppv_catalog(structures, metadata[, fields, ...])

Iterate over a collection of position-position-velocity (PPV) structures, extracting several quantities from each, and building a catalog.

pp_catalog(structures, metadata[, fields, ...])

Iterate over a collection of position-position (PP) structures, extracting several quantities from each, and building a catalog.

Classes

PPStatistic(stat[, metadata])

Compute properties of structures in a position-position (PP) cube.

PPVStatistic(stat[, metadata])

Compute properties of structures in a position-position-velocity (PPV) cube.

PPPStatistic(rhostat, vstat[, metadata])

SpatialBase()

astrodendro.pruning Module

The pruning module provides several functions to perform common pruning via the is_independent keyword in the Dendrogram compute() method.

Examples:

#prune unless leaf peak value >= 5
Dendrogram.compute(data, is_independent=min_peak(5))

#prune unless leaf contains 10 pixels
Dendrogram.compute(data, is_independent=min_npix(10))

#apply both criteria
is_independent = all_true((min_peak(5), min_npix(10)))
Dendrogram.compute(data, is_independent=is_independent)

Functions

all_true(funcs)

Combine several is_independent functions into one

contains_seeds(seeds)

Critieria that leaves contain at least one of a list of seed positions

min_delta(delta)

Minimum delta criteria

min_npix(npix)

Minimum npix criteria

min_peak(peak)

Minimum peak criteria

min_sum(sum)

Minimum sum criteria

astrodendro.structure_collection Module

Classes

StructureCollection(segments, *[, zorder])