mphot package

mphot package#

mphot.core module#

mphot.core.interpolate_dfs(index: list, *data: DataFrame) → DataFrame[source]#

Interpolates multiple pandas DataFrames based on a given index.

Parameters:

  • index (list) – A list of index values to interpolate over.

  • data (pd.DataFrame) – Variable number of pandas DataFrames to be interpolated.

Returns:

pd.DataFrame – A single DataFrame with interpolated values for the given index.

mphot.core.generate_system_response(efficiency_file: str, filter_file: str) → tuple[str, Series][source]#

Generates a spectral response (SR) file by combining efficiency and filter data.

Parameters:

  • efficiency_file (str) – Path to the CSV file containing efficiency data.

  • filter_file (str) – Path to the CSV file containing filter data.

Returns:

tuple –

A tuple containing:

  • name (str): The name used to refer to the generated SR file.

  • dfSR (pd.Series): The spectral response data.

mphot.core.generate_flux_grid(sResponse: str) → tuple[ndarray, ndarray][source]#
Generates a base flux grid based on atmospheric parameters and response functions, with the following ranges:

airmass: 1 - 3 pwv: 0.05 - 30 mm Teff: 450 - 36500 K

This function reads in a spectral response file and a precomputed grid of flux ingredients, then interpolates and integrates these data to produce a grid of stellar flux responses for various combinations of precipitable water vapor (PWV), airmass, and temperature values.

Parameters:

sResponse (str) – Path to the CSV file containing the spectral response function.

Returns:

tuple –

A tuple containing:

  • coords (np.ndarray): A 4D array with shape representing the coordinates of the grid points. The last dimension contains the values of PWV, airmass, and temperature respectively.

  • data (np.ndarray): A 3D array with shape (len(pwv_values), len(airmass_values), len(temperature_values)) containing the computed flux values for each combination of PWV, airmass, and temperature.

mphot.core.generate_radiance_grid(sResponse: str) → tuple[ndarray, ndarray][source]#
Generates a radiance base grid for atmospheric parameters, with the following ranges:

airmass: 1 - 3 pwv: 0.05 - 30 mm Teff: 450 - 36500 K

This function reads in a spectral response file and a precomputed grid of radiance ingredients, then interpolates and integrates these data to produce a grid of atmospheric flux responses for various combinations of precipitable water vapor (PWV), airmass, and temperature values.

Parameters:

sResponse (str) – Path to the spectral response CSV file.

Returns:

tuple –

A tuple containing:

  • coords (np.ndarray): A 4D array of shape (len(pwv_values), len(airmass_values), len(temperature_values), 3) containing the coordinates for PWV, airmass, and temperature.

  • data (np.ndarray): A 3D array of shape (len(pwv_values), len(airmass_values), len(temperature_values)) containing the integrated atmospheric flux responses.

mphot.core.interpolate_grid(coords: ndarray, data: ndarray, pwv: float, airmass: float, Teff: float) → float[source]#

Interpolates between grid points, using a cubic method.

Parameters:

  • coords (np.ndarray) – Coordinates of base grid generated.

  • data (np.ndarray) – Data of base grid generated.

  • pwv (float) – Precipitable water vapour value at zenith.

  • airmass (float) – Airmass of target/comparison star.

  • Teff (float) – Effective temperature of target/comparison star.

Returns:

float – Interpolated value of grid.

mphot.core.gaussian(delta: float, sigma: float) → float[source]#

Calculate the value of a Gaussian function.

This function computes the value of a Gaussian (normal) distribution for a given delta and sigma.

Parameters:

  • delta (float) – The difference from the mean (x - mu).

  • sigma (float) – The standard deviation of the distribution.

Returns:

float – The value of the Gaussian function at the given delta.

mphot.core.integration_time(fwhm: float, N_star: float, N_sky: float, N_dc: float, plate_scale: float, well_depth: float, well_fill: float) → float[source]#

Calculate the integration time for a given set of parameters.

Parameters:

  • fwhm (float) – Full width at half maximum of the point spread function.

  • N_star (float) – Number of star counts.

  • N_sky (float) – Number of sky counts.

  • N_dc (float) – Number of dark current counts.

  • N_rn (float) – Number of read noise counts.

  • plate_scale (float) – Plate scale in arcseconds per pixel.

  • well_depth (float) – Maximum well depth of the detector.

  • well_fill (float) – Fraction of the well depth to be filled.

Returns:

float – Calculated integration time.

mphot.core.convert_airmass(airmass: float, h: float) → float[source]#

Convert airmass at the observatory to an equivalent airmass at Paranal Observatory, assuming an isothermal atmospheric model.

Parameters:

  • airmass (float) – Airmass at the observatory.

  • h (float) – Altitude of the observatory in meters.

