API#

class lksearch.Conf[source]#

Configuration parameters for search.

Refer to astropy.config.ConfigNamespace for API details.

Refer to Astropy documentation for usage.

The attributes listed below are the available configuration parameters.

Parameters:

search_result_display_extra_columns – List of extra columns to be included when displaying a SearchResult object.
cache_dir – Default cache directory for data files downloaded, etc. Defaults to ~/.lksearch/cache if not specified.
CLOUD_ONLY – If False (default), will download a file whether the source is the cloud or MAST archives. If True, will only download/return uris for data located in the cloud (Amazon S3).
PREFER_CLOUD – Use Cloud-based data product retrieval where available (primarily Amazon S3 buckets for MAST holdings)
DOWNLOAD_CLOUD – Download cloud based data. If False, download() will return a pointer to the cloud based data instead of downloading it - intended usage for cloud-based science platforms (e.g. TIKE)
CHECK_CACHED_FILE_SIZES – Toggles whether to send requests to check whether the size of files in the local cache match the expected online file.

CHECK_CACHED_FILE_SIZES#: Whether to send requests to check the size of files in the cache match the expected online file.If False, lksearch will assume files within the cache are complete and will not check their file size.Setting to True will create a modest speed up to retrieving paths for cached files, but will be lest robust, and return an ‘UNKNOWN’ status message

CLOUD_ONLY#: Only Download cloud based data.If False, will download all dataIf True, will only download data located on a cloud (Amazon S3) bucket

DOWNLOAD_CLOUD#: Download cloud based data.If False, download() will return a pointer to the cloud based datainstead of downloading it - intended usage for cloud-based science platforms (e.g. TIKE)

PREFER_CLOUD#: Prefer Cloud-based data product retrieval where available

cache_dir#: Default cache directory for data files downloaded, etc.

search_result_display_extra_columns#: List of extra columns to be included when displaying a SearchResult object.

Generic Search Class for data exploration that queries mast for observations performed by the: Kepler, K2, TESS Missions, and returns the results in a convenient table with options to download. By default only mission products are returned.

Parameters:

target (Optional[Union[str, tuple[float], SkyCoord]] = None) – The target to search for observations of. Can be provided as a name (string), coordinates in decimal degrees (tuple), or astropy SkyCoord Object.
obs_table (Optional[pd.DataFrame] = None) – Optionally, can provice a Astropy Table Object from AstroQuery query_criteria which will be used to construct the observations table
prod_table (Optional[pd.DataFrame] = None) – Optionally, if you provide an obs_table, you may also provide a products table of assosciated products. These two tables will be concatenated to become the primary joint table of data products.
table (Optional[pd.DataFrame] = None) – Optionally, may provide an stropy Table Object that is the already merged joint table of obs_table and prod_table.
search_radius (Optional[Union[float,u.Quantity]] = None) – The radius around the target name/location to search for observations. Can be provided in arcsonds (float) or as an AstroPy Quantity Object
exptime (Optional[Union[str, int, tuple]] = (0,9999)) – Exposure time to filter observation results on. Can be provided as a mission-specific string, an int which forces an exact match to the time in seconds, or a tuple, which provides a range to filter on.
mission (Optional[Union[str, list[str]]] = ["Kepler", "K2", "TESS"]) – Mission(s) for which to search for data on
pipeline (Optional[Union[str, list[str]]] = ["Kepler", "K2", "SPOC"]) – Pipeline(s) which have produced the observed data
sequence (Optional[Union[int, list[int]]] = None,) – Mission Specific Survey value that corresponds to Sector (TESS) AND Campaign (K2). Not valid for Kepler. Setting sequence is not recommented for MASTSearch.

property cloud_uri#: Returns the cloud uris for products in self.table. :returns: an array where each element is the cloud-URI of a product in self.table :rtype: ~numpy.array of URI’s from ~astroquery.mast

property cubedata#: return a MASTSearch object with self.table only containing products that are image cubes

property dec#: Declination coordinate for each data product found.

download(cloud: bool = True, cache: bool = True, cloud_only: bool = False, download_dir: str = '/home/runner/.lksearch/cache', remove_incomplete: str = True) → DataFrame[source]#

downloads products in self.table to the local hard-drive

Parameters:

cloud (bool, optional) – enable cloud (as opposed to MAST) downloading, by default True
cloud_only (bool, optional) – download only products availaible in the cloud, by default False
download_dir (str, optional) – directory where the products should be downloaded to, by default default_download_dir cache : bool, optional
download_products (passed to) – if False, will overwrite the file to be downloaded (for example to replace a corrrupted file)
True (by default) – if False, will overwrite the file to be downloaded (for example to replace a corrrupted file)
remove_incomplete (str, optional) – remove files with a status not “COMPLETE” in the manifest, by default True

