Spectroscopy#

dace_query.spectroscopy.spectroscopy.Spectroscopy: SpectroscopyClass = <dace_query.spectroscopy.spectroscopy.SpectroscopyClass object>#

This is a singleton instance of the SpectroscopyClass class.

To use it, simply import it :

from dace_query.spectroscopy import Spectroscopy

class dace_query.spectroscopy.spectroscopy.SpectroscopyClass(dace_instance=None)#

Bases: object

The spectroscopy class. Use to retrieve data from the spectroscopy module.

Tip

A spectroscopy instance is already provided, to use it:

from dace_query.spectroscopy import Spectroscopy

browse_products(filters, file_type=None, drs_version=None, output_format=None)#

List the filenames of all available data products for observations (raw frames) matching the specified filters.

This method mirrors the signature of download(), making it ideal for previewing available data products before performing any actual downloads. Use it to examine what files would be retrieved based on your filters, file_type, and drs_version

You must specify filtering criteria (such as target name, file key, or other parameters) to limit the scope of the operation. This requirement helps avoid unintentionally requesting large amounts of data from the spectroscopy database.

Filters can be applied to the query via the filters argument (see Filtering and sorting). You can filter on any field available for a raw frame in query_database() (e.g. target_name, spectrum_id, date_night, file_rootname, …).

Available fields for filters argument

Variable name	Description
`spectrum_id`	Used internally by DACE, The unique identifier associated with an observation (a raw frame)
`target_name`	Name of the observed target (Uses the SIMBAD common name if the target has been resolved. Else it uses the name extracted from the `.fits` file). Case sensitive. Filtering on this field (ex: `target_name : { equals : ["HD 10700"]}`) will use a target resolver to find the associated target. Meaning you may use any of the target’s identifiers as long as the target has been resolved by DACE, else you will have to use the name from the raw frame’s `.fits` file.
`pos`	The coordinates in the format : `'<ra (deg)> / <dec (signed deg)>'`
`instrument_name`	The name of the instrument used for the observation. Some instruments are split into versions (e.g. `ESPRESSO18`, `ESPRESSO19`) to account for hardware changes capable of introducing offsets. Separating them simplifies the creation of normalized timeseries.
`program_name`	The name of the program associated with this observation.
`dpr_catg`	Determines the category of observation. Can be either `SCIENCE` (actual observation of a target) or `CALIB` (calibration frames).
`dpr_type`	Determines the type of observation. Varies on the instrument but contains most of the time what each fiber was observing and the spectral type. Some examples : (`OBJECT,FP`, `FLAT,OFF,LAMP`, `STAR,SKY` or `STAR,SKY,G9`).
`obs_start_mjd`	The start time of the observation in Modified Julian Date (MJD).
`file_rootname`	The name of the raw frame in the file system, for example `ESPRE.2018-07-08T10:55:25.173.fits`.
`date_night`	The date of the night of the observation in the format `YYYY-MM-DD`.
`program_code`	The code of the program associated with this observation. Extracted from the `.fits` header without any modification, for example `60.A-9036(A)`.
`parallax`	The parallax of the target in milliarcseconds (mas). It can be empty or `0` if the parallax was not provided in the `.fits` header.
`target_catname`	The name of the target extracted from the `.fits` header without any modification.
`sp_type`	The spectral type of the target. It can be empty if the spectral type was not provided in the `.fits` header.
`mag_v`	The V magnitude of the target. Depending on the instrument, it can be empty if the V magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`mag_i`	The I magnitude of the target. Depending on the instrument, it can be empty if the I magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`pm_a`	The proper motion in right ascension of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`pm_d`	The total proper motion of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`ra_deg`	The right ascension of the target in degrees (ICRS frame, J2000 epoch).
`dec_deg`	The declination of the target in degrees (ICRS frame, J2000 epoch).
`has_products_to_display`	Used internally by DACE to determine if the raw frame has products to display in the web interface. It is `True` if there are products to display and `False` otherwise.
`has_rv`	Used internally by DACE to determine if the raw frame has been reduced and has associated radial velocities. It is `True` if there is atleast one associated radial velocity and `False` otherwise.
`has_guiding_frame`	Used internally by DACE to determine if the raw frame has an associated guiding frame. It is `True` if there is an associated guiding frame and `False` otherwise.

Filtering by DRS version

You can restrict which products are returned by specifying the drs_version argument.

