opticam.reducer =============== .. py:module:: opticam.reducer Classes ------- .. autoapisummary:: opticam.reducer.Reducer Functions --------- .. autoapisummary:: opticam.reducer.set_psf_params opticam.reducer.parse_alignment_results opticam.reducer.write_queued_logs opticam.reducer.save_background opticam.reducer.save_unaligned_files opticam.reducer.get_random_image_for_each_filter opticam.reducer.create_targets_dict opticam.reducer.save_photometry_results opticam.reducer.parse_photometry_results opticam.reducer.save_catalog Module Contents --------------- .. py:class:: Reducer(out_directory, data_directory, aperture_selector = np.median, background = None, barycenter = True, bias_corrector = None, dark_corrector = None, finder = None, flat_corrector = None, instrument = OPTICAM_MX(), number_of_processors = cpu_count() // 2, rebin_factor = 1, remove_cosmic_rays = False, show_plots = True, threshold = 5, verbose = True) Class for reducing astronomical images. .. py:attribute:: verbose :value: True .. py:attribute:: out_directory .. py:attribute:: logger .. py:attribute:: data_directory .. py:attribute:: rebin_factor :value: 1 .. py:attribute:: instrument .. py:attribute:: aperture_selector .. py:attribute:: threshold :value: 5 .. py:attribute:: remove_cosmic_rays :value: False .. py:attribute:: barycenter :value: True .. py:attribute:: number_of_processors .. py:attribute:: show_plots :value: True .. py:attribute:: bias_corrector :value: None .. py:attribute:: dark_corrector :value: None .. py:attribute:: flat_corrector :value: None .. py:attribute:: reference_files .. py:attribute:: transforms .. py:attribute:: unaligned_files :value: [] .. py:attribute:: catalogs :type: dict[str, astropy.table.QTable] .. py:attribute:: psf_params .. py:method:: _log_params() Log the input parameters of a `Reducer` instance to file. Parameters ---------- reducer : Reducer The `Reducer` instance. .. py:method:: create_catalogs(max_catalog_sources = 15, n_alignment_sources = 15, transform_type = 'affine', rotation_limit = None, translation_limit = None, scale_limit = None, overwrite = False) Initialise the source catalogs for each camera. Some aspects of this method are parallelised for speed. Parameters ---------- max_catalog_sources : int, optional The maximum number of sources to include in the catalog, by default 30. Since source IDs are ordered by brightness, the brightest `max_catalog_sources` sources are included in the catalog. n_alignment_sources : int, optional The (maximum) number of sources to use for image alignment, by default 30. If `transform_type='translation'`, `n_alignment_sources` must be >= 1, and the brightest `n_alignment_sources` sources are used for image alignment. If `transform_type='affine'`, `n_alignment_sources` must be >= 3 and represents that *maximum* number of sources that *may* be used for image alignment. transform_type : Literal['affine', 'translation'], optional The type of transform to use for image alignment, by default 'affine'. 'translation' performs simple x, y translations, while 'affine' uses `astroalign.find_transform()`. 'affine' is generally more robust (and is therefore the default) while 'translation' can work with fewer sources. rotation_limit : float, optional The maximum rotation limit (in degrees) for affine transformations, by default `None` (no limit). scale_limit : float, optional The maximum scale limit for affine transformations, by default `None` (no limit). translation_limit : float | int | list[float | int] | None, optional The maximum translation limit for both types of transformations, by default `None` (no limit). Can be a scalar value that applies to both x- and y-translations, or an iterable where the first value defines the x-translation limit and the second value defines the y-translation limit. overwrite : bool, optional Whether to overwrite existing catalogs, by default False. .. py:method:: _align_batch(batch, reference_image_shape, reference_coords, transform_type, rotation_limit, scale_limit, translation_limit, n_alignment_sources) Align a batch of images with respect to some reference coordinates. Parameters ---------- batch: list[MEFSlice] The files. reference_image_shape : tuple[int] The reference image's shape. reference_coords : NDArray The source coordinates in the reference image. transform_type : Literal['affine', 'translation'] The type of transform to use for image alignment. rotation_limit : float | None The maximum rotation limit (in degrees) for image alignment. scale_limit : float | None The maximum scaling limit for image alignment. translation_limit : list[float] | None The maximum translation limit for image alignment. n_alignment_sources : int The (maximum) number of sources to use for image alignment. Returns ------- tuple[NDArray[np.float64], dict[str, list[float]], dict[str, dict[str, float]], list[tuple[str, str]]] The stacked image, transforms, background results, and log messages. .. py:method:: _valid_transform(file, transform, rotation_limit, scale_limit, translation_limit) Find whether a transform is valid given some transform limits. Parameters ---------- file : MEFSlice The path to the file being transformed. transform : SimilarityTransform The transform. rotation_limit : float | None The rotation limit. scale_limit : float | None The scale limit. translation_limit : list[float] | None The translation limit. Returns ------- tuple[bool, None | tuple[str, str]] Whether the transform is valid. If not, a log message is also returned as a tuple: (log level, log string). .. py:method:: plot_background_meshes(save = False) Plot the background mesh over an image from each filter to verify it's appropriately sized. If stacked catalog images exist, those will be used. Otherwise, a random image will be chosen for each filter. Parameters ---------- save : bool, optional Whether to save the plot, by default `False`. .. py:method:: plot_growth_curves(targets = None, save = False) Plot the growth curves for the sources identified in the catalog images. The resulting plots are saved to out_directory/diag/growth_curves as PDF files. Parameters ---------- targets : dict[str, int | list[int]] | None, optional The targets for which growth curves will be created, by default `None` (growth curves are created for all catalog sources). To create growth curves for specific targets, pass a dictionary with keys listing the desired filters and values listing each filter's correpsonding target(s). For example: ``` # plot growth curves for the three brightest sources in each catalog plot_growth_curves( targets = { 'g': [1, 2, 3], 'r': [1, 2, 3], 'i': [1, 2, 3], }, ) ``` save : bool, optional Whether to save the plots, by default `False`. .. py:method:: plot_psfs() Plot the PSFs for the catalog sources. .. py:method:: plot_snrs(save = False) Plot the signal-to-noise ratios for each catalogued source in the reference images. Parameters ---------- save : bool, optional Whether to save the plot, by default `False`. .. py:method:: plot_noise(save = False) Plot the noise characterisation for each reference image. Parameters ---------- save : bool, optional Whether to save the plot, by default 'False'. .. py:method:: create_gifs(keep_frames = True, overwrite = False) Create alignment gifs for each camera. Some aspects of this method are parallelised for speed. The frames are saved in out_directory/diag/*_gif_frames and the GIFs are saved in out_directory/cat. Parameters ---------- keep_frames : bool, optional Whether to save the GIF frames in out_directory/diag, by default True. If False, the frames will be deleted after the GIF is saved. overwrite : bool, optional Whether to overwrite existing GIFs, by default False. .. py:method:: plot_apertures(photometer, targets = None, save = False) Plot the apertures over each source. Parameters ---------- photometer : AperturePhotometer The `AperturePhotometer` instance. If a local background estimator has been defined, this will also be plotted. targets : dict[str, int] | dict[str, list[int]] | dict[str, list[int] | int] | None The targets for which apertures will be plotted, by default `None` (apertures are plotted for all sources). To plot apertures for specific targets, pass a dictionary with keys listing the desired filters and values listing each filter's correpsonding target(s). For example: ``` # plot apertures for the three brightest sources in each filter photometer = opticam.AperturePhotometer() plot_apertures( photometer=photometer, targets = { 'g': [1, 2, 3], 'r': [1, 2, 3], 'i': [1, 2, 3], }, ) ``` save : bool, optional Whether to save the plots, by default `False`. .. py:method:: photometry(photometer, overwrite = False) Perform photometry on the catalogs using the provided photometer. Parameters ---------- photometer : BasePhotometer The photometer. Should be a subclass of `BasePhotometer`, or implement a `compute` method that follows the `BasePhotometer` interface. overwrite : bool, optional Whether to overwrite any existing light curves files computed using the same photometer, by default `False`. .. py:method:: _perform_photometry(file, photometer, cat_coords, key) Perform photometry on a file. Parameters ---------- file : MEFSlice The file. photometer : BasePhotometer The photometer to use. cat_coords : NDArray The coordinates of the sources in the catalog. key : str The camera:filter key. Returns ------- dict[str, list] The photometry results. .. py:method:: update_unaligned_files(files) Add one or more files to the list of unaligned files. Unaligned files are skipped when performing photometry. Parameters ---------- files : MEFSlice | list[MEFSlice] The file or files. .. py:function:: set_psf_params(aperture_selector, catalog) Set the PSF parameters. Parameters ---------- aperture_selector : Callable The aperture selector (e.g., `numpy.median`). catalog : QTable The source catalog. Returns ------- dict[str, float] The PSF parameters. .. py:function:: parse_alignment_results(results, camera_files, transforms, unaligned_files, logger) Parse the alignment results. Parameters ---------- results : tuple The alignment results. camera_files : list[MEFSlice] The files. transforms : dict[Path, list[float]] The image-to-image alignments {file path: transform}. unaligned_files : list[MEFSlice] The files that could not be aligned. logger : Logger The logger. Returns ------- tuple[dict[str, list[float]], list[str], NDArray, dict[str, float], dict[str, float]] The updated transforms, unaligned files, stacked image, median background values and median background RMS values. .. py:function:: write_queued_logs(queued_logs, logger) Write queued logs to file. Parameters ---------- queued_logs : list[tuple[str, str]] The queued logs (level, log). logger : Logger The logger. Raises ------ ValueError If the log level is not recognised. .. py:function:: save_background(out_directory, background, key, bmjds) Save the median background and its RMS to a CSV file. Parameters ---------- out_directory : Path The output directory. background : dict[Path, dict[str, float]] The background values for each file. key : str The camera:filter key. bmjds : dict[Path, float] The BMJD values for each file {file path}. .. py:function:: save_unaligned_files(out_directory, unaligned_files) Save the unaligned files to a text file. Parameters ---------- out_directory : Path The output directory. unaligned_files : list[MEFSlice] The list of unaligned files. .. py:function:: get_random_image_for_each_filter(camera_files, instrument) Choose a random image for each filter from a dictionary. Parameters ---------- camera_files : dict[str, list[Path]] The filters and corresponding files in the data directory {filter: [paths to images]}. instrument : Instrument The instrument. Returns ------- dict[str, NDArray] A dictionary containing a random file for each filter .. py:function:: create_targets_dict(catalogs) Create a dictionary of target IDs for all catalog sources. Parameters ---------- catalogs : dict[str, QTable] The catalogs. Returns ------- dict[str, list[int]] The target IDs for all catalog sources. .. py:function:: save_photometry_results(results, catalogs, barycenter, save_dir, key) Save the photometry results to disk. Parameters ---------- results : tuple[dict] The photometry results. catalogs : dict[str, QTable] The source catalogs. save_dir : Path The save directory path. key : str The camera:filter key. .. py:function:: parse_photometry_results(results) Merge the multiprocessed photometry results into a single dictionary. Parameters ---------- results : tuple[dict[str, list]] The multiprocessed photometry results. Returns ------- dict[str, list[list[float]]] The photometry results in a single dictionary. .. py:function:: save_catalog(catalog, key, out_directory) Save a camera:filter catalog to file using `astropy`'s ECSV format. Parameters ---------- catalog : QTable The catalog for a specific camera:filter combination. key : str The camera:filter key. out_directory : Path The output directory.