Returns:

table where each row is an ~astroquery.mast.Observations.download_products() manifest

Return type:

DataFrame

property dvreports#: return a MASTSearch object with self.table only containing products that are data validation pdf files

property exptime#: Exposure times for all returned products

Filter the search by keywords

Parameters:

target_name (str, optional) – Name of targets. A list will look for multiple target names.
pipeline (str or list[str]], optional) – Data pipeline. A list will look for multiple pipelines.
mission (str or list[str]], optional) – Mission. A list will look for muliple missions.
exptime (int or float, tuple[float]], optional) – Exposure Time. A tuple will look for a range of times.
distance (float or tuple[float]], optional) – Distance. A float searches for products with a distance less than the value given, a tuple will search between the given values.
year (int or list[int], tuple[int]], optional) – Year. A list will look for multiple years, a tuple will look in the range of years.
description (str or list[str]], optional) – Description of product. A list will look for descriptions containing any keywords given, a tuple will look for descriptions containing all the keywords.
filetype (str or list[str]], optional) – Type of product. A list will look for multiple filetypes.
sequence (int or list[int]], optional) – Sequence number refers to “quarter” for Kepler, “campaign” for K2, and “sector” for TESS.
limit (int, optional) – _description_, by default None
inplace (bool, optional) – _description_, by default False

Returns:

Returns a filtered MASTSearch object or None if inplace=True

Return type:

MASTSearch or None

property mission#: Kepler quarter or TESS sector names for each data product found.

property pipeline#: Pipeline name for each data product found.

query_table(criteria: str, inplace: bool = False)[source]#

Filter the Search Result table using pandas query https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.query.html

Parameters:

criteria (str) – string containing criteria to filter table. Can handle multiple criteria, e.g. “exptime>=100 and exptime<=500”.
inplace (bool) – if True, modify table in MASTSearch object directly. If False, returns a new MASTSearch object with the resulting table

Returns:

MASTSearch – Only returned if inplace = False

Return type:

MASTSearch object

property ra#: Right Ascension coordinate for each data product found.

property target_name#: Target name for each data product found.

property timeseries#: return a MASTSearch object with self.table only containing products that are a time-series measurement

property uris#: Location Information of the products in the table

property year#: Year the observation was made.

Search Class that queries mast for observations performed by the Kepler Mission, and returns the results in a convenient table with options to download. By default both mission products and HLSPs are returned.

Parameters:

target (Optional[Union[str, tuple[float], SkyCoord]] = None) – The target to search for observations of. Can be provided as a name (string), coordinates in decimal degrees (tuple), or Astropy SkyCoord Object.
obs_table (Optional[pd.DataFrame] = None) – Optionally, can provice a Astropy Table Object from AstroQuery astroquery.mast.Observations.query_criteria which will be used to construct the observations table
prod_table (Optional[pd.DataFrame] = None) – Optionally, if you provide an obs_table, you may also provide a products table of assosciated products. These two tables will be concatenated to become the primary joint table of data products.
table (Optional[pd.DataFrame] = None) – Optionally, may provide an stropy Table Object that is the already merged joint table of obs_table and prod_table.
search_radius (Optional[Union[float,u.Quantity]] = None) – The radius around the target name/location to search for observations. Can be provided in arcseconds (float) or as an AstroPy Quantity Object
exptime (Optional[Union[str, int, tuple]] = (0,9999)) – Exposure time to filter observation results on. Can be provided as a mission-specific string, an int which forces an exact match to the time in seconds, or a tuple, which provides a range to filter on.
mission (Optional[Union[str, list[str]]] = ["Kepler", "K2", "TESS"]) – Mission(s) for which to search for data on
pipeline (Optional[Union[str, list[str]]] = ["Kepler", "K2", "SPOC"]) – Pipeline(s) which have produced the observed data
quarter (Optional[Union[int, list[int]]] = None,) – Kepler Observing Quarter(s) for which to search for data.
month (Optional[int] = None,) – Observation month for Kepler

property HLSPs#: return a MASTSearch object with self.table only containing High Level Science Products

Filters the search result table by specified parameters

Parameters:

