API

OASIS Methods

OasisPy.initialize.INITIALIZE()

Sets up the OASIS environment on a new machine. Creates the OASIS file tree and installs Alard’s ISIS program (see documentation for details).

OasisPy.get.GET()

Fetches and prepares data for difference imaging. Two get modes:

  • dl: used to fetch images from the Las Cumbres Observatory (LCO) data archive.
  • unpack: used for non-LCO data. Users acquire images themselves and then call get in unpack mode to prepare the data for difference imaging.
OasisPy.mask.MASK(path)

Masks all cosmic rays, saturated stars, and other defects in the science images. Combines the cosmic ray mask with the image’s initial bad pixel mask (set to NULL if no BPM is found) to make a master mask. Uses the python package astroscrappy (see documentation for details).

Parameters:path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
Returns:All science images are masked. The values of the MASKED keyword in their FITS headers are changed to ‘Y’ if masking is successful.
OasisPy.align.ALIGN(path, align_method='standard')

Registers all science images to their reference image. If no reference image exists, one is chosen (see documentation for details).

Parameters:
  • path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • align_method (default='standard') (str) – Method of alignment. Can be either standard or fakes. Default is standard. The fakes method should be used only for simulations, as it bypasses registration and only performs photometric alignment.
Returns:

Aligns all science images are aligned to the reference image to subpixel precision. A succesful alignment changes an image’s suffix from _U_ to _A_.
OasisPy.psf.PSF(path)

Computes PSF model of science images. Uses PSFex (Bertin).

Parameters:path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
Returns:PSF models of each science image are ouputted into the psf directory with the .psf suffix.
OasisPy.combine.COMBINE(path)

Stacks science images into a high S/N template frame. Stacking method is the weighted median value of each pixel and is done by the AstrOmatic software SWarp (E. Bertin). Only the top third of science images with respect to seeing are included in the template.

Parameters:path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
Returns:Weighted median coaddition of all science images is outputted into the templates directory with the name convention of StackMethod_NumberOfImagesInDataset.fits.
OasisPy.subtract.SUBTRACT(path, method='ois', use_config_file=True)

Performs difference imaging on the science images. The template image is convolved to match the science image’s PSF, then the template is subtracted from the science image. This process is repeated for a number of different parameter configurations until an optimal residual is found. The actual convolution and subtraction is done with either the ISIS package (Alard) or hotpants (Becker). See documentation for details.

Parameters:
  • path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • method (str) –

    Method of difference imaging.

    • ois (default): Optimal Image Subtraction. Christohpe Alard’s ISIS package.
    • hotpants: Andrew Becker’s hotpants program. Very similar to Alard’s OIS, but differs in input parameters. May be useful to try if OIS is returning inadequate results.
  • use_config_file (default=True) (bool) – If True all input parameters are fetched from the local OASIS.config file.
Returns:

All science images are differenced and the corresponding residuals are placed in the residuals directory with the _residual_ suffix.
OasisPy.MR.MR(path, method='swarp', sig_thresh=4, gauss_sig=3, gauss_filt=False, use_config_file=True)

Stacks residual frames into a master residual. Extremely useful for identifying faint variables and quick object detection, but should be used with caution. See documentation for details.

Parameters:
  • path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • method (str) –

    Stacking method.

    • swarp (default): Uses SWarp (Bertin) to stack the residuals according to the weighted average of the pixels.
    • sos: Sum of squares, pixel-wise.
    • sos_abs: Absolute sum of squares, pixel-wise. Preserves sign. Mathematically, this look like \(\Sigma(p_i \cdot |p_i|)\) with \(p_i\) being the \(ith\) pixel. For example, a series of pixels [10, 2, -3, -6] would be stacked according to 100 + 4 + -9 + -36.
    • sigma_clip: Takes the median of each pixel, unless there exists a pixel above or below a certain number of sigmas, in which case this outlying pixel is taken to be the stacked value.
  • sig_thresh (default=4) (float) – Only used for sigma_clip method. Number of sigmas pixel must exceed to be used as stacked value.
  • gauss_sig (default=3) (float) – Only used for sigma_clip method. Number of sigmas used for gaussian filter.
  • gauss_filt (default=False) (bool) – Only used for sigma_clip method. When True the final master residual will be smoothed with a gaussian filter with a sigma equal to gauss_sig.
  • use_config_file (default=True) (bool) – If True all input parameters are fetched from the local OASIS.config file.
Returns:

A stacked master residual frame, located in the residuals directory with the name MR.fits.
OasisPy.extract.EXTRACT(path, method='both')

Extracts sources from individual residual frames located in residuals directory. Automatically filters out false positives and objects not of interest (see documentation for details). Uses SExtractor to create the initial sources catalogs, which are outputted to the sources directory.

Parameters:
  • path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • method (str) –

    Method of source extraction. Tells OASIS whether to extract sources from the individual residuals, the master residual, or both.

    • both (default): Runs SExtractor on both residuals and master residual.
    • indiv: Runs SExtractor only on residuals.
    • MR: Runs SExtractor only on master residual.
Returns:

A filtered source catalog for each image specified with the method parameter is created and appended to the text file filtered_sources.txt located in the sources directory. Source extraction statistics and extra info are located in total_sources.txt.

Convenience Functions

OasisPy.pipeline.PIPELINE(path)

The OASIS Pipeline. Runs all OASIS functions in succession.

