Detections

Functions and interfaces to compute contrast curves and contrast grids.

Contrast

The contrast module is the main interface to compute contrast curves with applefy. For an example on how to use this module see the user documentation

class applefy.detections.contrast.Contrast(science_sequence, psf_template, psf_fwhm_radius, parang_rad, dit_science, dit_psf_template, scaling_factor=1, checkpoint_dir=None)

Bases: object

The Contrast class is the main interface to compute contrast curves with applefy. It allows to compute contrast grids as well as classical analytical contrast curves. For an example on how to use this class see the user documentation

__init__(science_sequence, psf_template, psf_fwhm_radius, parang_rad, dit_science, dit_psf_template, scaling_factor=1, checkpoint_dir=None)

Constructor of the class. The Contrast class can be used with and without a checkpoint_dir. If a checkpoint_dir is given intermediate results (such as residuals with fake planets) can be restored.

Parameters

• science_sequence (ndarray) – A 3d numpy array of the observation sequence without any fake planets. Dimensions (time, x, y). dim(x) == dim (y). We recommend an add pixel resolution!

• psf_template (ndarray) – A 2d numpy array with the psf-template (usually the unsaturated star). We recommend an add pixel resolution!

• psf_fwhm_radius (float) – The FWHM (radius) of the PSF. It is needed to sample independent noise values i.e. it determines the spacing between the noise observations which are extracted from the residuals.

• parang_rad (ndarray) – A 1d numpy array containing the parallactic angles in radians.

• dit_science (float) – Integration time of the science frames.

• dit_psf_template (float) – Integration time of the psf_template.

• scaling_factor (float) – A scaling factor to account for e.g. ND filters.

• checkpoint_dir (Optional[Union[str, Path]]) –

  A directory in which intermediate results are stored. Within the checkpoint_dir three subdirectories are created:

  1. configs_cgrid: This folder will contain several .json config files which define where to insert fake planets. The config files are created within design_fake_planet_experiments().

  2. residuals: This folder contains the results of the post-processing algorithm used. E.g. PCA residuals. The results are calculated in run_fake_planet_experiments().

  3. scratch: A scratch folder which can be used by the post-processing algorithm to store files.

classmethod create_from_checkpoint_dir(psf_template, psf_fwhm_radius, dit_science, dit_psf_template, checkpoint_dir, scaling_factor=1)

A factory method which can be used to restore a Contrast instance from a checkpoint_dir. This function can be used to load results calculated earlier with run_fake_planet_experiments(). It is further useful to load results of more complex post-processing methods computed on a cluster.

Parameters

• psf_template (ndarray) – A 2d numpy array with the psf-template (usually the unsaturated star).

• psf_fwhm_radius (float) – The FWHM (radius) of the PSF. It is needed to sample independent noise values i.e. it determines the spacing between the noise observations which are extracted from the residuals.

• dit_science (float) – Integration time of the science frames.

• dit_psf_template (float) – Integration time of the psf_template.

• checkpoint_dir (Union[str, Path]) –

  The directory in which intermediate results are stored. It has to contain three subdirectories:

  1. configs_cgrid: This folder contains several .json config files which define where fake planets have been inserted.

  2. residuals: This folder contains the results of the post-processing algorithm used. E.g. PCA residuals.

  3. scratch: A scratch folder which can be used by the post-processing algorithm to store files.

• scaling_factor (float) – A scaling factor to account for e.g. ND filters.

Return type

Contrast

Returns

An instance of Contrast ready to run prepare_contrast_results() compute_analytic_contrast_curves() and compute_contrast_grids().

design_fake_planet_experiments(flux_ratios, num_planets=6, separations=None, overwrite=False)

Calculates the positions at which fake planets are inserted. For each fake planet experiment one .json config file is created (in case a checkpoint_dir is available). This function is the first step to calculate a contrast curve or contrast grid.

Parameters

• flux_ratios (ndarray) – A list / single value of planet-to-star flux_ratios used for the fake planets to be injected. If you want to calculate a simple contrast curve this values should be below the expected detection limit. For the computation of a contrast grid several flux_ratios are needed.

• num_planets (int) – The number of planets to be inserted. Has to be between 1 (minimum) and 6 (maximum). More planets result in more accurate results but also longer computation time.