target_name (str, optional) – Name of targets. A list will look for multiple target names.
pipeline (str or list[str]], optional) – Data pipeline. A list will look for multiple pipelines.
mission (str or list[str]], optional) – Mission. A list will look for muliple missions.
exptime (int or float, tuple[float]], optional) – Exposure Time. A tuple will look for a range of times.
distance (float or tuple[float]], optional) – Distance. A float searches for products with a distance less than the value given, a tuple will search between the given values.
year (int or list[int], tuple[int]], optional) – Year. A list will look for multiple years, a tuple will look in the range of years.
description (str or list[str]], optional) – Description of product. A list will look for descriptions containing any keywords given, a tuple will look for descriptions containing all the keywords.
filetype (str or list[str]], optional) – Type of product. A list will look for multiple filetypes.
quarter (Optional[int], optional) – Kepler observing quarter, by default None
month (Optional[int], optional) – Kepler observing month, by default None
limit (int, optional) – how many rows to return, by default None
inplace (bool, optional) – whether to modify the KeplerSearch inplace, by default False

Return type:

KeplerSearch object with updated table or None if inplace==True

property mission_products#: return a MASTSearch object with self.table only containing Mission Products

Search Class that queries mast for observations performed by the K2 Mission, and returns the results in a convenient table with options to download. By default both mission products and HLSPs are returned.

Parameters:

target (Optional[Union[str, tuple[float], SkyCoord]] = None) – The target to search for observations of. Can be provided as a name (string), coordinates in decimal degrees (tuple), or Astropy SkyCoord Object.
obs_table (Optional[pd.DataFrame] = None) – Optionally, can provice a Astropy Table Object from AstroQuery query_criteria which will be used to construct the observations table
prod_table (Optional[pd.DataFrame] = None) – Optionally, if you provide an obs_table, you may also provide a products table of assosciated products. These two tables will be concatenated to become the primary joint table of data products.
table (Optional[pd.DataFrame] = None) – Optionally, may provide an astropy Table Object that is the already merged joint table of obs_table and prod_table.
search_radius (Optional[Union[float,u.Quantity]] = None) – The radius around the target name/location to search for observations. Can be provided in arcseconds (float) or as an AstroPy Quantity Object
exptime (Optional[Union[str, int, tuple]] = (0,9999)) – Exposure time to filter observation results on. Can be provided as a mission-specific string, an int which forces an exact match to the time in seconds, or a tuple, which provides a range to filter on.
mission (Optional[Union[str, list[str]]] = ["Kepler", "K2", "TESS"]) – Mission(s) for which to search for data on
pipeline (Optional[Union[str, list[str]]] = ["Kepler", "K2", "SPOC"]) – Pipeline(s) which have produced the observed data
campaign (Optional[Union[int, list[int]]] = None,) – K2 Observing Campaign(s) for which to search for data.

property HLSPs#: return a MASTSearch object with self.table only containing High Level Science Products

Filters the search result table by specified parameters

Parameters:

target_name (str, optional) – Name of targets. A list will look for multiple target names.
pipeline (str or list[str]], optional) – Data pipeline. A list will look for multiple pipelines.
mission (str or list[str]], optional) – Mission. A list will look for muliple missions.
exptime (int or float, tuple[float]], optional) – Exposure Time. A tuple will look for a range of times.
distance (float or tuple[float]], optional) – Distance. A float searches for products with a distance less than the value given, a tuple will search between the given values.
year (int or list[int], tuple[int]], optional) – Year. A list will look for multiple years, a tuple will look in the range of years.
description (str or list[str]], optional) – Description of product. A list will look for descriptions containing any keywords given, a tuple will look for descriptions containing all the keywords.
filetype (str or list[str]], optional) – Type of product. A list will look for multiple filetypes.
campaign (Optional[int], optional) – K2 observing campaign, by default None
limit (int, optional) – how many rows to return, by default None
inplace (bool, optional) – whether to modify the KeplerSearch inplace, by default False

Return type:

K2Search object with updated table or None if inplace==True

property mission_products#: return a MASTSearch object with self.table only containing Mission Products

Search Class that queries mast for observations performed by the TESS Mission, and returns the results in a convenient table with options to download. By default mission products and HLSPs are returned.

Parameters:

