Reference / API reference / dorothy / dorothy.analysis / dorothy.analysis.label_comparison

dorothy.analysis.label_comparison¶

Compare the labels of the stars that two label sources both measure.

If APOGEE and GALAH report correct errors, the difference of their labels for a star has the spread that the two errors predict. This module compares the measured and the predicted spread for each parameter, and plots the differences against Teff and [Fe/H]. It reads only the catalogue and needs no trained model.

Examples

>>> from dorothy.analysis import compare_label_sources, plot_label_differences
>>> comparison = compare_label_sources("data/super_catalogue.h5")
>>> print(comparison.summary())
>>> fig = plot_label_differences("data/super_catalogue.h5")

Functions

`compare_label_sources`(catalogue_path[, ...])	Compare two label sources on the stars that both measure.
`plot_label_differences`(catalogue_path[, ...])	Plot the label differences of the shared stars against Teff and [Fe/H].

Classes

LabelComparison(parameter_names, source_a, ...)

Differences between the labels of two sources for the stars they share.

class dorothy.analysis.label_comparison.LabelComparison(parameter_names, source_a, source_b, n_shared, median_offset, robust_spread, predicted_spread, ratio)[source]¶

Bases: object

Differences between the labels of two sources for the stars they share.

For one parameter and one shared star, d = y_A - y_B is the difference of the labels of sources A and B. The spread that their errors predict is sigma_d = sqrt(sigma_A^2 + sigma_B^2). Each array has one entry per parameter, in the order of parameter_names, and is in the physical units of the catalogue (K for Teff, dex for the others), except n_shared and ratio. A parameter without a shared star has n_shared 0 and NaN statistics.

parameter_names¶: Parameter names of the catalogue.

source_a¶: Name of label source A.

source_b¶: Name of label source B.

n_shared¶: Number of stars with a valid label of the parameter in both sources, shape (n_parameters,).

median_offset¶: Median of d, shape (n_parameters,).

robust_spread¶: (P84 - P16) / 2 of d, shape (n_parameters,).

predicted_spread¶: Median of sigma_d, shape (n_parameters,).

ratio¶: (P84 - P16) / 2 of d / sigma_d, shape (n_parameters,). It is about 1 when both sources report correct errors and the errors are normal. When all stars have the same errors, it equals robust_spread / predicted_spread.

summary()[source]¶

Format the statistics as a text table.

Returns:: A title line, a header line and one line per parameter.
Return type:: str

dorothy.analysis.label_comparison.compare_label_sources(catalogue_path, source_a='apogee', source_b='galah', max_flag_bits=0)[source]¶

Compare two label sources on the stars that both measure.

For each parameter, the function compares the difference d = y_A - y_B of the two labels of a star with sigma_d = sqrt(sigma_A^2 + sigma_B^2), the spread that the reported errors predict. If both sources report correct errors, agree on average and have normal errors, z = d / sigma_d has a standard normal distribution.

A star is shared for a parameter when both sources have a valid label of it. load_labels() reads each source, applies the validity rule and matches the labels to stars by Gaia ID. The function reads the two label groups and no spectra.

Parameters:

catalogue_path (str | Path) – Path to the HDF5 super-catalogue.
source_a (str) – Name of label source A.
source_b (str) – Name of label source B.
max_flag_bits (int) – Largest number of set flag bits, summed over the parameters of a star, for its labels to count; -1 sets no limit (see CatalogueLoader.load_labels).

Returns:

The statistics of each parameter, in physical units (K for Teff, dex for the others).

Raises:

FileNotFoundError – If the catalogue does not exist.
ValueError – If source_a and source_b are equal, max_flag_bits is not an integer >= -1, a source is not in the catalogue, or the catalogue or a label group has no Gaia IDs.

Return type:

LabelComparison

dorothy.analysis.label_comparison.plot_label_differences(catalogue_path, source_a='apogee', source_b='galah', max_flag_bits=0)[source]¶

Plot the label differences of the shared stars against Teff and [Fe/H].

The figure has one row per parameter and two columns. A panel plots d = y_A - y_B against the mean of the two sources’ Teff (left) or [Fe/H] (right). It shows the stars that have a valid label of the parameter, and of Teff or [Fe/H], in both sources. A trend of d with Teff or [Fe/H] is a systematic difference between the sources, and it raises the ratio of compare_label_sources.

Parameters:

catalogue_path (str | Path) – Path to the HDF5 super-catalogue.
source_a (str) – Name of label source A.
source_b (str) – Name of label source B.
max_flag_bits (int) – As in compare_label_sources.

Returns:

The Matplotlib figure, with d in the physical units of the catalogue (K for Teff, dex for the others).

Raises:

FileNotFoundError – If the catalogue does not exist.
ValueError – If the catalogue has no parameter teff or fe_h, or for a reason given at compare_label_sources.

Return type:

Figure