CHEOPS#

dace_query.cheops.cheops.Cheops: CheopsClass = <dace_query.cheops.cheops.CheopsClass object>#

This is a singleton instance of the CheopsClass class.

To use it, simply import it :

from dace_query.cheops import Cheops
class dace_query.cheops.cheops.CheopsClass(dace_instance=None)#

Bases: object

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

Tip

A cheops instance is already provided, to use it :

from dace_query.cheops import Cheops
browse_products(filters, file_type='all', aperture=None, output_format=None)#

List the filenames of all available data products for visits 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 aperture settings.

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 CHEOPS database. Filters can be applied to the query via named arguments (see Filtering and sorting).

Setting filters
# Filtering using file_key
file_key = 'CH_PR100018_TG027204_V0200'
filters: dict = {'file_key':{'equal': [file_key]}}

# Filtering using target_name
target_name = 'TOI178'
filters: dict = {'target_name':{'equal': [target_name]}}

File types can be specified in two ways:

General categories

  • lightcurves

  • images

  • reports

  • full

  • sub

  • all

Specific CHEOPS product identifiers

  • EXT_PRE_StarCatalogue

  • MCO_REP_BadPixelMapFullArray

  • MCO_REP_BadPixelMapSubArray

  • MCO_REP_DarkFrameFullArray

  • MCO_REP_DarkFrameSubArray

  • PIP_COR_PixelFlagMapSubArray

  • PIP_REP_DarkColumns

  • SCI_CAL_SubArray

  • SCI_COR_Lightcurve

  • SCI_COR_SubArray

  • SCI_RAW_FullArray

  • SCI_RAW_Imagette

  • SCI_RAW_SubArray

  • SCI_RAW_Attitude

  • SCI_RAW_Centroid

  • SCI_RAW_EventReport

  • SCI_RAW_HkAsy30759

  • SCI_RAW_HkAsy30767

  • SCI_RAW_HkCe

  • SCI_RAW_HkCentroid

  • SCI_RAW_HkDefault

  • SCI_RAW_HkExtended

  • SCI_RAW_HkIaswPar

  • SCI_RAW_HkIfsw

  • SCI_RAW_HkOperationParameter

  • log

  • mp4

  • pdf

Aperture can be used to further filter products. It is useful in the case where we need to download a single specific lightcurves or mp4 data product. Setting the aperture on other file types is not supported and will raise an error.

Aperture types available are : 'default', 'optimal', 'rinf' and 'rsup'

Parameters:

  • filters (dict) – Filters to apply to the query

  • file_type (str) – The type of files to download

  • aperture (Optional[str]) – The aperture ('default', 'optimal', 'rinf', 'rsup')

  • 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

Listing all available products for a given target name
from dace_query.cheops import Cheops
values = Cheops.browse_products(filters={'target_name':{'equal': [target_name]}})
Listing all available lightcurves for a given target name
from dace_query.cheops import Cheops
values = Cheops.browse_products(filters={'target_name':{'equal': [target_name]}}, file_type='lightcurves')
download(filters, file_type='all', aperture=None, compressed=True, output_directory=None, output_filename=None)#

Download CHEOPS data products (.fits, .pdf, etc.) for visits matching the specified filters.

Before downloading: 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 CHEOPS database. Filters can be applied to the query via named arguments (see Filtering and sorting).

Setting filters
# Filtering using file_key
file_key = 'CH_PR100018_TG027204_V0200'
filters: dict = {'file_key':{'equal': [file_key]}}

# Filtering using target_name
target_name = 'TOI178'
filters: dict = {'target_name':{'equal': [target_name]}}

File types can be specified in two ways:

General categories

  • lightcurves

  • images

  • reports

  • full

  • sub

  • all

Specific CHEOPS product identifiers

  • EXT_PRE_StarCatalogue

  • MCO_REP_BadPixelMapFullArray

  • MCO_REP_BadPixelMapSubArray

  • MCO_REP_DarkFrameFullArray

  • MCO_REP_DarkFrameSubArray

  • PIP_COR_PixelFlagMapSubArray

  • PIP_REP_DarkColumns

  • SCI_CAL_SubArray

  • SCI_COR_Lightcurve

  • SCI_COR_SubArray

  • SCI_RAW_FullArray

  • SCI_RAW_Imagette

  • SCI_RAW_SubArray

  • SCI_RAW_Attitude

  • SCI_RAW_Centroid

  • SCI_RAW_EventReport

  • SCI_RAW_HkAsy30759

  • SCI_RAW_HkAsy30767

  • SCI_RAW_HkCe

  • SCI_RAW_HkCentroid

  • SCI_RAW_HkDefault

  • SCI_RAW_HkExtended

  • SCI_RAW_HkIaswPar

  • SCI_RAW_HkIfsw

  • SCI_RAW_HkOperationParameter

  • log

  • mp4

  • pdf

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

  • Single file: native format (.fits, .pdf, .mp4, etc.)

  • Multiple files: archive (.tar or .tar.gz)

Specifying compression behavior

You can control the compression behavior of the downloaded files using the compressed parameter.

By default, files will be compressed into a .tar.gz archive if multiple files are downloaded.

If you want to disable compression, set the compressed parameter to False. (will result in a .tar archive).

