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)
wherestructure
is the structure under consideration, andindex
andvalue
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)
, whereidx
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.
-
static