Parameters:path (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
Returns:All-in-one difference imaging pipeline. Raw science images are placed in the data directory, and residual images and source catalogs are outputted into the residuals and sources directories, respectively.
OasisPy.run.RUN()

Master run function. Allows user to call any of the main OASIS methods. See documentation for details.

Auxillary Functions

OasisPy.simulation.sim_fakes(location, n_fakes, iterations, input_mode='flux', PSF='moffat', subtract_method='ois', f_min=0, f_max=40000)

Simulates transient signals (fakes) and tests OASIS’s ability to detect them. The procedure of the simulation is as follows:

  1. Makes a copy of the specified data set and moves it to the simulations directory.
  2. Chooses a random image out of the data set and adds in fakes.
  3. Runs the data set through the OASIS Pipeline.
  4. Outputs a catalog of all fakes and whether or not they were detected.
  5. Simulation is repeated with a different set of fakes.
Parameters:
  • location (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • n_fakes (default=20) (int) – Number of fakes added to the chosen image.
  • iterations (default=50) (int) – Number of iterations the simulation goes through. The total number of fakes added is then \(n\_fakes \cdot iterations\). It is reccommended to choose n_fakes and iterations such that the total number of fakes is high, at least a few hundred, ideally more than 1000.
  • input_mode (str) –

    How to interpret fake’s flux parameter.

    • flux (default): Fake’s brightness is assumed to be total flux of the fake in ADU and is determined by f_min and f_max parameters.
    • mag: Fake’s brightness is given in magnitudes instead of ADU flux. f_min and f_max are then assumed to be apparent magnitudes rather than ADU counts.
  • PSF (str) –

    Type of PSF model used for fake construction. See documentation for details.

    • moffat (default): Fakes are convolved with a 2D Moffat kernel.
    • gaussian: Fakes are convolved with a symmetric 2D Gaussian kernel.
  • subtract_method (default='ois') (str) – Subtraction method used, can be either ois or hotpants, default is ois. See subtract method’s documentation for details.
  • f_min (default=0) (float) – Minimum flux for fakes. Assumed to either be given in ADU counts or apparent magnitudes depending on input_mode.
  • f_max (default=40000) (float) – Maximum flux for fakes. Assumed to either be given in ADU counts or apparent magnitudes depending on input_mode.
Returns:

Catalog of all fakes, the image they were added to, iteration, and whether or not they were detected. See documentation for details.
OasisPy.simulation.sim_sameField(location, numIms=100, bkg_mag=22.5, fwhm_min=3, fwhm_max=6, rot_min=-2.5, rot_max=2.5, shift_min=-2, shift_max=2, scale_mult=(0, 1.5), scale_add=(-20, 50), zero_point=25, mode='gauss')

Test OASIS’s ability to handle frame-by-frame variations in astronomical data and filter out false-positive sources. The procedure of the simulation is as follows:

  1. Copies a random science image from the specified dataset to the simulations directory.
  2. A source catalog of the chosen science image is made, containing information on each source’s centroid location and total flux.
  3. Using this source catalog, simulations of the chosen science image are made, all with constant source flux and location, but with different backgrounds, seeing, and pointing.
  4. The set of simulated images are sent through the OASIS Pipeline.
  5. Low numbers of detected sources signifies a successful simulation. There are no variable objects in the simulated images, so ideally zero sources should be detected by OASIS.
Parameters:
  • location (str) – Path of data file tree (contains the configs, data, psf, residuals, sources, templates directories). Use a comma-separated list for mapping to multiple datasets.
  • mode (default='moffat') (str) –

    Simulation mode. Method by which simulated images are made. All images are given a uniform background, then smeared according to Poisson statistics.

    • moffat (default): Sources are convolved with a 2D Moffat kernel.
    • gauss: Sources are convolved with a symmetric 2D Gaussian kernel.
    • real: The actual PSF model of the chosen science image is used as the convolution kernel.
    • sky: AstrOmatic program SkyMaker (Bertin) is used to make simulated images.
  • numIms (default=100) (int) – Number of simulated images to make.
  • bkg_mag (default=22.5) (float) – Average background level in mags. Actual simulated background levels are chosen to be a random value within the interval \([bkg\_mag-1.5, bkg\_mag+1.5]\).
  • fwhm_min (default=3) (float) – Minimum FWHM of simulated images in pixels.
  • fwhm_max (default=6) (float) – Maximum FWHM of simulated images in pixels.
  • rot_min (default=-2.5) (float) – Lower bound on angle of rotation in degrees.
  • rot_max (default=2.5) (float) – Upper bound on angle of rotation in degrees.
  • shift_min (default=-2) (float) – Lower bound on (X,Y) shift in pixels.
  • shift_max (default=2) (float) – Upper bound on (X,Y) shift in pixels.
  • scale_mult (default=(0,1.5)) (tuple) – Interval of acceptable multiplicative scale factors.
  • scale_add (default=(-20,50)) (tuple) – Interval of acceptable additive scale factors.
  • zero_point (default=25) (float) – Zero point magnitude.
Returns:

Standard OASIS Pipeline output, residual frames located in residuals and source catalogs located in sources.
OasisPy.simulation.SIM()

Master simulation function. Allows users to choose simulation type and supply all other simulation parameters.

OasisPy.test.TEST()

Tests the installation of OasisPy by downloading a set of images from an online public archive, adding fake sources to one of the images, and running the dataset through the OASIS Pipeline. If the fake sources are recovered, the test is a success. The images used are 118 second exposures of exoplanet HAT-P-37b taken with telescopes at the Las Cumbres Observatory. Results of the test are compared to control results located in OasisPy’s source code directory.

Returns:Prints either ‘TEST SUCCESSFUL!’ or ‘Test failure: Results do not match controls’.
OasisPy.montage.MOSAIC()

Interfaces with MontagePy to build a mosaic from a set of input images. All parameters are supplied through terminal prompts. See documentation for details.