If you want to force compression, set the compressed parameter to True. (will result in a .tar.gz archive).

When downloading large datasets, it is recommended to disable compression by setting compressed=False. This will speed up the download process and reduce memory usage but will result in a larger file size.

Aperture can be used to further filter products. It is useful in the case where we need to download a single specific lightcurves or mp4 data product. Setting the aperture on other file types is not supported and will raise an error.

Aperture types available are : 'default', 'optimal', 'rinf' and 'rsup'

Output directory is the location where the downloaded files will be saved.

Output filename is the name of the downloaded file. If not specified, a default name will be used.

Note

When specifying output_filename, be mindful of the appropriate file extension:

When downloading a single file : match the extension to the file type (e.g., output_filename="lightcurve.fits") or leave output_filename as None to use the default name When downloading multiple files : use a .tar or .tar.gz extension (e.g., output_filename="my_data.tar.gz") or leave output_filename as None to use the default name

Parameters:

  • filters (dict) – Filters to apply to the query

  • file_type (str) – The type of files to download

  • aperture (Optional[str]) – The aperture ('default', 'optimal', 'rinf', 'rsup')

  • compressed (Optional[bool]) – Specify whether to compress the downloaded files. (True for .tar.gz, False for .tar)

  • output_directory (Optional[str]) – The directory where files will be saved

  • output_filename (Optional[str]) – The filename for the download

Return type:

None

Returns:

None

Downloading all products for a given visit
from dace_query.cheops import Cheops
filters_to_use = {'file_key': {'contains': ['CH_PR300001_TG000301_V0000']}}
Cheops.download(filters_to_use)
Downloading a specific product type (eg. lightcurves) for a given visit
from dace_query.cheops import Cheops
filters_to_use = {'file_key': {'contains': ['CH_PR300001_TG000301_V0000']}}
Cheops.download(filters=filters, file_type='lightcurves')
download_diagnostic_movie(file_key, aperture='default', output_directory=None, output_filename=None)#

Deprecated since version 2.0.0: This method is deprecated and will be removed in a future version. Use download() with file_type='mp4' instead.

Download diagnostic movie for a Cheops file_key.

Aperture types available are : 'default', 'optimal', 'rinf' and 'rsup'

Parameters:

  • file_key (str) – The cheops visit file key

  • aperture (Optional[str]) – Apertures types

  • output_directory (Optional[str]) – The directory where files will be saved

  • output_filename (Optional[str]) – The filename for the download

Return type:

None

Returns:

None

(Outdated) Downloading diagnostic movies using file keys
from dace_query.cheops import Cheops
Cheops.download_diagnostic_movie(file_key='CH_PR100018_TG027204_V0200', output_directory='/tmp', output_filename='cheops_movie.mp4')
get_lightcurve(target, aperture='default', filters=None, sort=None, output_format=None)#

Get the photometry data (from Cheops) in the chosen format for a specified target.

Aperture types available are : 'default', 'optimal', 'rinf' and 'rsup'

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

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

Parameters:

  • target (str) – The target to retrieve light curve from

  • aperture (Optional[str]) – Aperture type

  • filters (Optional[dict]) – Filters to apply to the query

  • sort (Optional[dict]) – Sort order to apply to the query

  • output_format (Optional[str]) – The desired data in the chosen output format

Returns:

The desired data in the chosen format

Return type:

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

Getting all available photometry data for a specific target
from dace_query.cheops import Cheops
values = Cheops.get_lightcurve('WASP-8')
list_data_product(visit_filepath, output_format=None)#

Deprecated since version 2.0.0: This method is no longer supported and will be removed in a future version. Use browse_products() with filters instead:

filters: dict = {'target_name': {'contains': 'TOI178'}}
browse_products(filters=filters)

List the filenames of all available data products for the specified visit filepath.

Parameters:

  • visit_filepath (str) – The cheops visit filepath

  • 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

(Outdated) Listing data products using visit file paths
from dace_query.cheops import Cheops
values = Cheops.list_data_product(visit_filepath='cheops/outtray/PR10/PR100018_TG027204_V0200/CH_PR100018_TG027204_TU2020-12-04T04-42-41_SCI_RAW_SubArray_V0200.fits')
query_catalog(catalog, limit=10000, filters=None, sort=None, output_format=None)#

Query the cheops, either stellar or planet, catalogs.

Available catalogs are [ ‘planet’, ‘stellar’ ].

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

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

Parameters:

  • catalog (str) – The catalog name

  • 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

Getting the planet catalog
from dace_query.cheops import Cheops
catalog_to_search = 'planet'
values = Cheops.query_catalog(catalog_to_search)
query_database(limit=10000, filters=None, sort=None, output_format=None)#

Query the cheops database to retrieve available visits in the chosen format.

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

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

List all available CHEOPS visits
from dace_query.cheops import Cheops
values = Cheops.query_database()
query_region(sky_coord, angle, limit=10000, filters=None, output_format=None)#

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

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

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

Finding visits using a cone search
from dace_query.cheops import Cheops
from astropy.coordinates import SkyCoord, Angle
sky_coord, angle = SkyCoord("22h23m29s", "+32d27m34s", frame='icrs'), Angle('0.045d')
values = Cheops.query_region(sky_coord=sky_coord, angle=angle)