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 ---------- 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}. 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:: location :type: astropy.coordinates.EarthLocation .. py:attribute:: pixel_scales :type: dict[str, float] .. 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_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_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:: 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(location=EarthLocation.from_geodetic(lon=-115.463611 * u.deg, lat=31.044167 * u.deg, height=2790 * u.m), pixel_scales={'1': 0.1397, '2': 0.1406, '3': 0.1661}, dateobs_kw='UT', exptime_kw='EXPOSURE') Bases: :py:obj:`Instrument` OAN-SPM OPTICAM-MX instrument. .. 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:class:: OPTICAM_MX_UNKNOWN Bases: :py:obj:`OPTICAM_MX` OAN-SPM OPTICAM-MX instrument. .. py:class:: MEXMAN(location = EarthLocation.from_geodetic(lon=-115.463611 * u.deg, lat=31.044167 * u.deg, height=2790 * u.m), pixel_scales = {'MEXMAN': 0.24645}, dateobs_kw = 'JD', binning_kw = 'CCDSUM') 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.