Returns:

float – The equivalent converted airmass at Paranal Observatory.

Reference:

https://acp.copernicus.org/articles/7/6047/2007/

mphot.core.scintillation_noise(r: float, t: float, N_star: float, h: float = 2440, C: float = 1.56, airmass: float = 1.5) → float[source]#

Calculate the scintillation noise for a given set of parameters.

Parameters:

  • r (float) – Aperture radius in meters.

  • t (float) – Exposure time in seconds.

  • N_star (float) – Number of stars.

  • h (float) – Altitude of the observatory in meters. Default is 2440 for Paranal Observatory.

  • C (float) – Empirical coefficient. Default is 1.56, optimized for the 20-cm NGTS telescopes at Paranal Observatory.

  • airmass (float, optional) – Airmass value. Default is 1.5.

Returns:

float – The calculated scintillation noise.

Reference:

https://academic.oup.com/mnras/article/509/4/6111/6442285

mphot.core.get_precision(props: dict, props_sky: dict, Teff: float, distance: float, binning: float = 10, override_grid: bool = False, N_sky: float | None = None, N_star: float | None = None, scn: float | None = None, h: float = 2440, C: float = 1.56, exp_time: float | None = None) → dict[source]#

Calculate the precision of astronomical observations based on various parameters.

Parameters:

  • props (dict) – Dictionary containing properties of the instrument and observation. Expected keys: - “name”: str, name of the instrument - “plate_scale”: float, plate scale of the instrument - “N_dc”: float, dark current noise - “N_rn”: float, read noise - “well_depth”: float, well depth of the detector - “well_fill”: float, well fill level - “read_time”: float, readout time of the detector - “r0”: float, inner radius for aperture - “r1”: float, outer radius for aperture - “ap_rad”: float, optional, aperture radius

  • props_sky (dict) – Dictionary containing properties of the sky. Expected keys: - “pwv”: float, precipitable water vapor - “airmass”: float, airmass of the observation - “seeing”: float, full width at half maximum (FWHM) of the seeing

  • Teff (float) – Effective temperature of the star in Kelvin.

  • distance (float) – Distance to the star in parsecs.

  • binning (float, optional) – Binning time in minutes. Default is 10.

  • override_grid (bool, optional) – If True, override existing grid files. Default is False.

  • N_sky (float, optional) – Number of sky counts, calculated if None. Default is None.

  • N_star (float, optional) – Number of star counts, calculated if None. Default is None.

  • scn (float, optional) – Scintillation noise, calculated if None. Default is None.

  • h (float, optional) – Altitude of the observatory in meters. Default is 2440 for Paranal Observatory.

  • C (float, optional) – Empirical coefficient used in the calculation of scn. Default is 1.56, optimized for the 20-cm NGTS telescopes at Paranal Observatory.

  • exp_time (float, optional) – Exposure time in seconds, calculated if None. Default is None.

Returns:

tuple –

A tuple containing:
image_precisiondict

Precision of the image

binned_precisiondict

Precision of the binned image

componentsdict

Various components used in the calculation

mphot.core.best_gaia_filters(system_name: str, min_weight_sum: float = 0, support_points: int = 8000) → ndarray[source]#

Determine the weights of the linear combination of Gaia filters that best resembles the instrument system response.

Parameters:

  • system_name (str) – Name of the instrument.

  • min_weight_sum (float, optional) – The minimum sum of weights in the linear combination of Gaia filters. Default is 0.

  • support_points (int, optional) – The number of support points in the wavelength spectrum between 0.3 and 3.0 microns used to interpolate the instrument system response and Gaia filter transmission curves. Default is 8000.

Returns:

tuple –

A tuple containing:
image_precisiondict

Precision of the image

binned_precisiondict

Precision of the binned image

componentsdict

Various components used in the calculation

mphot.core.get_precision_gaia(props: dict, props_sky: dict, source_id: uint64, gaia_filter: str | None = None, min_weight_sum: float = 0, support_points: int = 8000, binning: float = 10, override_grid: bool = False, N_sky: float | None = None, scn: float | None = None, h: float = 2440, C: float = 1.56, exp_time: float | None = None, Teff: float | None = None, distance: float | None = None) → dict[source]#

Calculate the precision of astronomical observations based on various parameters and perform calibration of fluxes to Gaia fluxes.

