astrolab.photometry module

This package contains a list of functions that can be used to analyse images of stars to perform stellar photometry on them. These functions are intended to be used in the stellar photometry experiment.

Note

The first iteration of this module was written by Hiyaa Atreya, with contributions from Ayush Gurule and Tannuvi Agarwal. All three students are Ashoka undergraduates from the UG25 (2022-2026) batch. The code has since undergone major changes, but much of the underlying ideas are the same.

astrolab.photometry.get_star_counts(image_array, star=None, radii=array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]), bkg_counts_pp=0, points_to_avg=1, print_log=False, cmap='Greys_r', plot_apertures=5, aperture_color='firebrick', fig=None, axes=None)

Perform aperture photometry on a star.

The number of counts (pixel values) are measured within a range of apertures whose radii are provided. A constant number of background counts per pixel is removed from each aperture. This number should plateau at the number of counts due solely to the star. The last few points are averaged to return this number.

Parameters

image_array: array_like

A 2D array which serves as the image data.

star: [int, int] or None, default: None

x and y pixel coordinates of the star’s rough location to refine search for the brightest pixel. If None is provided, the star’s location is determined using the brightest pixel.

radii: array_like, default: numpy.arange(20)

A list of radii for the different apertures at which the star’s counts are calculated. By default, a range of radii up to 20 pixels is used.

bkg_counts_pp: float, default: 0.0

A constant number of background counts per pixel. This number is used to compute the total counts due to the background in the aperture. If the aperture is of area A pixels, then the total counts due to the background for that aperture is bkg_counts_pp * A. By default, this value is 0.0.

points_to_avg: int, default: 1

The last n points to average to give the star’s final counts after background subtraction. By default, only the last point’s value is used.

print_log: bool, default: False

Provides option to print a log to debug your code. In this case, it produces a figure with two plots: one which visually shows the star with some of the apertures overlaid, and the other which shows the number of counts as a function of aperture radius.

cmap: str, default: “Greys_r”

A string containing the colormap title. Should be one of the colormaps used by matplotlib: https://matplotlib.org/stable/users/explain/colors/colormaps.html.

plot_apertures: int, default: 5

The number of apertures to overlay over the image of the star in the log.

aperture_color: str, default: ‘firebrick’

Colour of the apertures overlaid on the image of the star. Must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fig: matplotlib figure object, default: None

Figure on which to plot the result. By default, a new figure is created.

axes: ndarray of two elements which are matplotlib axes objects, default: None

Axes on which to plot the result. By default, a new axis of two columns is created.

Returns

star_counts: float

The final averaged number of star counts.

Usage

>>> mizar_counts = get_distances(mizar_image, star=[1024,512])

astrolab.photometry.get_bkg_counts_pp(image_array, aperture_coord=None, aperture_rad=10, n_apertures=200, auto_reject=True, n_sigma=3.0, return_counts_and_areas=False, print_log=False, cmap='Greys_r', aperture_colors=['firebrick', 'k'], fig=None, axes=None)

Compute the average number number of background counts per pixel for a given image.

A large number of apertures are chosen, and the number of counts in each of them is computed. Then, apertures are rejected based on their whether their numbers of counts are significantly far away from the mean value. These “outliers” are assumed to contain stars in them. The underlying assumption of this method is that the majority of the image makes up the background.

Parameters

image_array: array_like

A 2D array which serves as the image data.

aperture_coord: array_like or None, default: None

2D array if (N,2) elements, each denoting the coordinates of the centre of an aperture of aperture_rad radius. By default, these coordinates are chosen randomly.

aperture_rad: int or array_like, default: 20

Radius in pixels of each aperture. If a single number if provided, all apertures have the same radius. If an array is provided, it should either be the same length as the aperture_coord (if it is provided) or n_points, in that order.

n_apertures: int, default: 200

If aperture_coord is not provided, these are the number of apertures that will be initially sampled. This is ignored if aperture_coord is provided, and replaced by the length of aperture_coord.

auto_reject: bool, default: True

Boolean flag that decides whether to automatically reject all data points until they all lie within n_sigma standard deviations away from the mean.

n_sigma: float, default: 3.0

Number of standard deviations away from the mean beyond which to reject all data points.