• separations (Optional[ndarray]) – Separations at which fake planets are inserted [pixel]. By default, (If set to None) separations are selected in steps of 1 FWHM form the central star to the edge of the image.

• overwrite (bool) – Check if config files exist already within the checkpoint_dir. Overwrite allows to overwrite already existing files. The default behaviour will raise an error.

Return type

None

run_fake_planet_experiments(algorithm_function, num_parallel)

Runs the fake planet experiments with the post-processing algorithm given as algorithm_function. Requires that fake planet experiments have been defined with design_fake_planet_experiments() before. For each fake planet experiment the following steps are executed:

1. Insert a fake planet in the observation sequence.

2. Run algorithm_function to get a residual.

3. Save the residual in case a checkpoint_dir is available.

All fake planet experiments are executed with multiprocessing. This function is the second step to calculate a contrast curve or contrast grid.

Parameters

• algorithm_function (DataReductionInterface) – The post-processing method used to calculate the residuals (e.g. PCA). See wrappers for examples.

• num_parallel (int) – The number of parallel fake planet experiments.

Return type

None

prepare_contrast_results(photometry_mode_planet, photometry_mode_noise)

After running run_fake_planet_experiments() this function is used to compute the stellar flux and prepare instances of ContrastResult(). This function is the third step to calculate a contrast curve or contrast grid.

Parameters