Value	Description
`None`	Do not filter by DRS version (default)
`'latest'`	Select the latest available DRS version
`'DRS-<major>.<minor>.<patch>'`	Select a specific DRS version (e.g. `'DRS-3.3.10'` or `'3.3.10'` or `'DRS-3.3.10-CCF'`)

Example:

from dace_query.spectroscopy import Spectroscopy

filters = {'target_name': {'equal': ['TOI178']}}

# List CCF files for the latest DRS version available
products = Spectroscopy.browse_products(filters=filters, file_type='ccf', drs_version='latest')

# List S1D files for a specific DRS version (e.g. DRS-3.3.10)
products = Spectroscopy.browse_products(filters=filters, file_type='s1d', drs_version='DRS-3.3.10')

# List S2D files products for a specific DRS version with a specifiic extraction method (e.g. DRS-3.3.10-CCF or DRS-3.3.10-SBART)
products = Spectroscopy.browse_products(filters=filters, file_type='s2d', drs_version='DRS-3.3.10-CCF')

Filtering file types

You can specify the type of files to list using the file_type argument.

Available values:

Value	Corresponding file types
`'s1d'`	`S1D_A`, `S1D_B`
`'s2d'`	`S2D_A`, `S2D_B`
`'ccf'`	`CCF_A`, `CCF_B`
`'all'` or `None`	All file types (default)

You can also pass exact file types (e.g. 'S1D_A' or 'CCF_B')

or a list of exact file types (e.g. ['S1D_A', 'S1D_B', 'CCF_B']) to download specific products.

Parameters:

filters (dict) – Filters to apply to the query
file_type (str) – The type of files to download (see “Filtering file types”)
drs_version (Optional[Union[str, list[str]]]) – The DRS version of the products to browse (e.g. 'latest' or specific version in the format 'DRS-<major>.<minor>.<patch>-<rv_extraction_method>')
output_format (Optional[str]) – Type of data returns

Returns:

The desired data in the chosen output format

Return type:

dict[str, ndarray] or DataFrame or Table or dict

download(filters, file_type=None, drs_version=None, compressed=False, output_directory=None, output_filename=None)#

Download reduced products (CCF, S1D, S2D, etc.) for observations (raw frames) matching the specified filters.

Before downloading: you can use browse_products() with identical parameters to preview what files would be downloaded. This is particularly useful for large data sets.

You must specify filtering criteria (such as target name, file key, or other parameters) to limit the scope of the operation. This requirement helps avoid unintentionally requesting large amounts of data from the spectroscopy database.

Filters can be applied to the query via the filters argument (see Filtering and sorting). You can filter on any field available for a raw frame in query_database() (e.g. target_name, spectrum_id, date_night, file_rootname, …).

Available fields for filters argument

Variable name	Description
`spectrum_id`	Used internally by DACE, The unique identifier associated with an observation (a raw frame)
`target_name`	Name of the observed target (Uses the SIMBAD common name if the target has been resolved. Else it uses the name extracted from the `.fits` file). Case sensitive. Filtering on this field (ex: `target_name : { equals : ["HD 10700"]}`) will use a target resolver to find the associated target. Meaning you may use any of the target’s identifiers as long as the target has been resolved by DACE, else you will have to use the name from the raw frame’s `.fits` file.
`pos`	The coordinates in the format : `'<ra (deg)> / <dec (signed deg)>'`
`instrument_name`	The name of the instrument used for the observation. Some instruments are split into versions (e.g. `ESPRESSO18`, `ESPRESSO19`) to account for hardware changes capable of introducing offsets. Separating them simplifies the creation of normalized timeseries.
`program_name`	The name of the program associated with this observation.
`dpr_catg`	Determines the category of observation. Can be either `SCIENCE` (actual observation of a target) or `CALIB` (calibration frames).
`dpr_type`	Determines the type of observation. Varies on the instrument but contains most of the time what each fiber was observing and the spectral type. Some examples : (`OBJECT,FP`, `FLAT,OFF,LAMP`, `STAR,SKY` or `STAR,SKY,G9`).
`obs_start_mjd`	The start time of the observation in Modified Julian Date (MJD).
`file_rootname`	The name of the raw frame in the file system, for example `ESPRE.2018-07-08T10:55:25.173.fits`.
`date_night`	The date of the night of the observation in the format `YYYY-MM-DD`.
`program_code`	The code of the program associated with this observation. Extracted from the `.fits` header without any modification, for example `60.A-9036(A)`.
`parallax`	The parallax of the target in milliarcseconds (mas). It can be empty or `0` if the parallax was not provided in the `.fits` header.
`target_catname`	The name of the target extracted from the `.fits` header without any modification.
`sp_type`	The spectral type of the target. It can be empty if the spectral type was not provided in the `.fits` header.
`mag_v`	The V magnitude of the target. Depending on the instrument, it can be empty if the V magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`mag_i`	The I magnitude of the target. Depending on the instrument, it can be empty if the I magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`pm_a`	The proper motion in right ascension of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`pm_d`	The total proper motion of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`ra_deg`	The right ascension of the target in degrees (ICRS frame, J2000 epoch).
`dec_deg`	The declination of the target in degrees (ICRS frame, J2000 epoch).
`has_products_to_display`	Used internally by DACE to determine if the raw frame has products to display in the web interface. It is `True` if there are products to display and `False` otherwise.
`has_rv`	Used internally by DACE to determine if the raw frame has been reduced and has associated radial velocities. It is `True` if there is atleast one associated radial velocity and `False` otherwise.
`has_guiding_frame`	Used internally by DACE to determine if the raw frame has an associated guiding frame. It is `True` if there is an associated guiding frame and `False` otherwise.