return_counts_and_areas: bool, default: False

Boolean flag to decide whether to return the number of counts and the areas of the apertures that were finally used (after automatically rejecting apertures, if chosen), in addition to the background counts per pixel. By default, this is not provided.

print_log: bool, default: False

Provides option to print a log to debug your code. In this case, it produces a figure with two plots: one which visually shows the star and all of the initially chosen apertures overlaid, and the other which shows the apertures that have been retained if auto_reject=True.

cmap: str, default: “Greys_r”

A string containing the colormap title. Should be one of the colormaps used by matplotlib: https://matplotlib.org/stable/users/explain/colors/colormaps.html.

aperture_colors: [str, str], default: [‘firebrick’, ‘k’]

Array containing two elements, the first being the color of the unrejected apertures in the first plot, and the second being the color of the apertures after rejection in the second plot. Both colors must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fig: matplotlib figure object, default: None

Figure on which to plot the result. By default, a new figure is created.

axes: ndarray of two elements which are matplotlib axes objects, default: None

Axes on which to plot the result. By default, a new axis of two columns is created.

Returns

bkg_counts_pp: float

The final averaged number of counts per pixel for all background pixels.

counts, areas: array_like, optional: only returned if return_counts_and_areas=True.

Array of finally used counts and areas of each aperture that was used to compute bkg_counts_pp.

Raises

ValueError

If n_apertures or n_sigma is not positive.

ValueError

If aperture_rad is neither a number or a 1D array.

ValueError

If aperture_rad (or any element of aperture_rad) is less than or equal to 1 pixel.

ValueError

If aperture_coord is not provided, and aperture_rad is neither a number, nor an array of n_apertures elements.

ValueError

If aperture_coord is provided, but it isn’t a 2D array, or it doesn’t have the same length as radii.

ValueError

If multiple apertures and radii are provided, and not enough space is left between the largest possible aperture and the edge of the image.

Usage

>>> this_bkg_cpp = get_bkg_counts_pp(mizar_image, aperture_rad=10)

astrolab.photometry.get_bright_star_catalog()

Load a bright-star catalogue of 1346 stars.

Parameters

None

Returns

catalog: Pandas DataFrame

A Pandas dataframe containing data of the 1346 bright stars and their data.

Usage

>>> bright_cat = get_bright_star_catalog()

astrolab.photometry.get_star_data(hr=None, name=None, catalog=None, hr_colname='HR', name_colname='name', requested_colnames=None, return_numpy=False)

Get a star’s data from a catalog.

Parameters

hr: int or None, default: None

HR number of the star.

name: str or None, default: None

Common name of the star. Ignored if hr is provided.

catalog: Pandas DataFrame or None, default: None

Catalog of stars in which to search for requested star’s data. By default, the 1346 bright-star catalog is used.

hr_colname: str or None, default: “HR”

Column name in catalog in which to search for HR number hr.

name_colname: str or None, default: “name”

Column name in catalog in which to search for name name.

requested_colnames: str, list of str or None, default: None

A column name or list of column names in the catalog whose values to return. By default, all columns are returned.

return_numpy: bool, default: False

Boolean flag to decide whether the function returns the data as a Pandas DataFrame, or a NumPy array.

Returns

star_data: Pandas DataFrame or NumPy array

A Pandas dataframe or a NumPy array (if return_numpy=True) containing the requested data of the specified star.

Raises

ValueError

If neither hr nor name are provided.

ValueError

If star is not present in catalog.

Warns

UserWarning

If both hr and name are provided, name is ignored.

Usage

>>> this_star_data = get_star_data(hr=5054)

>>> this_star_data = get_star_data(name="mizar")

astrolab.photometry.get_color_temperature_fits(catalog=None, deg=10, T_colname='Teff(K)', colors_colname=['STC_R', 'STC_G', 'STC_B'], return_fit=True, return_err=False, unpack=False, precision=0.01, print_log=False, colband_label=['R', 'G', 'B'], data_colors=['k', 'k', 'k'], fit_colors=['rebeccapurple', 'saddlebrown', 'dimgray'], fit_ls='solid', fit_alpha=0.33, fill_alpha=0.1, fig=None, ax=None)

