opticam.instruments =================== .. py:module:: opticam.instruments Classes ------- .. autoapisummary:: opticam.instruments.Instrument opticam.instruments.OPTICAM_MX opticam.instruments.OPTICAM_MX_UNKNOWN opticam.instruments.MEXMAN Functions --------- .. autoapisummary:: opticam.instruments.generate_instrument_json_template opticam.instruments.create_template Module Contents --------------- .. py:class:: Instrument Bases: :py:obj:`abc.ABC` Base class for instruments. Parameters ---------- diameter : Quantity The diameter of the telescope. location : EarthLocation The location of the observatory as an `astropy.coordinates.EarthLocation` object. pixel_scales : dict[str, float] The pixel scales for each camera in arcsec/pixel {camera: pixel scale}. airmass_kw : str, optional The airmass keyword, by default "AIRMASS" binning_kw : str, optional The binning keyword, by default "BINNING". camera_kw : str, optional The keyword that uniquely identifies the camera that took the image, by default "INSTRUME". For single-camera instruments, this keyword doesn't matter. For multi-camera instruments, however, it is used to apply calibrations like flats correctly. dark_curr_kw : str, optional The dark current keyword, by default "DARKCURR". Dark current values are assumed to be in electrons/pixel. dateobs_kw : str, optional The observation date keyword, by default "DATE-OBS". By default, observation dates are assumed to be in ISO 8601/FITS format (YYYY-MM-DDTHH:MM:SS[.sss]). dec_kw : str, optional The DEC keyword, by default "DEC". DEC values are assumed to be in units of degrees. exptime_kw : str, optional The exposure time keyword, by default "EXPTIME". Exposure times are assumed to be in units of seconds. filter_kw : str, optional The filter keyword, by default "FILTER". gain_kw : str, optional The gain keyword, by default "GAIN". Gain values are assumed to be in units of electrons/ADU. ra_kw : str, optional The RA keyword, by default "RA". RA values are assumed to be in units of hour angle. read_noise_kw : str, optional The read noise keyword, by default "RDNOISE". .. py:attribute:: diameter :type: astropy.units.Quantity .. py:attribute:: location :type: astropy.coordinates.EarthLocation .. py:attribute:: pixel_scales :type: dict[str, float] .. py:attribute:: airmass_kw :type: str :value: 'AIRMASS' .. py:attribute:: binning_kw :type: str :value: 'BINNING' .. py:attribute:: camera_kw :type: str :value: 'INSTRUME' .. py:attribute:: dark_curr_kw :type: str :value: 'DARKCURR' .. py:attribute:: dateobs_kw :type: str :value: 'DATE-OBS' .. py:attribute:: dec_kw :type: str :value: 'DEC' .. py:attribute:: exptime_kw :type: str :value: 'EXPTIME' .. py:attribute:: filter_kw :type: str :value: 'FILTER' .. py:attribute:: gain_kw :type: str :value: 'GAIN' .. py:attribute:: ra_kw :type: str :value: 'RA' .. py:attribute:: read_noise_kw :type: str :value: 'RDNOISE' .. py:method:: run_checks(file, return_errors = False) Check that the instrument can be used to parse an image's header. Parameters ---------- file : MEFSlice | Path The file to use for checking the instrument. If a `Path` or `str` instance is specified, the first HDU of the corresponding FITS file is used. return_errors : bool, optional Whether to return the number of errors raised, by default `False`. Returns ------- None | int If `return_errors=True`, returns the number of errors raised. Otherwise, nothing is returned. Raises ------ ValueError If the header of the file could not be read. .. py:method:: get_mjd(file = None, header = None) Given the path to a FITS file, or its header, parse its observation date into *local* Modified Julian Date (MJD). Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The local MJD of the image. .. py:method:: get_camera(file = None, header = None) Given the path to a FITS file, get the corresponding camera. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str A unique identifier for the camera. .. py:method:: get_sky_coord(file = None, header = None) Given the path to a FITS file, get the corresponding sky coordinates. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- SkyCoord The sky coordinates of the image. .. py:method:: get_dark_flux(file = None, header = None) Given the path to a FITS file, get the corresponding dark flux (i.e., the exposure-integrated dark current). If the instrument does not list a dark current in the image headers, the returned dark flux can be `None`. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float | None The dark flux in the image. .. py:method:: get_airmass(file = None, header = None) Get the airmass of an image using the instrument's `airmass_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The airmass of the image. .. py:method:: get_gain(file = None, header = None) Get the gain of an image using the instrument's `gain_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The gain of the image. .. py:method:: get_binning(file = None, header = None) Get the binning of an image using the instrument's `binning_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str The binning of the image. .. py:method:: get_exptime(file = None, header = None) Get the exposure time of an image using the instrument's `exptime_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str The exposure time of the image. .. py:method:: get_filter(file = None, header = None) Get the filter of an image using the instrument's `filter_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str The filter of the image. .. py:method:: get_read_noise(file = None, header = None) Get the read noise in an image, in electrons per pixel, using the instrument's `read_noise_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The read noise in the image. .. py:method:: get_relative_scintillation_noise(file = None, header = None, C = 1.5, H = 8000 * u.m) Get the scintillation noise in an image using the approximation of Young 1967 (https://ui.adsabs.harvard.edu/abs/1967AJ.....72..747Y/abstract) as refined by Osborn+2015 (https://ui.adsabs.harvard.edu/abs/2015MNRAS.452.1707O/abstract). See Osborn+2015 for details on implementing a more rigorous scintillation noise treatment for your particular instrument. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. C : float, optional The empirical correction coefficient, by default 1.5 (see, e.g., Table 1 of Osborn+2015). H : Quantity, optional The scale-height of the atmosphere, by default 8000 m (e.g., Young 1967). Returns ------- float The relative scintillation noise. .. py:method:: from_json(file_path = None, config = None) :classmethod: Create an instrument from a configuration file/dictionary. Parameters ---------- file_path : Path | str | None, optional The path to the configuration file, by default `None`. If `None`, a dictionary must be passed to `config`. If a value is passed to `file_path`, `config` is ignored. config : dict[str, Any] | None, optional The configuration dictionary, by default `None`. If `None`, a path must be passed to `file_path`. If a value is passed to `file_path`, `config` is ignored. Returns ------- Instrument The configured instrument. Raises ------ AssertionError If required keys are missing from the configuration file/dictionary. .. py:method:: to_json(file_path) Export the instrument configuration to a JSON file. Parameters ---------- file_path : Path | str The location to which the file is written. If `save_path` does not include the file name, the file will be saved as `instrument_config.json`. .. py:function:: generate_instrument_json_template(out_directory) Generate a template JSON file that can be used to define an `Instrument`. Parameters ---------- out_directory : Path | str The path to the directory to which the template is saved. .. py:function:: create_template() Create an instrument configuration template. Returns ------- dict[str, Any] The instrument configuration template. .. py:class:: OPTICAM_MX Bases: :py:obj:`Instrument` OAN-SPM OPTICAM-MX instrument. .. py:method:: get_airmass(file = None, header = None) OPTICAM headers contain a fixed airmass. Here, we estimate the time-dependent airmass. If the airmass cannot be estimate (e.g., due to missing coordinate info), the airmass is set to 0. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The airmass of the image. .. py:method:: get_mjd(file = None, header = None) Get the timestamp of the image in MJD. OPTICAM uses a "UT" keyword to represent an image's timestamp in ISO format. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The timestamp of the image in MJD format. .. py:method:: get_camera(file = None, header = None) Given the path to a FITS file, get the corresponding camera. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str A unique identifier for the camera. .. py:method:: get_read_noise(file = None, header = None) Get the read noise in an image, in electrons per pixel, using the instrument's `read_noise_kw` attribute. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The read noise in the image. .. py:method:: get_relative_scintillation_noise(file = None, header = None, C = 1.67, H = 8000 * u.m) Get the scintillation noise in an image using the approximation of Young 1967 (https://ui.adsabs.harvard.edu/abs/1967AJ.....72..747Y/abstract) as refined by Osborn+2015 (https://ui.adsabs.harvard.edu/abs/2015MNRAS.452.1707O/abstract). See Osborn+2015 for details on implementing a more rigorous scintillation noise treatment. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. C : float, optional The empirical correction coefficient. At OAN-SPM, this value was found to be 1.67 (Osborn+2015). H : Quantity, optional The scale-height of the atmosphere, by default 8000 m (e.g., Young 1967). Returns ------- float The relative scintillation noise. .. py:class:: OPTICAM_MX_UNKNOWN Bases: :py:obj:`OPTICAM_MX` OAN-SPM OPTICAM-MX instrument. .. py:class:: MEXMAN Bases: :py:obj:`Instrument` OAN-SPM MEXMAN instrument. .. py:method:: get_camera(file = None, header = None) Get the camera used to create the file. Since MEXMAN is a single-camera instrument, the name of the instrument is returned. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- str The camera used to create the file. .. py:method:: get_mjd(file = None, header = None) Get the timestamp of the image in MJD. MEXMAN uses a "JD" keyword to represent an image's timestamp in Julian Date format. Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. Returns ------- float The timestamp of the image in MJD format. .. py:method:: get_relative_scintillation_noise(file = None, header = None, C = 1.67, H = 8000 * u.m) Get the relative scintillation noise in an image using the approximation of Young 1967 (https://ui.adsabs.harvard.edu/abs/1967AJ.....72..747Y/abstract) as refined by Osborn+2015 (https://ui.adsabs.harvard.edu/abs/2015MNRAS.452.1707O/abstract). Parameters ---------- file : MEFSlice | None, optional The `MEFSlice` instance corresponding to the file, by default `None`. If `None`, a `Header` must be passed to `header` instead. header : Header, optional The header of the FITS file, by default `None`. If `None`, a `MEFSlice` must be passed to `file` instead. C : float, optional The empirical correction coefficient. At OAN-SPM, this value was found to be 1.67 (Osborn+2015). H : Quantity, optional The scale-height of the atmosphere, by default 8000 m (e.g., Young 1967). Returns ------- float The relative scintillation noise.