Filtering by DRS version

You can restrict which products are returned by specifying the drs_version argument.

Value	Description
`None`	Do not filter by DRS version (default)
`'latest'`	Select the latest available DRS version
`'DRS-<major>.<minor>.<patch>'`	Select a specific DRS version (e.g. `'DRS-3.3.10'` or `'3.3.10'` or `'DRS-3.3.10-CCF'`)

Example:

from dace_query.spectroscopy import Spectroscopy

filters = {'target_name': {'equal': ['TOI178']}}

# Download CCFs for the latest DRS version available
Spectroscopy.download(filters=filters, file_type='ccf', drs_version='latest')

# Download S1D products for a specific DRS version (e.g. DRS-3.3.10)
Spectroscopy.download(filters=filters, file_type='s1d', drs_version='DRS-3.3.10')

# Download S2D products for a specific DRS version with a specifiic extraction method (e.g. DRS-3.3.10-CCF or DRS-3.3.10-SBART)
Spectroscopy.download(filters=filters, file_type='s2d', drs_version='DRS-3.3.10-CCF')

Filtering file types

You can specify the type of files to download using the file_type argument.

Available values:

Value	Corresponding file types
`'s1d'`	`S1D_A`, `S1D_B`
`'s2d'`	`S2D_A`, `S2D_B`
`'ccf'`	`CCF_A`, `CCF_B`
`'all'` or `None`	All file types (default)

You can also pass exact file types (e.g. 'S1D_A' or 'CCF_B')

or a list of exact file types (e.g. ['S1D_A', 'S1D_B', 'CCF_B']) to download specific products.

To check which file types are available for your filters, you may use browse_products().

Files are sent in different formats based on the number of files to download:

Single file: native format (e.g. .fits)
Multiple files: archive (.tar or .tar.gz)

Parameters:

filters (dict) – Filters to apply to the query
file_type (Optional[str]) – The type of files to download (see “Filtering file types”)
drs_version (Optional[Union[str, list[str]]]) – The DRS version of the products to browse (e.g. 'latest' or specific version in the format 'DRS-<major>.<minor>.<patch>-<rv_extraction_method>')
compressed (Optional[bool]) – Whether to return a compressed archive when multiple files are downloaded
output_directory (Optional[str]) – The directory where files will be saved (defaults to the current working directory)
output_filename (Optional[str]) – The filename for the download (defaults to the server-provided filename)

Returns:

None

Return type:

None

download_files(files, file_type='all', output_directory=None, output_filename=None)#

Deprecated since version 3.0.0: This method is no longer supported and will be removed in a future version. Use download() instead.

Download reduction products specified in argument for the list of raw files specified and save it locally.

Parameters:

files (list[str]) – The raw files
file_type (Optional[str]) – The type of files to download
output_directory (Optional[str]) – The directory where files will be saved
output_filename (Optional[str]) – The filename for the download

Returns:

None

get_guiding_frame(spectrum_id)#

Retrieve the guiding frame associated with a given raw frame (using the raw frame’s unique identifier spectrum_id to find it).

The guiding frame frame is returned as an astropy.io.fits.HDUList object, which can be manipulated using the astropy library. As such, actual frame data and headers are provided by the API, just like when opening a fits file using astropy’s fits.open() method.

You can for example access the data of the guiding frame using guiding_frame[0].data and its header using guiding_frame[0].header.