Fit color and temperature data of stars from a catalog using a polynomial fit, and return the temperatures and fits. Optionally, the errors in the fits can also be returned.

Note

Currently, the errors are equal for each point, and given by the standard deviation of all the points from the fit.

Parameters

catalog: Pandas DataFrame or None, default: None

Catalog of stars in which to search for requested star’s data. By default, the 1346 bright-star catalog is used.

deg: int, default: 10

Order of polynomial fit.

T_colname: str or None, default: “Teff(K)”

Column name in catalog in which to search for temperature data.

colors_colname: list of str, default: [‘STC_R’, ‘STC_G’, ‘STC_B’]

A column name or list of column names where the magnitudes in different bands are stored in the catalog.

return_fit: bool, default: True

Optional flag to return the fit arrays. By default, these are returned.

return_err: bool, default: False

Optional flag to return the array of errors about each point. .. note:: Currently, these are constant values for each of the points corresponding to the standard deviation away from the fit, but point-wise errors could be added later.

unpack: bool, default: False

If True, the returned array is transposed, so that arguments may be unpacked using T, fitBmR, fitGmR, fitBmG = get_color_temperature_fits(). By default, this is True.

precision: float, default: 0.01

Minimum precision in the fitted temperature array. For example, is the temperature precise up to 12_000.0 K, or 12_000.01 K, or 12_000.001 K?

print_log: bool, default: False

Provides option to print a log to debug your code. In this case, it produces a plot with the fits and their standard deviation errors.

colband_label: list of str, default: [‘R’, ‘G’, ‘B’]

A list of labels used to denote the different bands in the plot.

data_colors: list of color strings, default: [‘k’, ‘k’, ‘k’]

Array of colours for the three sets of data-points that are to be fit. All colors must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fit_colors: list of color strings, default: [‘rebeccapurple’, ‘saddlebrown’, ‘dimgray’]

Array of colours for the three fits and their standard-deviation fills. All colors must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fit_ls: str, default: ‘solid’

Linestyle of the fit lines. Linestyle should be one of the matplotlib “linestyles”: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html

fit_alpha: 0 < float < 1, default: 0.33

Alpha of the fit lines.

fill_alpha: 0 < float < 1, default: 0.1

Alpha of the standard-deviation fill around the fit lines.

fig: matplotlib figure object, default: None

Figure on which to plot the result. By default, a new figure is created.

ax: matplotlib axes object, default: None

Axes on which to plot the result. By default, a new axis is created.

Returns

return_T: array_like

Array of either the actual or an interpolated temperature data (based on whrther return_fit=True or not).

return_colors: array_like

Either an array of the actual data points (or the fitted data points, if return_fit=True) for the colors.

err_array: array_like (optional)

Array of the errors about each data point. Returned only if return_err=True.

Usage

>>> thisTemp, thisBmR, thisGmR, thisBmG = get_color_temperature_fits(unpack=True)

>>> thisTemp, thisBmR, thisGmR, thisBmG, thisBmR_err, thisGmR_err, thisBmG_err = get_color_temperature_fits(unpack=True, return_err=True)

astrolab.photometry.get_mags(target_counts, reference_counts, reference_hr=None, reference_name=None, catalog=None, hr_colname='HR', name_colname='name', colors_colname=['STC_R', 'STC_G', 'STC_B'])

Get magnitude of a “target” star relative to a “reference” star whose absolute magnitudes are found in a catalog.

Parameters

target_counts: array_like

Array of photon counts in different filters for the target star

reference_counts: array_like

Array of photon counts in different filters for the reference star

reference_hr: int or None, default: None

HR number of the reference star.

reference_name: str or None, default: None

Common name of the reference star. Ignored if reference_hr is provided.

catalog: Pandas DataFrame or None, default: None

Catalog of stars in which to search for requested star’s data. By default, the 1346 bright-star catalog is used.

hr_colname: str or None, default: “HR”

Column name in catalog in which to search for HR number hr.

name_colname: str or None, default: “name”

Column name in catalog in which to search for name name.

colors_colname: list of str, default: [‘STC_R’, ‘STC_G’, ‘STC_B’]

A column name or list of column names where the magnitudes in different bands are stored in the catalog.

Returns

target_mags: array_like

An array of the target magnitudes.