• photometry_mode_planet (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the flux is measured at the planet position.

• photometry_mode_noise (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the noise photometry is measured.

Return type

None

compute_analytic_contrast_curves(statistical_test, confidence_level_fpf, num_rot_iter=20, pixel_scale=None)

Computes analytic contrast curves given a confidence level and a statistical test. Analytic contrast curves are only applicable if used with linear post-processing techniques such as PCA. They can further lead to inaccurate results close to the star. For more advanced post-processing techniques use a contrast grid instead.

Requires a previous execution of prepare_contrast_results(). If the post-processing method used in run_fake_planet_experiments() returns multiple residuals (e.g. for different numbers of PCA components) the output contains multiple contrast curves summarized in one pandas table.

Parameters

• statistical_test (TestInterface) – The test used to constrain the planet flux needed to be counted as a detection. For the classical TTest (Gaussian noise) use an instance of TTest(). For Laplacian noise use LaplaceBootstrapTest().

• confidence_level_fpf (float) – The confidence level associated with the contrast curve as false-positive fraction (FPF).

• num_rot_iter (int) – Number of tests performed with different positions of the noise values. See Figure 10 for more information.

• pixel_scale (Optional[float]) – The pixel scale in arcsec. If given the result table will have a multi index.

Return type

Tuple[DataFrame, DataFrame]

Returns

1. A pandas DataFrame with the median contrast curves over all num_rot_iter.

2. A pandas DataFrame with the MAD error of the contrast curves over all num_rot_iter.

compute_contrast_grids(statistical_test, confidence_level_fpf, num_cores=1, safety_margin=1.0, num_rot_iter=20, pixel_scale=None)

Calculates the contrast grids. A contrast grid shows the detection uncertainty as a function of separation from the star and fake planet flux_ratio. It evaluates the fake planet residuals directly.

Requires a previous execution of prepare_contrast_results(). If the post-processing method used in run_fake_planet_experiments() returns multiple residuals (e.g. for different numbers of PCA components) the output contains multiple contrast grids. The results are computed using multiprocessing.

Parameters

• statistical_test (TestInterface) – The test used to constrain the planet flux needed in order to be counted as a detection. For the classical TTest (Gaussian noise) use an instance of TTest(). For Laplacian noise use LaplaceBootstrapTest().

• num_cores (int) – Number of parallel jobs used during multiprocessing.

• confidence_level_fpf (float) – The confidence level associated with the contrast curve as false-positive fraction (FPF). See return values.

• safety_margin (float) – Area around the planet [pixel] which is excluded from the noise. This can be useful in case the planet has negative wings.

• num_rot_iter (int) –

  Number of tests performed with different positions of the noise values. See Figure 10 for more information.

• pixel_scale (Optional[float]) – The pixel scale in arcsec. If given the result table will have a multi index.

Return type

Tuple[DataFrame, Dict[str, DataFrame]]

Returns

1. A pandas DataFrame with the contrast curves obtained by thresholding the contrast grids. We report the median p-values over all num_rot_iter experiments performed.

2. A dict with one contrast grid for each output of the post-processing routine. We report the median p-value over all num_rot_iter experiments performed.

class applefy.detections.contrast.ContrastResult(model_results, stellar_flux, photometry_mode_planet, photometry_mode_noise, psf_fwhm_radius)

Bases: object

Class for the evaluation and organization of residuals from one method (e.g. pca with 10 components). Supports both contrast curves and contrast grids. Usually ContrastResult is used within an instance of Contrast(). But, it can also be used individually.

__init__(model_results, stellar_flux, photometry_mode_planet, photometry_mode_noise, psf_fwhm_radius)

Constructor of the class. This function will sort all residuals.

Parameters

• model_results (List[Tuple[Dict[str, Any], ndarray]]) – List which contains tuples of fake planet config files (as dict) and residuals as created by read_fake_planet_results().

• stellar_flux (float) – The stellar flux measured with estimate_stellar_flux(). The mode used to get the stellar flux has to be the same as used in planet_photometry_mode.

• photometry_mode_planet (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the flux is measured at the planet position.

• photometry_mode_noise (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the noise photometry is measured.

• psf_fwhm_radius (float) – The FWHM (radius) of the PSF. It is needed to sample independent noise values i.e. it determines the spacing between the noise observations which are extracted from the residuals.

compute_throughput()

Computes a throughput table based on all residuals. Uses the function compute_throughput_table().

Return type

DataFrame

Returns

Pandas DataFrame which contains the median throughput as a function of separation and fake planet flux_ratio.

property residuals: ndarray

Combines all residuals from all experiments.

Returns

All residuals from all experiments as one array with dimensions

(separation, fake planet flux ratio, planet index, x, y)

compute_analytic_contrast_curve(statistical_test, confidence_level_fpf, num_rot_iter=100)

Computes an analytic contrast curve given a confidence level and a statistical test. Analytic contrast curves are only applicable if used with linear post-processing techniques such as PCA. They can further lead to inaccurate results close to the star. For more advanced post-processing techniques use a contrast grid instead.

Parameters

• statistical_test (TestInterface) – The test used to constrain the planet flux needed to be counted as a detection. For the classical TTest (Gaussian noise) use an instance of TTest(). For Laplacian noise use LaplaceBootstrapTest().

• confidence_level_fpf (Union[float, List[float]]) – The confidence level associated with the contrast curve as false-positive fraction (FPF). Can also be a list of fpf values (with the length of separations evaluated in the fake planet experiments).

• num_rot_iter (int) –

  Number of tests performed with different positions of the noise values. See Figure 10 for more information.

Return type

Tuple[DataFrame, DataFrame]

Returns

1. A pandas DataFrame with the median contrast curve over all num_rot_iter.

2. A pandas DataFrame with the MAD error of the contrast curve over all num_rot_iter.

compute_contrast_grid(statistical_test, num_cores=1, num_rot_iter=20, safety_margin=1.0, confidence_level_fpf=None)

Calculates the contrast grid . The contrast grid shows the detection uncertainty as a function of separation from the star and fake planet flux_ratio. It evaluates the fake planet residuals directly. Compared to the function compute_analytic_contrast_curve() this function is applicable not only to residuals of linear PSF-subtraction methods like PCA, but in general. This allows to compare results of different methods. The results are computed using multiprocessing.

Parameters

• statistical_test (TestInterface) – The test used to constrain the planet flux needed in order to be counted as a detection. For the classical TTest (Gaussian noise) use an instance of TTest(). For Laplacian noise use LaplaceBootstrapTest().

• num_cores (int) – Number of parallel jobs used during multiprocessing.

• num_rot_iter (int) –

  Number of tests performed with different positions of the noise values. See Figure 10 for more information.

• safety_margin (float) – Area around the planet [pixel] which is excluded from the noise. This can be useful in case the planet has negative wings.

• confidence_level_fpf (Optional[float]) – If set to a float value the output contrast grid will be interpolated in order to obtain a contrast curve. The value is the confidence level associated with the contrast curve as false-positive fraction (FPF). If None only the contrast grid is returned.

Return type

Union[Tuple[DataFrame, DataFrame], DataFrame]

Returns

1. A pandas DataFrame with the contrast grid. We report the median p-value over all num_rot_iter experiments performed.

2. A pandas DataFrame with the contrast curve obtained by thresholding the contrast grid. We report the median p-values over all num_rot_iter experiments performed. Only returned if a confidence_level_fpf is given.

class applefy.detections.contrast.DataReductionInterface

Bases: ABC

Applefy allows to compute contrast curves with different post-processing algorithms. However, it does not come with any implementation of these techniques. Instead, we use existing implementations in packages like PynPoint or VIP. The DataReductionInterface is an interface which guarantees that these external implementations can be used within applefy. See wrappers for examples.

abstract get_method_keys()

The get_method_keys should return the name (or names) of the method implemented. The name(s) should match the keys of the result dict created by __call__.

Return type

List[str]

Returns

A list containing the name(s) of the method. If __call__ computes only a single residual the return value should be a list containing a single string. If __call__ has multiple outputs (e.g. PCA residuals with different number of components) the list should contain one name for each entry in the result dict of __call__.

abstract __call__(stack_with_fake_planet, parang_rad, psf_template, exp_id)

In order to make external post-processing methods compatible with applefy they have to implement the __call__ function. __call__ should run the post-processing algorithm and return its result(s) / residual(s). It is possible to return multiple result (e.g. for different parameters of the post-processing algorithm) as a dict.

Parameters

• stack_with_fake_planet (ndarray) – A 3d numpy array of the observation sequence. Fake plants are inserted by applefy in advance.

• parang_rad (ndarray) – A 1d numpy array containing the parallactic angles in radians.

• psf_template (ndarray) – A 2d numpy array with the psf-template (usually the unsaturated star).

• exp_id (str) – Experiment ID of the config used to add the fake planet. It is a unique string and can be used to store intermediate results. See generate_fake_planet_experiments() for more information about the config files.

Return type

Dict[str, ndarray]

Returns

A dictionary which contains the results / residuals of the post-processing algorithm. Each entry in the dict should give one result, while the key specifies the name of the method used. If e.g. PCA with different number of components is used the dict contains one residual for each number of components. The keys of the dict have to match those specified in get_method_keys().

Detection Uncertainty

Functions which can be used to estimate the uncertainty (p-value) that a potential planet at a given position in a residual is not noise.

applefy.detections.uncertainty.compute_detection_uncertainty(frame, planet_position, statistical_test, psf_fwhm_radius, photometry_mode_planet, photometry_mode_noise, safety_margin=1.0, num_rot_iter=20)

Function to estimate the uncertainty (p-value) that a potential planet at a given position in a residual is not noise. The function supports several tests and accounts for the effect of where the noise is extracted from the residual (see Figure 10)

Parameters

• frame (ndarray) – The residual on which we want to estimate the detection uncertainty.

• planet_position (Union[Tuple[float, float], Tuple[float, float, float, float]]) – The position of where the planet is expected. Can either be a position as (x_pos, y_pos) or (x_pos, y_pos, separation, angle). If photometry_mode_planet is set to a mode that supports search, the area around planet_position is explored to maximize the planet flux.

• statistical_test (TestInterface) – The test used to constrain the planet flux needed to be counted as a detection. For the classical TTest (Gaussian noise) use an instance of TTest(). For Laplacian noise use LaplaceBootstrapTest().

• psf_fwhm_radius (float) – The FWHM (radius) of the PSF. It is needed to sample independent noise values i.e. it determines the spacing between the noise observations which are extracted from the residuals.

• photometry_mode_planet (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the flux is measured at the planet position.

• photometry_mode_noise (AperturePhotometryMode) – An instance of AperturePhotometryMode which defines how the noise photometry is measured.

• num_rot_iter (int) –

  Number of tests performed with different positions of the noise values. See Figure 10 for more information.

• safety_margin (float) – Area around the planet [pixel] which is excluded from the noise. This can be useful in case the planet has negative wings.

Return type

Tuple[float, ndarray, ndarray]

Returns

1. The median of all num_rot_iter confidence level estimates (p-values /fpf).

2. 1D numpy array with all num_rot_iter confidence level estimates (p-values /fpf).

3. 1D numpy array with all num_rot_iter estimates of the test statistic T (SNR).