target (Optional[Union[str, tuple[float], SkyCoord]] = None) – The target to search for observations of. Can be provided as a name (string), coordinates in decimal degrees (tuple), or Astropy SkyCoord Object.
obs_table (Optional[pd.DataFrame] = None) – Optionally, can provice a Astropy Table Object from AstroQuery astroquery.mast.Observations.query_criteria which will be used to construct the observations table
prod_table (Optional[pd.DataFrame] = None) – Optionally, if you provide an obs_table, you may also provide a products table of assosciated products. These two tables will be concatenated to become the primary joint table of data products.
table (Optional[pd.DataFrame] = None) – Optionally, may provide an astropy Table Object that is the already merged joint table of obs_table and prod_table.
search_radius (Optional[Union[float,u.Quantity]] = None) – The radius around the target name/location to search for observations. Can be provided in arcseconds (float) or as an astropy Quantity Object
exptime (Optional[Union[str, int, tuple]] = (0,9999)) – Exposure time to filter observation results on. Can be provided as a mission-specific string, an int which forces an exact match to the time in seconds, or a tuple, which provides a range to filter on.
mission (Optional[Union[str, list[str]]] = ["Kepler", "K2", "TESS"]) – Mission(s) for which to search for data on
pipeline (Optional[Union[str, list[str]]] = ["Kepler", "K2", "SPOC"]) – Pipeline(s) which have produced the observed data
sector (Optional[Union[int, list[int]]] = None,) – TESS Observing Sector(s) for which to search for data.

property HLSPs#: return a MASTSearch object with self.table only containing High Level Science Products

property cubedata#: return a MASTSearch object with self.table only containing products that are image cubes

download(cloud: bool = True, cache: bool = True, cloud_only: bool = False, download_dir: str = '/home/runner/.lksearch/cache', TESScut_size: int | tuple = 10)[source]#

downloads products in self.table to the local hard-drive

Parameters:

cloud (bool, optional) – enable cloud (as opposed to MAST) downloading, by default True
cloud_only (bool, optional) – download only products availaible in the cloud, by default False
download_dir (str, optional) – directory where the products should be downloaded to, by default default_download_dir cache : bool, optional
download_products (passed to) – if False, will overwrite the file to be downloaded (for example to replace a corrrupted file)
True (by default) – if False, will overwrite the file to be downloaded (for example to replace a corrrupted file)
remove_incomplete (str, optional) – remove files with a status not “COMPLETE” in the manifest, by default True
TESScut_size (Union[int, tuple], optional,) – The size of a TESScut FFI cutout in pixels

Returns:

table where each row is an ~astroquery.mast.Observations.download_products() manifest

Return type:

DataFrame

Filters the search result table by specified parameters

Parameters:

target_name (str, optional) – Name of targets. A list will look for multiple target names.
pipeline (str or list[str]], optional) – Data pipeline. A list will look for multiple pipelines.
mission (str or list[str]], optional) – Mission. A list will look for muliple missions.
exptime (int or float, tuple[float]], optional) – Exposure Time. A tuple will look for a range of times.
distance (float or tuple[float]], optional) – Distance. A float searches for products with a distance less than the value given, a tuple will search between the given values.
year (int or list[int], tuple[int]], optional) – Year. A list will look for multiple years, a tuple will look in the range of years.
description (str or list[str]], optional) – Description of product. A list will look for descriptions containing any keywords given, a tuple will look for descriptions containing all the keywords.
filetype (str or list[str]], optional) – Type of product. A list will look for multiple filetypes.
sector (Optional[int], optional) – TESS observing sector, by default None
limit (int, optional) – how many rows to return, by default None
inplace (bool, optional) – whether to modify the KeplerSearch inplace, by default False

Return type:

TESSSearch object with updated table or None if inplace==True

property mission_products#: return a MASTSearch object with self.table only containing Mission Products

search_sector_ffis(sector: int | type[None], **extra_query_criteria)[source]#: DEPRECATED Returns a list of the FFIs available in a particular sector

property tesscut#: return the TESScut only data

Catalog module to search various catalogs for missions

lksearch.catalogsearch.match_names_catalogs(search_input: str | list[str], match: str | list[str])[source]#

Uses the Simbad name resolver and ids to disambiguate the search_input string or list, and compare the disambiguated names with a list to match against.

Parameters:

search_input (Union[str, list[str]]) – A string or list of strings to query simbad for ID disambiguation
match (Union[str, list[str]]) – Short name of catalog to parse the simbad id results for. If this is passed the list of ids are not reported and a column per item in the match list is added and the ids with that match str contained in the id are listed.

Returns:

result – Results from the Simbad ID query in DataFrame format.

Return type:

DataFrame, list[DataFrame]

lksearch.catalogsearch.query_id(search_object: str | int | list[str, int], output_catalog: str = None, input_catalog: str = None, max_results: int = None, return_skycoord: bool = False, output_epoch: str | Time = None)[source]#

Searches a catalog (TIC, KIC, EPIC, or GAIA DR3) for an exact ID match and returns the assosciated catalog rows. A limited cross-match between the TIC, KIC, and gaiadr3 catalogs is possible using the catalog, and input_catalog optional parameters.