Raises

AssertionError

If the lengths of target_counts, reference_counts, and colors_colname aren’t the same.

Usage

>>> alcor_mags = get_mags(alcor_counts, mizar_counts, reference_hr=5054)

astrolab.photometry.get_temp(mags, catalog=None, T_colname='Teff(K)', colors_colname=['STC_R', 'STC_G', 'STC_B'], precision=0.01, print_log=False, colband_label=['R', 'G', 'B'], data_colors=['k', 'k', 'k'], fit_colors=['rebeccapurple', 'saddlebrown', 'dimgray'], fit_ls='solid', fit_alpha=0.33, fill_alpha=0.1, fig=None, ax=None)

Get the temperature of a star given its magnitudes in different colour bands and a color-temperature fit obtained from a catalog.

Parameters

mags, array_like

Array of magnitudes in different color bands.

catalog: Pandas DataFrame or None, default: None

Catalog of stars in which to search for requested star’s data. By default, the 1346 bright-star catalog is used.

T_colname: str or None, default: “Teff(K)”

Column name in catalog in which to search for temperature data.

colors_colname: list of str, default: [‘STC_R’, ‘STC_G’, ‘STC_B’]

A column name or list of column names where the magnitudes in different bands are stored in the catalog.

precision: float, default: 0.01

Minimum precision in the fitted temperature array. For example, is the temperature precise up to 12_000.0 K, or 12_000.01 K, or 12_000.001 K?

print_log: bool, default: False

Provides option to print a log to debug your code. In this case, it produces a plot with the fits and their standard deviation errors, as well as lines indicating the corresponding temperatures for each color-band.

colband_label: list of str, default: [‘R’, ‘G’, ‘B’]

A list of labels used to denote the different bands in the plot.

data_colors: list of color strings, default: [‘k’, ‘k’, ‘k’]

Array of colours for the three sets of data-points that are to be fit. All colors must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fit_colors: list of color strings, default: [‘rebeccapurple’, ‘saddlebrown’, ‘dimgray’]

Array of colours for the three fits and their standard-deviation fills. All colors must be one of the matplotlib “named colors”: https://matplotlib.org/stable/gallery/color/named_colors.html.

fit_ls: str, default: ‘solid’

Linestyle of the fit lines. Linestyle should be one of the matplotlib “linestyles”: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html

fit_alpha: 0 < float < 1, default: 0.33

Alpha of the fit lines.

fill_alpha: 0 < float < 1, default: 0.33

Alpha of the standard-deviation fill around the fit lines.

fig: matplotlib figure object, default: None

Figure on which to plot the result. By default, a new figure is created.

ax: matplotlib axes object, default: None

Axes on which to plot the result. By default, a new axis is created.

Returns

T_eff: array_like

Array temperatures obtained, one from each from the color-temperature calibration.

Raises

AssertionError

If the lengths of mags and colors_colname aren’t the same.

Warns

UserWarning

If the computed temperature does not lie within the temperature-range of the catalog data.

Usage

>>> mizar_temp = get_temp(mags=[2.0086,2.1897,1.1739], print_log=True)

astrolab.photometry.get_distances(image_array, origin)

Create an array whose elements contain the pixel distances from a provided origin. This is used to mask out and count pixel values within a circular region.

Parameters

image_array: array_like

A 2D array which serves as the image data.

origin: [int, int]

A 1D array containing the pixel location of the point from which distances are measured.

Returns

distances: array_like

A 2D array containing the distances.

Raises

ValueError

If origin is not a 1D array with two elements.

Warns

UserWarning

If origin does not lie within the image array.

Usage

>>> dist_array = get_distances(this_image, origin=[512,512])

astrolab.photometry.reject_outliers(array, n_sigma=3.0)

Reject all elements of an array that are greater than some number of standard deviations away from the mean, and return a mask of the rejected elements.

Parameters

array: array_like

A 1D array of float data.

n_sigma: float, default: 3.0

Number of standard deviations away from the mean beyond which to reject data points.

Returns

mask: boolean 1D array

A boolean mask of the same length as array, indicating which data points must be rejected.

Usage

>>> this_mask = reject_outliers([1,2,8,10,23,4,2,0.1,3], n_sigma=0.5)