Parameters:: spectrum_id (int) – The unique id of a raw frame to retrieve the guiding frame for
Returns:: The guiding frame as an astropy.io.fits.HDUList object, or None if no guiding frame is available
Return type:: fits.HDUList or None

get_timeseries(target, limit=10000, filters=None, sort=None, rv_sources=[Source.STANDARD_PROCESSING, Source.PUBLICATION], drs_version=None, sorted_by_instrument=True, output_format=None)#

Retrieve the spectroscopy time series data for a specified target in the chosen format.

Filters can be applied to the query via named arguments (see Filtering and sorting).

Available fields for filters argument

Name	Description	Unit	Data Type
`rv_id`	Unique identifier for RV measurement	`-`	`str`
`rjd`	Barycentric Reduced Julian Date of the observation	`day`	`float`
`texp`	Exposure time	`second`	`float`
`cal_berv`	Barycentric Earth Radial Velocity (BERV)	`m/s`	`float`
`cal_drift_noise`	Drift Noise	`m/s`	`float`
`cal_drift_rv`	Drift Used	`m/s`	`float`
`cal_therror`	Th Error	`m/s`	`float`
`cal_thfile`	Filename of the ThAr calibration file used	`-`	`str`
`ccf_asym`	Asymetry of the CCF	`-`	`float`
`ccf_bispan`	Bisector Span of the CCF	`m/s`	`float`
`ccf_bispan_err`	Uncertainty on the Bisector Span	`m/s`	`float`
`ccf_contrast`	Contrast of the CCF	`-`	`float`
`ccf_contrast_err`	Uncertainty on the CCF Contrast	`-`	`float`
`ccf_mask`	Mask used for CCF computation	`-`	`str`
`ccf_fwhm`	Full Width at Half Maximum (FWHM) of the CCF	`m/s`	`float`
`ccf_fwhm_err`	Uncertainty on the CCF FWHM	`m/s`	`float`
`ccf_noise`	Noise in the CCF	`-`	`float`
`rv`	Radial Velocity	`m/s`	`float`
`rv_err`	Uncertainty on the Radial Velocity	`m/s`	`float`
`ins_mode`	Mode of the instrument during observation	`-`	`str`
`drs_qc`	Whether the DRS quality check was passed (`True` means a point passed the DRS QC, and `False` means it failed.) the DACE webapp filters out `drs_qc=False` points by default but this is not the case for the API. It is recommended to filter `drs_qc=True` when using the API.	`-`	`bool`
`cal_thar_lamp_offset_ar`	ThAr Lamp Offset	`m/s`	`float`
`cal_thar_lamp_offset_ar1`	ThAr Lamp Offset 1	`m/s`	`float`
`cal_thar_lamp_offset_ar2`	ThAr Lamp Offset 2	`m/s`	`float`
`spectro_sn10`	Signal to Noise ratio at order 10	`-`	`float`
`spectro_sn20`	Signal to Noise ratio at order 20	`-`	`float`
`spectro_sn30`	Signal to Noise ratio at order 30	`-`	`float`
`spectro_sn40`	Signal to Noise ratio at order 40	`-`	`float`
`spectro_sn50`	Signal to Noise ratio at order 50	`-`	`float`
`spectro_sn60`	Signal to Noise ratio at order 60	`-`	`float`
`spectro_halpha`	H Alpha activity index	`-`	`float`
`spectro_halpha_err`	Uncertainty on H Alpha activity index	`-`	`float`
`spectro_halpha_flx_h`	H Alpha flux in the H window	`-`	`float`
`spectro_halpha_flx_h_err`	Uncertainty on H Alpha flux in the H window	`-`	`float`
`spectro_halpha_flx_r1`	H Alpha flux in the R1 window	`-`	`float`
`spectro_halpha_flx_r1_err`	Uncertainty on H Alpha flux in the R1 window	`-`	`float`
`spectro_halpha_flx_r2`	H Alpha flux in the R2 window	`-`	`float`
`spectro_halpha_flx_r2_err`	Uncertainty on H Alpha flux in the R2 window	`-`	`float`
`spectro_na`	Sodium activity index	`-`	`float`
`spectro_na_err`	Uncertainty on Sodium activity index	`-`	`float`
`spectro_na_flx_d1`	Sodium flux in the D1 window	`-`	`float`
`spectro_na_flx_d1_err`	Uncertainty on Sodium flux in the D1 window	`-`	`float`
`spectro_na_flx_d2`	Sodium flux in the D2 window	`-`	`float`
`spectro_na_flx_d2_err`	Uncertainty on Sodium flux in the D2 window	`-`	`float`
`spectro_na_flx_r1`	Sodium flux in the R1 window	`-`	`float`
`spectro_na_flx_r1_err`	Uncertainty on Sodium flux in the R1 window	`-`	`float`
`spectro_na_flx_r2`	Sodium flux in the R2 window	`-`	`float`
`spectro_na_flx_r2_err`	Uncertainty on Sodium flux in the R2 window	`-`	`float`
`spectro_ca`	Calcium activity index	`-`	`float`
`spectro_ca_err`	Uncertainty on Calcium activity index	`-`	`float`
`spectro_ca_flx_k`	Calcium flux in the K window	`-`	`float`
`spectro_ca_flx_k_err`	Uncertainty on Calcium flux in the K window	`-`	`float`
`spectro_ca_flx_h`	Calcium flux in the H window	`-`	`float`
`spectro_ca_flx_h_err`	Uncertainty on Calcium flux in the H window	`-`	`float`
`spectro_ca_flx_r1`	Calcium flux in the R1 window	`-`	`float`
`spectro_ca_flx_r1_err`	Uncertainty on Calcium flux in the R1 window	`-`	`float`
`spectro_ca_flx_r2`	Calcium flux in the R2 window	`-`	`float`
`spectro_ca_flx_r2_err`	Uncertainty on Calcium flux in the R2 window	`-`	`float`
`spectro_smw`	Mount Wilson S activity index	`-`	`float`
`spectro_smw_err`	Uncertainty on Mount Wilson S activity index	`-`	`float`
`spectro_rhk`	Log(R’/HK) activity index	`-`	`float`
`spectro_rhk_err`	Uncertainty on Log(R’/HK) activity index	`-`	`float`
`spectrum_id`	Used internally by DACE, The unique identifier associated with an observation (a raw frame)	`-`	`int`
`instrument_group`	Intrument group of the instrument used for the observation (e.g. `ESPRESSO` for `ESPRESSO18`)	`-`	`str`
`instrument_id`	Unique identifier for the instrument used for the observation (see `instrument_name`	`-`	`int`
`instrument_name`	The name of the instrument used for the observation. Some instruments are split into versions (e.g. `ESPRESSO18`, `ESPRESSO19`) to account for hardware changes capable of introducing offsets. Separating them simplifies the creation of normalized timeseries.	`-`	`str`
`target_id`	Used internally by DACE, unique identifier for target	`-`	`int`
`target_catname`	Name of the observed target (Uses the SIMBAD common name if the target has been resolved. Else it uses the name extracted from `.fits`). Case sensitive.	`-`	`str`
`ra_deg`	Right Ascension in decimal degrees	`deg`	`float`
`dec_deg`	Declination in signed decimal degrees	`deg`	`float`
`pos`	The coordinates in the format : `"<ra_deg> / <dec_signed_deg>"`	`deg`	`float`
`date_night`	The date of the night of the observation in the format `YYYY-MM-DD`.	`-`	`str`
`dpr_catg`	Determines the category of observation. Can be either `SCIENCE` (actual observation of a target) or `CALIB` (calibration frames).	`-`	`str`
`dpr_type`	Determines the type of observation. Varies on the instrument but contains most of the time what each fiber was observing and the spectral type. Some examples : (`OBJECT,FP`, `FLAT,OFF,LAMP`, `STAR,SKY` or `STAR,SKY,G9`).	`-`	`str`
`program_id`	Used internally by DACE, Unique identifier for the observing program	`-`	`int`
`program_code`	The code of the program associated with this observation.	`-`	`str`
`pub_ref`	Publication Reference, can be empty if the point does not come from a publication	`-`	`str`
`pub_bibcode`	Publication Bibcode/DOI, can be empty if the point does not come from a publication	`-`	`str`
`file_rootname`	The name of the raw frame in the file system, for example `ESPRE.2018-07-08T10:55:25.173.fits`.	`-`	`str`
`status_public`	Whether the data is publicly available (If `True` the data is public, if `False` the data is still private on DACE and not accessible to all users)	`-`	`bool`
`drs_id`	Used internally by DACE, Unique identifier of a given DRS version	`-`	`int`
`rv_extraction_method`	Method used by the DRS for radial velocity extraction (for example `CCF` for standard DRS or the name of a post-processing e.g. `SBART`	`-`	`str`
`version_major`	Major version of the DRS software used to obtain this point	`-`	`int`
`version_minor`	Minor version of the DRS software used to obtain this point	`-`	`int`
`version_patch`	Patch version of the DRS software used to obtain this point	`-`	`int`
`source_product_id`	ID of the file from which the RV was extracted	`-`	`int`
`source_product_file_ext`	File extension of the file from which the RV was extracted (e.g. `POSTDRS_A`, `POSTDRS_SKYSUB_A`, `SBART` etc.). To filter on this field, it is recommended to use the `Source` enum instead.	`-`	`str`
`source_product_file_rootname`	File path to the file from which the RV was extracted	`-`	`str`
`is_latest_drs`	Whether the DRS used to get this radial velocity is the latest for this instrument (HARPS, ESPRESSO, etc.) and rv extraction method (CCF, SBART, ANTARESS, etc.)	`-`	`bool`

All available formats are defined in this section (see Output formats).

Using sorted_by_instrument=True will sort the results by instrument → DRS version → instrument mode and return a nested dictionary structure as shown in the sample output below.

Note : when using sorted_by_instrument=True, the output_format argument is ignored.

Filtering by DRS version

You can further restrict which series are returned by specifying the drs_version argument.

Value	Description
`None`	Do not filter by DRS version (default)
`'latest'`	Select the latest available DRS version
`'DRS-<major>.<minor>.<patch>'`	Select a specific DRS version (e.g. `'DRS-3.3.10'` or `'3.3.10'` or `'DRS-3.3.10-CCF'`)

Example:

from dace_query.spectroscopy import Spectroscopy

# Get timeseries for the latest DRS version available per instrument
timeseries = Spectroscopy.get_timeseries(target='HD69830', drs_version='latest')

# Ge timeseries for a specific DRS version (e.g. DRS-3.3.10)
timeseries = Spectroscopy.get_timeseries(target='HD69830', drs_version='DRS-3.3.10')

# Get timeseries for a specific DRS version with a specifiic extraction method (e.g. DRS-3.3.10-CCF or DRS-3.3.10-SBART)
# Make sure to specify the source (by default we only include standard processing and publications)
timeseries = Spectroscopy.get_timeseries(target='HD69830', rv_sources=[Source.SBART], drs_version='DRS-3.3.10-SBART')

If you set both rv_sources and drs_version, we apply both filters. This means you only get radial-velocity time series that match the selected sources and belong to the selected DRS version.

If that DRS version does not exist for the selected source(s) (for example because it corresponds to a different extraction method / pipeline), then there is no overlap and you will get no results.

Pick a DRS version that matches the RV sources you selected, for example:

from dace_query.spectroscopy import Spectroscopy, Source

# Yields no results as SBART is not selected in rv_sources by default
timeseries = Spectroscopy.get_timeseries(
    target='HR3259',
    drs_version='DRS-3.3.10-SBART' 
)

timeseries = Spectroscopy.get_timeseries(
    target='HR3259',
    rv_sources=[Source.SBART, Source.STANDARD_PROCESSING], # Get both standard and SBART radial velocities
    drs_version='DRS-3.3.10-SBART'                         # Returns only SBART series from DRS-3.3.10
)

timeseries = Spectroscopy.get_timeseries(
    target='HR3259',
    rv_sources=[Source.SBART, Source.STANDARD_PROCESSING], # Get both standard and SBART radial velocities
    drs_version='DRS-3.3.10'                               # Returns SBART + standard series from DRS-3.3.10 (if available)
)

Parameters:

target (str) – The target to retrieve data from.
limit (Optional[int]) – Maximum number of rows to return
filters (Optional[dict]) – Filters to apply to the query
sort (Optional[dict]) – Sort order to apply to the query
rv_sources (Optional[list[Source]]) – List of Source enum values to filter the radial velocity data by their source
drs_version (Optional[Union[str, list[str]]]) – The DRS version to filter the data (e.g. 'latest' or specific version in the format 'DRS-<major>.<minor>.<patch>-<rv_extraction_method>')
sorted_by_instrument (Optional[bool]) – Application of the instrument sorting
output_format (Optional[str]) – Type of data returns

Returns:

The desired data in the chosen output format

Return type:

dict[str, ndarray] or DataFrame or Table or dict

query_database(limit=10000, filters=None, sort=None, output_format=None)#

Query the spectroscopy database to retrieve data in the chosen format. The spectroscopy database contains metadata of raw frames. Use this method to search for observations matching specific criteria (e.g. target name, date, instrument, program id, etc.)

Filters and sorting order can be applied to the query via named arguments (see Filtering and sorting).

Available fields for filters argument

Variable name	Description
`spectrum_id`	Used internally by DACE, The unique identifier associated with an observation (a raw frame)
`target_name`	Name of the observed target (Uses the SIMBAD common name if the target has been resolved. Else it uses the name extracted from the `.fits` file). Case sensitive. Filtering on this field (ex: `target_name : { equals : ["HD 10700"]}`) will use a target resolver to find the associated target. Meaning you may use any of the target’s identifiers as long as the target has been resolved by DACE, else you will have to use the name from the raw frame’s `.fits` file.
`pos`	The coordinates in the format : `'<ra (deg)> / <dec (signed deg)>'`
`instrument_name`	The name of the instrument used for the observation. Some instruments are split into versions (e.g. `ESPRESSO18`, `ESPRESSO19`) to account for hardware changes capable of introducing offsets. Separating them simplifies the creation of normalized timeseries.
`program_name`	The name of the program associated with this observation.
`dpr_catg`	Determines the category of observation. Can be either `SCIENCE` (actual observation of a target) or `CALIB` (calibration frames).
`dpr_type`	Determines the type of observation. Varies on the instrument but contains most of the time what each fiber was observing and the spectral type. Some examples : (`OBJECT,FP`, `FLAT,OFF,LAMP`, `STAR,SKY` or `STAR,SKY,G9`).
`obs_start_mjd`	The start time of the observation in Modified Julian Date (MJD).
`file_rootname`	The name of the raw frame in the file system, for example `ESPRE.2018-07-08T10:55:25.173.fits`.
`date_night`	The date of the night of the observation in the format `YYYY-MM-DD`.
`program_code`	The code of the program associated with this observation. Extracted from the `.fits` header without any modification, for example `60.A-9036(A)`.
`parallax`	The parallax of the target in milliarcseconds (mas). It can be empty or `0` if the parallax was not provided in the `.fits` header.
`target_catname`	The name of the target extracted from the `.fits` header without any modification.
`sp_type`	The spectral type of the target. It can be empty if the spectral type was not provided in the `.fits` header.
`mag_v`	The V magnitude of the target. Depending on the instrument, it can be empty if the V magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`mag_i`	The I magnitude of the target. Depending on the instrument, it can be empty if the I magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`pm_a`	The proper motion in right ascension of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`pm_d`	The total proper motion of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`ra_deg`	The right ascension of the target in degrees (ICRS frame, J2000 epoch).
`dec_deg`	The declination of the target in degrees (ICRS frame, J2000 epoch).
`has_products_to_display`	Used internally by DACE to determine if the raw frame has products to display in the web interface. It is `True` if there are products to display and `False` otherwise.
`has_rv`	Used internally by DACE to determine if the raw frame has been reduced and has associated radial velocities. It is `True` if there is atleast one associated radial velocity and `False` otherwise.
`has_guiding_frame`	Used internally by DACE to determine if the raw frame has an associated guiding frame. It is `True` if there is an associated guiding frame and `False` otherwise.

All available formats are defined in this section (see Output formats).

Parameters:

limit (Optional[int]) – Maximum number of rows to return
filters (Optional[dict]) – Filters to apply to the query
sort (Optional[dict]) – Sort order to apply to the query
output_format (Optional[str]) – Type of data returns

Returns:

The desired data in the chosen output format

Return type:

dict[str, ndarray] or DataFrame or Table or dict

query_region(sky_coord, angle, limit=10000, filters=None, output_format=None)#

Query a region, based on SkyCoord and Angle objects, in the spectroscopy database and retrieve data in the chosen format.

Filters can be applied to the query via named arguments (see Filtering and sorting).

Available fields for filters argument

Variable name	Description
`spectrum_id`	Used internally by DACE, The unique identifier associated with an observation (a raw frame)
`target_name`	Name of the observed target (Uses the SIMBAD common name if the target has been resolved. Else it uses the name extracted from the `.fits` file). Case sensitive. Filtering on this field (ex: `target_name : { equals : ["HD 10700"]}`) will use a target resolver to find the associated target. Meaning you may use any of the target’s identifiers as long as the target has been resolved by DACE, else you will have to use the name from the raw frame’s `.fits` file.
`pos`	The coordinates in the format : `'<ra (deg)> / <dec (signed deg)>'`
`instrument_name`	The name of the instrument used for the observation. Some instruments are split into versions (e.g. `ESPRESSO18`, `ESPRESSO19`) to account for hardware changes capable of introducing offsets. Separating them simplifies the creation of normalized timeseries.
`program_name`	The name of the program associated with this observation.
`dpr_catg`	Determines the category of observation. Can be either `SCIENCE` (actual observation of a target) or `CALIB` (calibration frames).
`dpr_type`	Determines the type of observation. Varies on the instrument but contains most of the time what each fiber was observing and the spectral type. Some examples : (`OBJECT,FP`, `FLAT,OFF,LAMP`, `STAR,SKY` or `STAR,SKY,G9`).
`obs_start_mjd`	The start time of the observation in Modified Julian Date (MJD).
`file_rootname`	The name of the raw frame in the file system, for example `ESPRE.2018-07-08T10:55:25.173.fits`.
`date_night`	The date of the night of the observation in the format `YYYY-MM-DD`.
`program_code`	The code of the program associated with this observation. Extracted from the `.fits` header without any modification, for example `60.A-9036(A)`.
`parallax`	The parallax of the target in milliarcseconds (mas). It can be empty or `0` if the parallax was not provided in the `.fits` header.
`target_catname`	The name of the target extracted from the `.fits` header without any modification.
`sp_type`	The spectral type of the target. It can be empty if the spectral type was not provided in the `.fits` header.
`mag_v`	The V magnitude of the target. Depending on the instrument, it can be empty if the V magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`mag_i`	The I magnitude of the target. Depending on the instrument, it can be empty if the I magnitude was not provided in the `.fits` header or if it is outside of the range of the instrument.
`pm_a`	The proper motion in right ascension of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`pm_d`	The total proper motion of the target in milliarcseconds per year (mas/yr). It can be empty or `0` if the proper motion was not provided in the `.fits` header.
`ra_deg`	The right ascension of the target in degrees (ICRS frame, J2000 epoch).
`dec_deg`	The declination of the target in degrees (ICRS frame, J2000 epoch).
`has_products_to_display`	Used internally by DACE to determine if the raw frame has products to display in the web interface. It is `True` if there are products to display and `False` otherwise.
`has_rv`	Used internally by DACE to determine if the raw frame has been reduced and has associated radial velocities. It is `True` if there is atleast one associated radial velocity and `False` otherwise.
`has_guiding_frame`	Used internally by DACE to determine if the raw frame has an associated guiding frame. It is `True` if there is an associated guiding frame and `False` otherwise.

All available formats are defined in this section (see Output formats).

Parameters:

sky_coord (SkyCoord) – Sky coordinates object from the astropy module
angle (Angle) – Angle object from the astropy module
limit (Optional[int]) – Maximum number of rows to return
filters (Optional[dict]) – Filters to apply to the query
output_format (Optional[str]) – Type of data returns

Returns:

The desired data in the chosen output format

Return type:

dict[str, ndarray] or DataFrame or Table or dict

class dace_query.spectroscopy.spectroscopy.Source(value)#

Bases: Enum

Enumeration of the different sources of radial velocity (RV) data. Used to filter RV time series data based on their provenance and/or extraction pipeline.

A source is a label describing how an RV time series was produced (or ingested).

For RVs produced by a cross-correlation function (CCF) based DRS pipeline, multiple RV series may exist for the same observations depending on the processing variant (for example standard, telluric-corrected, or sky-subtracted CCF products).

Other sources may correspond to alternative RV extraction pipelines, RVs resulting from a specific post-processing (i.e. SBART), or to RVs imported from an alternative source such as a publication.

By default, SpectroscopyClass.get_timeseries() returns RVs from the STANDARD_PROCESSING and PUBLICATION sources, but you can specify which sources to include or exclude using the rv_sources argument.

See SpectroscopyClass.get_timeseries() for usage examples.

Available radial velocity sources

Some DRS or postprocesses may be marked as Private if they are not publicly available. To access private data, ensure you have the necessary permissions and authentication.

Name	Value	Description	Public/Private
`STANDARD_PROCESSING`	`"POSTDRS_A"`	Standard DRS pipeline processing, RVs extracted from CCF. (default)	`Public`
`TELLURIC_CORRECTION`	`"POSTDRS_TELL_CORR_A"`	Standard DRS pipeline processing, RVs extracted from CCF with telluric correction applied.	`Public`
`SKYSUB`	`"POSTDRS_SKYSUB_A"`	Standard DRS pipeline processing, RVs extracted from CCF with sky subtraction applied.	`Public`
`PUBLICATION`	`"PUB"`	RVs imported from publications. (default)	`Public`
`SBART`	`"SBART"`	RVs extracted using the sBART method.	`Private`
`LBL`	`"LBL_A"`	RVs extracted using the LBL method.	`Private`