astrodendro.dendrogram.Dendrogram¶

class astrodendro.dendrogram.Dendrogram¶

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

To create a dendrogram from an array, use the compute() class method:

>>> from astrodendro import Dendrogram
>>> d = Dendrogram.compute(array)

Once the dendrogram has been computed, you can explore it programmatically using the trunk attribute, which allows you to access the base-level structures in the dendrogram:

>>> d.trunk
[<Structure type=leaf idx=101>,
 <Structure type=branch idx=2152>,
 <Structure type=leaf idx=733>,
 <Structure type=branch idx=303>]

Structures can then be recursively explored. For more information on attributes and methods available for structures, see the Structure class.

The dendrogram can also be explored using an interactive viewer. To use this, use the viewer() method:

>>> d.viewer()

and an interactive Matplotlib window should open.

Finally, the plotter() method can be used to facilitate the creation of plots:

>>> p = d.plotter()

For more information on using the plotter and other aspects of the Dendrogram class, see the online documentation.

Attributes

`trunk`	A list of all structures that have no parent structure and form the base of the tree.
`leaves`	A flattened list of all leaves in the dendrogram.
`all_structures`	Yields an iterator over all structures in the dendrogram, in prefix order.

Analysis

`compute`(data[, min_value, min_delta, ...])	Compute a dendrogram from a Numpy array.
`structure_at`(indices)	Get the structure at the specified pixel coordinate.

Input/Output

`save_to`(filename[, format])	Save the dendrogram to a file.
`load_from`(filename[, format])	Load a previously computed dendrogram from a file.

Visualization

`plotter`()	Return a `DendrogramPlotter` instance that makes it easier to construct plots.
`viewer`()	Launch an interactive viewer to explore the dendrogram.

Methods (detail)

static compute(data, min_value='min', min_delta=0, min_npix=0, is_independent=None, verbose=False, neighbours=None, wcs=None)¶

Compute a dendrogram from a Numpy array.

Parameters:

data : numpy.ndarray

The n-dimensional array to compute the dendrogram for

min_value : float or “min”, optional

The minimum data value to go down to when computing the dendrogram. Values below this threshold will be ignored. Defaults to the minimum value in the data.

min_delta : float, optional

The minimum height a leaf has to have in order to be considered an independent entity.

min_npix : int, optional

The minimum number of pixels/values needed for a leaf to be considered an independent entity.

is_independent : function or list of functions, optional

A custom function that can be specified that will determine if a leaf can be treated as an independent entity. The signature of the function should be func(structure, index=None, value=None) where structure is the structure under consideration, and index and value are optionally the pixel that is causing the structure to be considered for merging into/attaching to the tree.

If multiple functions are provided as a list, they are all applied when testing for independence.

neighbours : function, optional

A function that returns the list of neighbours to a given location. Neighbours is called as neighbours(dendrogram, idx), where idx is a tuple describing the n-dimensional location of a pixel. It returns a list of N-dimensional locations of neighbours. This function can implement optional adjacency logic.

Note

idx refers to location in a copy of the input data that has been padded with one element along each edge.

wcs : WCS object, optional

A WCS object that describes data. This is used in the interactive viewer to properly display the data’s coordinates on the image axes. (Requires that wcsaxes is installed; see http://wcsaxes.readthedocs.org/ for install instructions.)

Notes

More information about the above parameters is available from the online documentation at [www.dendrograms.org](www.dendrograms.org).

Examples

The following example demonstrates how to compute a dendrogram from an dataset contained in a FITS file:

>>> from astropy.io import fits
>>> array = fits.getdata('observations.fits')
>>> from astrodendro import Dendrogram
>>> d = Dendrogram.compute(array)

structure_at(indices)¶

Get the structure at the specified pixel coordinate.

This will return None if no structure includes the specified pixel coordinates.

Parameters:

indices: tuple

The pixel coordinates of the structure of interest

save_to(filename, format=None)¶

Save the dendrogram to a file.

Parameters:

filename : str

The name of the file to save the dendrogram to. By default, the file format will be automatically detected from the file extension. At this time, only HDF5 files (extension .hdf5) are supported.

format : str, optional

The format to use for the file. By default, this is not used and the format is auto-detected from the file extension. At this time, the only format supported is 'hdf5'.

static load_from(filename, format=None)¶

Load a previously computed dendrogram from a file.

Parameters:

filename : str

The name of the file to load the dendrogram from. By default, the file format will be automatically detected from the file extension. At this time, only HDF5 files (extension .hdf5) are supported.

format : str, optional

The format to use to read the file. By default, this is not used and the format is auto-detected from the file extension. At this time, the only format supported is 'hdf5'.

plotter()¶: Return a DendrogramPlotter instance that makes it easier to construct plots.

viewer()¶

Launch an interactive viewer to explore the dendrogram.

This functionality is only available for 2- or 3-d datasets.