Parameters:

search_object (Union[str, int, list[str, int]]) – A string or integer, or list of strings or integers, that represents a list of IDs from a single catalog to match. If an integer is supplied the catalog optional parameter must be specified.
catalog (str, optional) – Catalog to search for an ID match to. If no input_catalog is specified catalog and input_catalog are assumed to be the same. If search_object is a string and catalog and is None, search_object is parsed to try and determine the catalog, by default None
input_catalog (str, optional) – _description_, by default None
max_results (int, optional) – limits the maximum rows to return, by default None
return_skycoord (bool, optional) – If true, an SkyCoord objects is returned for each row in the result table, by default False
output_epoch (Union[str, Time], optional) – If a return_skycoord is True, output_epoch can be used to specify the output_epoch for the returned SkyCoord object, by default None

Returns:

results_table – Table object containing the rows of the catalog with IDs matching the search_input. If return_skycoord is set to True, a SkyCoord object or list of SkyCoord objects is instead returned.

Return type:

Union[Table, SkyCoord, list[SkyCoord]]

lksearch.catalogsearch.query_names(search_input: str | list[str])[source]#

Uses the Simbad name resolver and ids to disambiguate the search_input string or list.

Parameters:: search_input (Union[str, list[str]]) – A string or list of strings to query simbad for ID disambiguation
Returns:: result – Results from the Simbad ID query in DataFrame format.
Return type:: DataFrame, list[DataFrame]

lksearch.catalogsearch.query_region(search_input: str | ~astropy.coordinates.sky_coordinate.SkyCoord | tuple | list[str, ~astropy.coordinates.sky_coordinate.SkyCoord, tuple], output_epoch: str | ~astropy.time.core.Time = None, catalog: str = 'tic', radius: float | ~astropy.units.quantity.Quantity = <Quantity 100. arcsec>, magnitude_limit: float = 18.0, max_results: int = None, return_skycoord: bool = False)[source]#

Query a catalog for a single source location, obtain nearby sources

Parameters:

coord (SkyCoord, string, tuple, or list thereof) – Coordinates around which to do a radius query. If passed a string, will first try to resolve string as a coordinate using SkyCoord, if this fails then tries to resolve the string as a name using resolve_object.
output_epoch (Time) – The time of observation in JD.
catalog (str) – The catalog to query, either ‘kepler’, ‘k2’, or ‘tess’, ‘gaia’
radius (float or Quantity) – Radius in arcseconds to query
magnitude_limit (float) – A value to limit the results in based on the Tmag/Kepler mag/K2 mag or Gaia G mag. Default, 18.
return_skycoord (bool) – Whether to return an SkyCoord object. Default is False.

Returns:

result – By default returns a pandas dataframe of the sources within radius query, corrected for proper motion. Optionally will return astropy.coordinates.SkyCoord object.

Return type:

Table or SkyCoord

class lksearch.config.ConfigItem(defaultvalue='', description=None, cfgtype=None, module=None, aliases=None)[source]#

rootname = 'lksearch'#: Rootname sets the base path for all config files.

class lksearch.config.ConfigNamespace[source]#

lksearch.config.clearcache(test=True)[source]#

Deletes all downloaded files in the lksearch download directory

Parameters:: test (bool, optional) – perform this in test mode, printing what folders will be deleted, by default True. Set test=False to delete cache

lksearch.config.create_config_file(overwrite: bool = False)[source]#: Creates a default configuration file in the config directory

lksearch.config.get_cache_dir()[source]#

Determines the default lksearch cache directory name and creates the directory if it doesn’t exist. If the directory cannot be access or created, then it returns the current directory (".").

This directory is typically $HOME/.lksearch/cache, but if the XDG_CACHE_HOME environment variable is set and the $XDG_CACHE_HOME/lksearch directory exists, it will be that directory. If neither exists, the former will be created and symlinked to the latter.

The value can be also configured via cache_dir configuration parameter.

Returns:

cachedir (str) – The absolute path to the cache directory.
See Conf for more information.

lksearch.config.get_config_dir()[source]#

Determines the package configuration directory name and creates the directory if it doesn’t exist.

This directory is typically $HOME/.lksearch/config, but if the XDG_CONFIG_HOME environment variable is set and the $XDG_CONFIG_HOME/lksearch directory exists, it will be that directory. If neither exists, the former will be created and symlinked to the latter.

Returns:: configdir – The absolute path to the configuration directory.
Return type:: str