Parameters:

  • props (dict) – Dictionary containing properties of the instrument and observation. Expected keys: - “name”: str, name of the instrument - “plate_scale”: float, plate scale of the instrument - “N_dc”: float, dark current noise - “N_rn”: float, read noise - “well_depth”: float, well depth of the detector - “well_fill”: float, well fill level - “read_time”: float, readout time of the detector - “r0”: float, inner radius for aperture - “r1”: float, outer radius for aperture - “ap_rad”: float, optional, aperture radius

  • props_sky (dict) – Dictionary containing properties of the sky. Expected keys: - “pwv”: float, precipitable water vapor - “airmass”: float, airmass of the observation - “seeing”: float, full width at half maximum (FWHM) of the seeing

  • source_id (np.int64) – The source_id property of the target from the Gaia DR3 catalog.

  • gaia_filter (str, optional) – The Gaia filter used for calibration. Must be one of the following: - “bp” - “g” - “rp” - If None, filters are selected automatically. See https://www.cosmos.esa.int/web/gaia/edr3-passbands for further information. Default is None.

  • min_weight_sum (float, optional) – The minimum sum of Gaia filter weights for determining the best linear combination of Gaia filters. Only used if gaia_filter is not specified. Default is 0.

  • support_points (int, optional) – The number of support points in the wavelength spectrum between 0.3 and 3.0 microns for determining the best linear combination of Gaia filters. Only used if gaia_filter is not specified. Default is 8000.

  • binning (float, optional) – Binning time in minutes. Default is 10.

  • override_grid (bool, optional) – If True, override existing grid files. Default is False.

  • N_sky (float, optional) – Number of sky counts, calculated if None. Default is None.

  • scn (float, optional) – Scintillation noise, calculated if None. Default is None.

  • h (float, optional) – Altitude of the observatory in meters. Default is 2440 for Paranal Observatory.

  • C (float, optional) – Empirical coefficient used in the calculation of scn. Default is 1.56, optimized for the 20-cm NGTS telescopes at Paranal Observatory.

  • exp_time (float, optional) – Exposure time in seconds, calculated if None. Default is None.

  • Teff (float, optional) – Effective temperature of the star in Kelvin. If None, it will be fetched from the Gaia catalog. Default is None.

  • distance (float, optional) – Distance to the star in parsecs. If None, it will be calculated from the parallax fetched from the Gaia catalog. Default is None.

Returns:

tuple –

A tuple containing:
image_precisiondict

Precision of the image

binned_precisiondict

Precision of the binned image

componentsdict

Various components used in the calculation

mphot.core.vega_mag(SRFile: str, props_sky: dict, N_star: float, sky_radiance: float, A: float) → dict[source]#

Calculate the Vega magnitude for a given spectral response file and sky properties.

Parameters:

  • SRFile (str) – Path to the spectral response CSV file.

  • props_sky (dict) – Dictionary containing properties of the sky. Expected keys: - “pwv”: float, precipitable water vapor - “airmass”: float, airmass of the observation

  • N_star (float) – Number of star counts.

  • sky_radiance (float) – Sky radiance value.

  • A (float) – Aperture area in square meters.

Returns:

dict – A dictionary containing the Vega magnitude information: - “star [mag]”: Vega magnitude of the star. - “sky [mag/arcsec2]”: Vega magnitude of the sky per arcsecond squared. - “vega_flux [e/s]”: Vega flux in electrons per second.

mphot.core.update_progress(progress: float | int) → None[source]#

Updates and displays a progress bar in the console.

Parameters:

progress (float or int) – A number between 0 and 1 representing the progress percentage. If an integer is provided, it will be converted to a float. Values less than 0 will be treated as 0, and values greater than or equal to 1 will be treated as 1.

Returns:

None

mphot.core.display_number(x: float, p: int = 3) → str[source]#

Convert a number to a string with the given precision.

Parameters:

  • x (float) – The number to be converted.

  • p (int, optional) – The precision (number of significant digits). Default is 3.

Returns:

str – The number represented as a string with the specified precision.

Examples: >>> display_number(123.456, 4) ‘123.5’ >>> display_number(0.00123456, 2) ‘0.0012’ >>> display_number(123456, 2) ‘1.2e+05’

mphot.core.display_results(r1: tuple, r2: tuple = None) → None[source]#

Display the results of the photometric analysis.

Parameters:

  • props_sky (dict) – Dictionary containing properties of the sky.

  • r1 (tuple) –

    A tuple containing image precision, binned precision, and components for the first set of results.
    • image_precision1 (dict):

      Dictionary containing image precision metrics for the first set.

    • binned_precision1 (dict):

      Dictionary containing binned precision metrics for the first set.

    • components1 (dict):

      Dictionary containing components for the first set.

  • r2 (tuple, optional) –

    A tuple containing image precision, binned precision, and components for the second set of results.
    • image_precision2 (dict):

      Dictionary containing image precision metrics for the second set.

    • binned_precision2 (dict):

      Dictionary containing binned precision metrics for the second set.

    • components2 (dict):

      Dictionary containing components for the second set.

Returns:

None

This function displays the results using pandas DataFrames and does not return any value.

Contents