GaiaXPy API

class PhotometricSystem(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AutoName

An enumeration.

DECam = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Els_Custom_W09_S2 = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Euclid_VIS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Gaia_2 = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Gaia_DR3_Vega = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
HST_ACSWFC = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
HST_HUGS_Std = <gaiaxpy.generator.standardised_photometric_system.StandardisedPhotometricSystem object>
HST_WFC3UVIS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
HST_WFPC2 = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
H_Custom = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Halpha_Custom_AB = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Hipparcos_Tycho = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
IPHAS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
JKC = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
JKC_Std = <gaiaxpy.generator.standardised_photometric_system.StandardisedPhotometricSystem object>
JPAS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
JPLUS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
JWST_NIRCAM = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
LSST = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
PanSTARRS1 = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
PanSTARRS1_Std = <gaiaxpy.generator.standardised_photometric_system.StandardisedPhotometricSystem object>
Pristine = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
SDSS = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
SDSS_Std = <gaiaxpy.generator.standardised_photometric_system.StandardisedPhotometricSystem object>
Sky_Mapper = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Stromgren = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
Stromgren_Std = <gaiaxpy.generator.standardised_photometric_system.StandardisedPhotometricSystem object>
WFIRST = <gaiaxpy.generator.regular_photometric_system.RegularPhotometricSystem object>
get_available_systems()
apply_error_correction(input_multi_photometry, photometric_system=None, output_path='.', output_file='output_corrected_photometry', output_format=None, save_file=True)[source]

Apply error correction (see Montegriffo et al., 2022, for more details). Infer photometric systems if not specified.

Parameters:

  • input_multi_photometry (DataFrame) – Photometry DataFrame, can contain photometry for one or more systems.

  • photometric_system (obj) – Desired photometric system or list of photometric systems.

  • output_path (str) – Path where to save the output data.

  • output_file (str) – Name of the output file without extension (e.g. ‘my_file’).

  • output_format (str) – Desired output format. If no format is given, the output file format will be the same as the input file (e.g. ‘csv’).

  • save_file (bool) – Whether to save the output in a file. If false, output_format and output_file_name are ignored.

Returns:

A DataFrame of all synthetic photometry with corrected errors for the systems for which it is

possible.

Return type:

DataFrame

calibrate(input_object: list | ~pathlib.Path | ~pandas.core.frame.DataFrame | str, sampling: ~numpy.ndarray | None = None, truncation: bool = False, output_path: ~pathlib.Path | str = '.', output_file: str = 'output_spectra', output_format: str | None = None, save_file: bool = True, with_correlation: bool = False, username: str | None = None, password: str | None = None) -> (<class 'pandas.core.frame.DataFrame'>, <class 'numpy.ndarray'>)[source]

Calibration utility: calibrates the input internally-calibrated continuously-represented mean spectra to the absolute system. An absolute spectrum sampled on a user-defined or default wavelength grid is created for each set of BP and RP input spectra. If either band is missing, the output spectrum will only cover the range covered by the available data.

Parameters:

  • input_object (list/Path/pd.DataFrame/str) – Path to the file containing the mean spectra as downloaded from the Archive in their continuous representation, a list of sources ids (string or long), or a pandas DataFrame.

  • sampling (ndarray) – 1D array containing the desired sampling in absolute wavelengths [nm].

  • truncation (bool) – Toggle truncation of the set of bases. The level of truncation to be applied is defined by the recommended value in the input files.

  • output_path (Path/str) – Path where to save the output data.

  • output_file (str) – Name of the output file without extension (e.g. ‘my_file’).

  • output_format (str) – Desired output format. If no format is given, the output file format will be the same as the input file (e.g. ‘csv’).

  • save_file (bool) – Whether to save the output in a file. If false, output_format and output_file will be ignored.

  • with_correlation (bool) – Whether correlation information should be generated.

  • username (str) – Cosmos username, only suggested when input_object is a list or ADQL query.

  • password (str) – Cosmos password, only suggested when input_object is a list or ADQL query.

Returns:

tuple containing:

DataFrame: The values for all sampled absolute spectra. ndarray: The sampling used to calibrate the input spectra (user-provided or default).

Return type:

(tuple)

convert(input_object: list | ~pathlib.Path | ~pandas.core.frame.DataFrame | str, sampling: ~numpy.ndarray | None = array([ 0., 0.10016694, 0.20033389, 0.30050083, 0.40066778, 0.50083472, 0.60100167, 0.70116861, 0.80133556, 0.9015025, 1.00166945, 1.10183639, 1.20200334, 1.30217028, 1.40233723, 1.50250417, 1.60267112, 1.70283806, 1.80300501, 1.90317195, 2.0033389, 2.10350584, 2.20367279, 2.30383973, 2.40400668, 2.50417362, 2.60434057, 2.70450751, 2.80467446, 2.9048414, 3.00500835, 3.10517529, 3.20534224, 3.30550918, 3.40567613, 3.50584307, 3.60601002, 3.70617696, 3.80634391, 3.90651085, 4.0066778, 4.10684474, 4.20701169, 4.30717863, 4.40734558, 4.50751252, 4.60767947, 4.70784641, 4.80801336, 4.9081803, 5.00834725, 5.10851419, 5.20868114, 5.30884808, 5.40901503, 5.50918197, 5.60934891, 5.70951586, 5.8096828, 5.90984975, 6.01001669, 6.11018364, 6.21035058, 6.31051753, 6.41068447, 6.51085142, 6.61101836, 6.71118531, 6.81135225, 6.9115192, 7.01168614, 7.11185309, 7.21202003, 7.31218698, 7.41235392, 7.51252087, 7.61268781, 7.71285476, 7.8130217, 7.91318865, 8.01335559, 8.11352254, 8.21368948, 8.31385643, 8.41402337, 8.51419032, 8.61435726, 8.71452421, 8.81469115, 8.9148581, 9.01502504, 9.11519199, 9.21535893, 9.31552588, 9.41569282, 9.51585977, 9.61602671, 9.71619366, 9.8163606, 9.91652755, 10.01669449, 10.11686144, 10.21702838, 10.31719533, 10.41736227, 10.51752922, 10.61769616, 10.71786311, 10.81803005, 10.91819699, 11.01836394, 11.11853088, 11.21869783, 11.31886477, 11.41903172, 11.51919866, 11.61936561, 11.71953255, 11.8196995, 11.91986644, 12.02003339, 12.12020033, 12.22036728, 12.32053422, 12.42070117, 12.52086811, 12.62103506, 12.721202, 12.82136895, 12.92153589, 13.02170284, 13.12186978, 13.22203673, 13.32220367, 13.42237062, 13.52253756, 13.62270451, 13.72287145, 13.8230384, 13.92320534, 14.02337229, 14.12353923, 14.22370618, 14.32387312, 14.42404007, 14.52420701, 14.62437396, 14.7245409, 14.82470785, 14.92487479, 15.02504174, 15.12520868, 15.22537563, 15.32554257, 15.42570952, 15.52587646, 15.62604341, 15.72621035, 15.8263773, 15.92654424, 16.02671119, 16.12687813, 16.22704508, 16.32721202, 16.42737896, 16.52754591, 16.62771285, 16.7278798, 16.82804674, 16.92821369, 17.02838063, 17.12854758, 17.22871452, 17.32888147, 17.42904841, 17.52921536, 17.6293823, 17.72954925, 17.82971619, 17.92988314, 18.03005008, 18.13021703, 18.23038397, 18.33055092, 18.43071786, 18.53088481, 18.63105175, 18.7312187, 18.83138564, 18.93155259, 19.03171953, 19.13188648, 19.23205342, 19.33222037, 19.43238731, 19.53255426, 19.6327212, 19.73288815, 19.83305509, 19.93322204, 20.03338898, 20.13355593, 20.23372287, 20.33388982, 20.43405676, 20.53422371, 20.63439065, 20.7345576, 20.83472454, 20.93489149, 21.03505843, 21.13522538, 21.23539232, 21.33555927, 21.43572621, 21.53589316, 21.6360601, 21.73622705, 21.83639399, 21.93656093, 22.03672788, 22.13689482, 22.23706177, 22.33722871, 22.43739566, 22.5375626, 22.63772955, 22.73789649, 22.83806344, 22.93823038, 23.03839733, 23.13856427, 23.23873122, 23.33889816, 23.43906511, 23.53923205, 23.639399, 23.73956594, 23.83973289, 23.93989983, 24.04006678, 24.14023372, 24.24040067, 24.34056761, 24.44073456, 24.5409015, 24.64106845, 24.74123539, 24.84140234, 24.94156928, 25.04173623, 25.14190317, 25.24207012, 25.34223706, 25.44240401, 25.54257095, 25.6427379, 25.74290484, 25.84307179, 25.94323873, 26.04340568, 26.14357262, 26.24373957, 26.34390651, 26.44407346, 26.5442404, 26.64440735, 26.74457429, 26.84474124, 26.94490818, 27.04507513, 27.14524207, 27.24540902, 27.34557596, 27.4457429, 27.54590985, 27.64607679, 27.74624374, 27.84641068, 27.94657763, 28.04674457, 28.14691152, 28.24707846, 28.34724541, 28.44741235, 28.5475793, 28.64774624, 28.74791319, 28.84808013, 28.94824708, 29.04841402, 29.14858097, 29.24874791, 29.34891486, 29.4490818, 29.54924875, 29.64941569, 29.74958264, 29.84974958, 29.94991653, 30.05008347, 30.15025042, 30.25041736, 30.35058431, 30.45075125, 30.5509182, 30.65108514, 30.75125209, 30.85141903, 30.95158598, 31.05175292, 31.15191987, 31.25208681, 31.35225376, 31.4524207, 31.55258765, 31.65275459, 31.75292154, 31.85308848, 31.95325543, 32.05342237, 32.15358932, 32.25375626, 32.35392321, 32.45409015, 32.5542571, 32.65442404, 32.75459098, 32.85475793, 32.95492487, 33.05509182, 33.15525876, 33.25542571, 33.35559265, 33.4557596, 33.55592654, 33.65609349, 33.75626043, 33.85642738, 33.95659432, 34.05676127, 34.15692821, 34.25709516, 34.3572621, 34.45742905, 34.55759599, 34.65776294, 34.75792988, 34.85809683, 34.95826377, 35.05843072, 35.15859766, 35.25876461, 35.35893155, 35.4590985, 35.55926544, 35.65943239, 35.75959933, 35.85976628, 35.95993322, 36.06010017, 36.16026711, 36.26043406, 36.360601, 36.46076795, 36.56093489, 36.66110184, 36.76126878, 36.86143573, 36.96160267, 37.06176962, 37.16193656, 37.26210351, 37.36227045, 37.4624374, 37.56260434, 37.66277129, 37.76293823, 37.86310518, 37.96327212, 38.06343907, 38.16360601, 38.26377295, 38.3639399, 38.46410684, 38.56427379, 38.66444073, 38.76460768, 38.86477462, 38.96494157, 39.06510851, 39.16527546, 39.2654424, 39.36560935, 39.46577629, 39.56594324, 39.66611018, 39.76627713, 39.86644407, 39.96661102, 40.06677796, 40.16694491, 40.26711185, 40.3672788, 40.46744574, 40.56761269, 40.66777963, 40.76794658, 40.86811352, 40.96828047, 41.06844741, 41.16861436, 41.2687813, 41.36894825, 41.46911519, 41.56928214, 41.66944908, 41.76961603, 41.86978297, 41.96994992, 42.07011686, 42.17028381, 42.27045075, 42.3706177, 42.47078464, 42.57095159, 42.67111853, 42.77128548, 42.87145242, 42.97161937, 43.07178631, 43.17195326, 43.2721202, 43.37228715, 43.47245409, 43.57262104, 43.67278798, 43.77295492, 43.87312187, 43.97328881, 44.07345576, 44.1736227, 44.27378965, 44.37395659, 44.47412354, 44.57429048, 44.67445743, 44.77462437, 44.87479132, 44.97495826, 45.07512521, 45.17529215, 45.2754591, 45.37562604, 45.47579299, 45.57595993, 45.67612688, 45.77629382, 45.87646077, 45.97662771, 46.07679466, 46.1769616, 46.27712855, 46.37729549, 46.47746244, 46.57762938, 46.67779633, 46.77796327, 46.87813022, 46.97829716, 47.07846411, 47.17863105, 47.278798, 47.37896494, 47.47913189, 47.57929883, 47.67946578, 47.77963272, 47.87979967, 47.97996661, 48.08013356, 48.1803005, 48.28046745, 48.38063439, 48.48080134, 48.58096828, 48.68113523, 48.78130217, 48.88146912, 48.98163606, 49.08180301, 49.18196995, 49.28213689, 49.38230384, 49.48247078, 49.58263773, 49.68280467, 49.78297162, 49.88313856, 49.98330551, 50.08347245, 50.1836394, 50.28380634, 50.38397329, 50.48414023, 50.58430718, 50.68447412, 50.78464107, 50.88480801, 50.98497496, 51.0851419, 51.18530885, 51.28547579, 51.38564274, 51.48580968, 51.58597663, 51.68614357, 51.78631052, 51.88647746, 51.98664441, 52.08681135, 52.1869783, 52.28714524, 52.38731219, 52.48747913, 52.58764608, 52.68781302, 52.78797997, 52.88814691, 52.98831386, 53.0884808, 53.18864775, 53.28881469, 53.38898164, 53.48914858, 53.58931553, 53.68948247, 53.78964942, 53.88981636, 53.98998331, 54.09015025, 54.1903172, 54.29048414, 54.39065109, 54.49081803, 54.59098497, 54.69115192, 54.79131886, 54.89148581, 54.99165275, 55.0918197, 55.19198664, 55.29215359, 55.39232053, 55.49248748, 55.59265442, 55.69282137, 55.79298831, 55.89315526, 55.9933222, 56.09348915, 56.19365609, 56.29382304, 56.39398998, 56.49415693, 56.59432387, 56.69449082, 56.79465776, 56.89482471, 56.99499165, 57.0951586, 57.19532554, 57.29549249, 57.39565943, 57.49582638, 57.59599332, 57.69616027, 57.79632721, 57.89649416, 57.9966611, 58.09682805, 58.19699499, 58.29716194, 58.39732888, 58.49749583, 58.59766277, 58.69782972, 58.79799666, 58.89816361, 58.99833055, 59.0984975, 59.19866444, 59.29883139, 59.39899833, 59.49916528, 59.59933222, 59.69949917, 59.79966611, 59.89983306, 60.        ]), truncation: bool = False, with_correlation: bool = False, output_path: ~pathlib.Path | str = '.', output_file: str = 'output_spectra', output_format: str | None = None, save_file: bool = True, username: str | None = None, password: str | None = None) -> (<class 'pandas.core.frame.DataFrame'>, <class 'numpy.ndarray'>)[source]
Conversion utility: converts the input internally calibrated mean spectra from the continuous representation to a

sampled form. The sampling grid can be defined by the user, alternatively a default will be adopted. Optionally, the continuous representation can be truncated dropping the bases functions (and corresponding coefficients) that were considered not to be significant considering the errors on the reconstructed mean spectra.

Parameters:

  • input_object (list/Path/pd.DataFrame/str) – Path to the file containing the mean spectra as downloaded from the Archive in their continuous representation, a list of sources ids (string or long), or a pandas DataFrame.

  • sampling (ndarray) – 1D array containing the desired sampling in pseudo-wavelengths.

  • truncation (bool) – Toggle truncation of the set of bases. The level of truncation to be applied is defined by the recommended value in the input files.

  • with_correlation (bool) – Whether correlation information should be generated.

  • output_path (Path/str) – Path where to save the output data.

  • output_file (str) – Name of the output file without extension (e.g. ‘my_file’).

  • output_format (str) – Desired output format. If no format is given, the output file format will be the same as the input file (e.g. ‘csv’).

  • save_file (bool) – Whether to save the output in a file. If false, output_format and output_file will be ignored.

  • username (str) – Cosmos username, only suggested when input_object is a list or ADQL query.

  • password (str) – Cosmos password, only suggested when input_object is a list or ADQL query.

Returns:

tuple containing:

DataFrame: The values for all sampled spectra. ndarray: The sampling used to convert the input spectra (user-provided or default).

Return type:

(tuple)

Raises:

ValueError – If the sampling is out of the expected boundaries.

generate(input_object: list | Path | DataFrame | str, photometric_system: list | PhotometricSystem, output_path: Path | str = '.', output_file: str = 'output_synthetic_photometry', output_format: str | None = None, save_file: bool = True, error_correction: bool = False, additional_columns: str | list | dict | None = None, username: str | None = None, password: str | None = None) → DataFrame[source]

Synthetic photometry utility: generates synthetic photometry in a set of available systems from the input internally-calibrated continuously-represented mean spectra. Some standardised photometric systems include a colour-correction to the U bands which will be applied automatically when generating the corresponding synthetic photometry.

Parameters:

  • input_object (list/Path/pd.DataFrame/str) – Path to the file containing the mean spectra as downloaded from the archive in their continuous representation, a list of sources ids (string or long), or a pandas DataFrame.

  • photometric_system (list/PhotometricSystem) – Desired photometric system or list of photometric systems.

  • output_path (Path/str) – Path where to save the output data.

  • output_file (str) – Name of the output file without extension (e.g. ‘my_file’).

  • output_format (str) – Desired output format. If no format is given, the output file format will be the same as the input file (e.g. ‘csv’).

  • save_file (bool) – Whether to save the output in a file or not. If false, output_format and output_file_name will be ignored.

  • error_correction (bool) – Whether to apply to the photometric errors the tabulated factors to mitigate underestimated errors (see Montegriffo et al., 2022, for more details).

  • additional_columns (str/list) – List of additional columns to include in the output. The columns must be requested columns must be available in the input (files, DataFrames) or in the Archive response (lists, queries).

  • username (str) – Cosmos username, only suggested when input_object is a list or ADQL query.

  • password (str) – Cosmos password, only suggested when input_object is a list or ADQL query.

Returns:

A DataFrame of all synthetic photometry results.

Return type:

DataFrame

get_chi2(_L_inv: ndarray, residuals: ndarray) → ndarray[source]

Compute chi-squared (chi2) from given inverse Cholesky of the covariance matrix (L^-1) and a residual vector (r = data - model). This function defines x = L^-1 * r such that chi2 = |x|^2, which guarantees that chi2 >= 0.

Parameters:

  • _L_inv (ndarray) – Inverse square root of the covariance, as computed from the function get_inverse_square_root_covariance_matrix.

  • residuals (ndarray) – Difference between the observed coefficient vector and some model prediction of it.

Returns:

Chi-squared value.

Return type:

float

get_inverse_covariance_matrix(input_object: list | Path | str, band: str | None = None)[source]

Compute the inverse covariance matrix.

Parameters:

  • input_object (object) – Path to the file containing the mean spectra as downloaded from the archive in their continuous representation, a pandas DataFrame, a list of sources ids (string or long), or an ADQL query.

  • band (str) – Chosen band: ‘bp’ or ‘rp’. If no band is passed, the function will compute the inverse covariance for both ‘bp’ and ‘rp’.

Returns:

DataFrame containing the source IDs and the output inverse covariance matrices for the

sources in the input object if it contains more than one source or no band is passed to the function. The function will return a ndarray (of shape (55, 55)) if there is only one source ID in the input data and a single band is selected.

Return type:

DataFrame or ndarray

get_inverse_square_root_covariance_matrix(input_object: list | Path | DataFrame | str, band: str | None = None)[source]

Compute the inverse square root covariance matrix.

Parameters:

  • input_object (list/Path/pd.DataFrame/str) – Path to the file containing the mean spectra as downloaded from the Archive in their continuous representation, a pandas DataFrame, a list of sources ids (string or long), or an ADQL query.

  • band (str) – Chosen band: ‘bp’ or ‘rp’. If no band is passed, the function will compute the inverse square root covariance for both ‘bp’ and ‘rp’.

Returns:

DataFrame containing the source IDs and the output inverse square root covariance matrices

for the sources in the input object if it contains more than one source or no band is passed to the function. The function will return a ndarray (of shape (55, 55)) if there is only one source ID in the input data and a single band is selected.

Return type:

DataFrame or ndarray

load_additional_systems(_systems_path=None)[source]

Load additional photometric systems.

Parameters:

  • _systems_path (str) – Path to directory containing the additional filter files. If not provided, the program

  • one. (will ask the user to input)

Returns:

PhotometricSystem object corresponding to an enumeration of the updated available systems.

Return type:

Enum

plot_spectra(spectra: DataFrame, sampling: ndarray | None = None, multi: bool = False, show_plot: bool = True, output_path: Path | str | None = None, output_file: str | None = None, format: str | None = None, legend: bool = True)[source]

Plot one or more spectra.

Parameters:

  • spectra (DataFrame) – DataFrame of spectra to be plotted.

  • sampling (ndarray) – Sampling used to create the spectra.

  • multi (bool) – Generate a multiple subplots. Default value of False plots each spectrum in its own figure. If True, errors will not be plotted.

  • show_plot (bool) – Show plots if True.

  • output_path (str) – Path to the directory where the figures will be saved. E.g.: ‘/home/user/folder’

  • output_file (str) – Name of the output file without extension (e.g. ‘my_plot’).

  • format (str) – File format for the saved figure. Defaults to ‘jpg’.

  • legend (bool) – Print legend. Valid only if multi is True.

pwl_range(band)[source]

Return the range where the dispersion function is interpolated. Outside this range extrapolation will occur.

Parameters:

band (str) – BP or RP.

Returns:

The minimum and maximum values of the pseudo-wavelength range.

Return type:

(list)

Raises:

ValueError – If the band string is not equal to BP or RP.

pwl_to_wl(band, pwl)[source]

Convert the input pseudo-wavelength value(s) into absolute wavelength for the input band (BP or RP).

Parameters:

  • band (str) – BP or RP.

  • pwl (ndarray) – 1D array containing the pseudo-wavelengths to be converted.

Returns:

The absolute wavelengths corresponding to the input pseudo-wavelength values.

Return type:

(ndarray)

Raises:

ValueError – If the band string is not equal to BP or RP.

remove_additional_systems()[source]

Remove previously loaded additional photometric systems. If no additional systems have been added, no changes will be made.

Returns:

PhotometricSystem object corresponding to an enumeration of the updated available systems.

Return type:

Enum

wl_range(band)[source]

Return the range where the dispersion function is interpolated. Outside this range extrapolation will occur.

Parameters:

band (str) – BP or RP.

Returns:

The minimum and maximum values of the wavelength range.

Return type:

(list)

Raises:

ValueError – If the band string is not equal to BP or RP.

wl_to_pwl(band, wl)[source]

Convert the input wavelength value(s) into pseudo-wavelength for the input band (BP or RP).

Parameters:

  • band (str) – BP or RP.

  • wl (ndarray) – 1D array containing the absolute wavelengths to be converted.

Returns:

The pseudo-wavelengths corresponding to the input absolute wavelength values.

Return type:

(ndarray)

Raises:

ValueError – If the band string is not equal to BP or RP.

Subpackages