diff --git a/pyscope/observatory/__init__.py b/pyscope/observatory/__init__.py index b35554a1..b46b02e4 100644 --- a/pyscope/observatory/__init__.py +++ b/pyscope/observatory/__init__.py @@ -1,3 +1,11 @@ +""" +The `observatory` module provides classes and functions for controlling and automating +observatory hardware and operations. This currently includes support only for the +`Robert L. Mutel Telescope` at the University of Iowa, but is designed to be extensible +to all motorized observatory telescopes in the future. +Operations include managing telescopes, cameras, focuser, filter wheels, domes, and other +devices commonly found in an observatory setup. +""" # isort: skip_file import logging diff --git a/pyscope/observatory/ascom_camera.py b/pyscope/observatory/ascom_camera.py index 15a98cd7..25f6806a 100644 --- a/pyscope/observatory/ascom_camera.py +++ b/pyscope/observatory/ascom_camera.py @@ -11,6 +11,20 @@ class ASCOMCamera(ASCOMDevice, Camera): def __init__(self, identifier, alpaca=False, device_number=0, protocol="http"): + """ + Provides the `ASCOMCamera` class for controlling `ASCOM `_-compatible cameras. + + Parameters + ---------- + identifier : `str` + The device identifier. This can be the ProgID or the device number. + alpaca : `bool`, default : `False`, optional + Whether to use the Alpaca protocol for Alpaca-compatible devices. + device_number : `int`, default : 0, optional + The device number. This is only used if the identifier is a ProgID. + protocol : `str`, default : `http`, optional + The protocol to use for Alpaca-compatible devices. + """ super().__init__( identifier, alpaca=alpaca, @@ -25,6 +39,18 @@ def __init__(self, identifier, alpaca=False, device_number=0, protocol="http"): self._camera_time = True def AbortExposure(self): + """ + Abort the current exposure immediately and return camera to idle. + See `CanAbortExposure` for support and possible reasons to abort. + + Parameters + ---------- + None + + Returns + ------- + None + """ logger.debug(f"ASCOMCamera.AbortExposure() called") self._device.AbortExposure() @@ -59,22 +85,87 @@ def SetImageDataType(self): self._image_data_type = np.uint16 def PulseGuide(self, Direction, Duration): + """ + Moves scope in the given direction for the given interval or time at the rate + given by the :py:meth:`ASCOMTelescope.GuideRateRightAscension` and :py:meth:`ASCOMTelescope.GuideRateDeclination` properties. + + Parameters + ---------- + Direction : `GuideDirections `_ + The direction in which to move the scope. + The corresponding values are as follows: + + * 0 : North or +declination. + * 1 : South or -declination. + * 2 : East or +right ascension. + * 3 : West or -right ascension. + + Duration : `int` + The duration of the guide pulse in milliseconds. + + Returns + ------- + None + + Notes + ----- + Method returns immediately if hardware supports back-to-back guiding e.g. dual-axis moving. + Otherwise returns only after the guide pulse has completed. + """ logger.debug(f"ASCOMCamera.PulseGuide({Direction}, {Duration}) called") self._device.PulseGuide(Direction, Duration) def StartExposure(self, Duration, Light): + """ + Starts an exposure with a given duration and light status. Check `ImageReady` for operation completion. + + Parameters + ---------- + Duration : `float` + The exposure duration in seconds. Can be zero if `Light` is `False`. + + Light : `bool` + Whether the exposure is a light frame (`True`) or a dark frame (`False`). + + Returns + ------- + None + + Notes + ----- + `Duration` can be shorter than `ExposureMin` if used for dark frame or bias exposure. + Bias frame also allows a `Duration` of zero. + """ logger.debug(f"ASCOMCamera.StartExposure({Duration}, {Light}) called") self._last_exposure_duration = Duration self._last_exposure_start_time = str(Time.now()) self._device.StartExposure(Duration, Light) def StopExposure(self): + """ + Stops the current exposure gracefully. + + Parameters + ---------- + None + + Returns + ------- + None + + Notes + ----- + Readout process will initiate if stop is called during an exposure. + Ignored if readout is already in process. + """ logger.debug(f"ASCOMCamera.StopExposure() called") self._device.StopExposure() @property def BayerOffsetX(self): # pragma: no cover """ + The X/column offset of the Bayer filter array matrix. (`int`) + .. warning:: This property is not implemented in the ASCOM Alpaca protocol. """ @@ -84,6 +175,8 @@ def BayerOffsetX(self): # pragma: no cover @property def BayerOffsetY(self): # pragma: no cover """ + The Y/row offset of the Bayer filter array matrix. (`int`) + .. warning:: This property is not implemented in the ASCOM Alpaca protocol. """ @@ -92,6 +185,11 @@ def BayerOffsetY(self): # pragma: no cover @property def BinX(self): + """ + The binning factor in the X/column direction. (`int`) + + Default is 1 after camera connection is established. + """ logger.debug(f"ASCOMCamera.BinX property called") return self._device.BinX @@ -102,6 +200,11 @@ def BinX(self, value): @property def BinY(self): + """ + The binning factor in the Y/row direction. (`int`) + + Default is 1 after camera connection is established. + """ logger.debug(f"ASCOMCamera.BinY property called") return self._device.BinY @@ -112,66 +215,115 @@ def BinY(self, value): @property def CameraState(self): + """ + The current operational state of the camera. (`CameraStates `_) + + Can be interpreted as `int` values in the following logic: + + * 0 : Camera is idle and ready to start an exposure. + * 1 : Camera exposure started but waiting (i.e. shutter, trigger, filter wheel, etc.). + * 2 : Camera exposure in progress. + * 3 : CCD readout in progress. + * 4 : Data downloading to PC. + * 5 : Camera in error condition, cannot continue. + """ logger.debug(f"ASCOMCamera.CameraState property called") return self._device.CameraState @property def CameraXSize(self): + """The width of the CCD chip in unbinned pixels. (`int`)""" logger.debug(f"ASCOMCamera.CameraXSize property called") return self._device.CameraXSize @property def CameraYSize(self): + """The height of the CCD chip in unbinned pixels. (`int`)""" logger.debug(f"ASCOMCamera.CameraYSize property called") return self._device.CameraYSize @property def CameraTime(self): + """Whether the camera supports the CameraTime property. (`bool`)""" logger.debug(f"ASCOMCamera.CameraTime property called") return self._camera_time @property def CanAbortExposure(self): + """ + Whether the camera can abort exposures imminently. (`bool`) + + Aborting is not synonymous with stopping an exposure. + Aborting immediately stops the exposure and discards the data. + Used for urgent situations such as errors or temperature concerns. + See `CanStopExposure` for gracious cancellation of an exposure. + """ logger.debug(f"ASCOMCamera.CanAbortExposure property called") return self._device.CanAbortExposure @property def CanAsymmetricBin(self): + """ + Whether the camera supports asymmetric binning such that + `BinX` != `BinY`. (`bool`) + """ logger.debug(f"ASCOMCamera.CanAsymmetricBin property called") return self._device.CanAsymmetricBin @property def CanFastReadout(self): + """Whether the camera supports fast readout mode. (`bool`)""" logger.debug(f"ASCOMCamera.CanFastReadout property called") return self._device.CanFastReadout @property def CanGetCoolerPower(self): + """Whether the camera's cooler power setting can be read. (`bool`)""" logger.debug(f"ASCOMCamera.CanGetCoolerPower property called") return self._device.CanGetCoolerPower @property def CanPulseGuide(self): + """ + Whether the camera supports pulse guiding, + see `definition `_. (`bool`) + """ logger.debug(f"ASCOMCamera.CanPulseGuide property called") return self._device.CanPulseGuide @property def CanSetCCDTemperature(self): + """ + Whether the camera's CCD temperature can be set. (`bool`) + + A false means either the camera uses an open-loop cooling system or + does not support adjusting the CCD temperature from software. + """ logger.debug(f"ASCOMCamera.CanSetCCDTemperature property called") return self._device.CanSetCCDTemperature @property def CanStopExposure(self): + """ + Whether the camera can stop exposures graciously. (`bool`) + + Stopping is not synonymous with aborting an exposure. + Stopping allows the camera to complete the current exposure cycle, then stop. + Image data up to the point of stopping is typically still available. + See `CanAbortExposure` for instant cancellation of an exposure. + """ logger.debug(f"ASCOMCamera.CanStopExposure property called") return self._device.CanStopExposure @property def CCDTemperature(self): + """The current CCD temperature in degrees Celsius. (`float`)""" logger.debug(f"ASCOMCamera.CCDTemperature property called") return self._device.CCDTemperature @property def CoolerOn(self): + """Whether the camera's cooler is on. (`bool`)""" logger.debug(f"ASCOMCamera.CoolerOn property called") return self._device.CoolerOn @@ -182,31 +334,53 @@ def CoolerOn(self, value): @property def CoolerPower(self): + """The current cooler power level as a percentage. (`float`)""" logger.debug(f"ASCOMCamera.CoolerPower property called") return self._device.CoolerPower @property def ElectronsPerADU(self): + """Gain of the camera in photoelectrons per analog-to-digital-unit. (`float`)""" logger.debug(f"ASCOMCamera.ElectronsPerADU() property called") return self._device.ElectronsPerADU @property def ExposureMax(self): + """The maximum exposure duration supported by `StartExposure` in seconds. (`float`)""" logger.debug(f"ASCOMCamera.ExposureMax property called") return self._device.ExposureMax @property def ExposureMin(self): + """ + The minimum exposure duration supported by `StartExposure` in seconds. (`float`) + + Non-zero number, except for bias frame acquisition, where an exposure < ExposureMin + may be possible. + """ logger.debug(f"ASCOMCamera.ExposureMin property called") return self._device.ExposureMin @property def ExposureResolution(self): + """ + The smallest increment in exposure duration supported by `StartExposure`. (`float`) + + This property could be useful if one wants to implement a 'spin control' interface + for fine-tuning exposure durations. + + Providing a `Duration` to `StartExposure` that is not a multiple of `ExposureResolution` + will choose the closest available value. + + A value of 0.0 indicates no minimum resolution increment, except that imposed by the + floating-point precision of `float` itself. + """ logger.debug(f"ASCOMCamera.ExposureResolution property called") return self._device.ExposureResolution @property def FastReadout(self): + """Whether the camera is in fast readout mode. (`bool`)""" logger.debug(f"ASCOMCamera.FastReadout property called") return self._device.FastReadout @@ -217,11 +391,30 @@ def FastReadout(self, value): @property def FullWellCapacity(self): + """ + The full well capacity of the camera in electrons with the + current camera settings. (`float`) + """ logger.debug(f"ASCOMCamera.FullWellCapacity property called") return self._device.FullWellCapacity @property def Gain(self): + """ + The camera's gain OR index of the selected camera gain description. + See below for more information. (`int`) + + Represents either the camera's gain in photoelectrons per analog-to-digital-unit, + or the 0-index of the selected camera gain description in the `Gains` array. + + Depending on a camera's capabilities, the driver can support none, one, or both + representation modes, but only one mode will be active at a time. + + To determine operational mode, read the `GainMin`, `GainMax`, and `Gains` properties. + + `ReadoutMode` may affect the gain of the camera, so it is recommended to set + driver behavior to ensure no conflictions occur if both `Gain` and `ReadoutMode` are used. + """ logger.debug(f"ASCOMCamera.Gain property called") return self._device.Gain @@ -232,26 +425,44 @@ def Gain(self, value): @property def GainMax(self): + """The maximum gain value supported by the camera. (`int`)""" logger.debug(f"ASCOMCamera.GainMax property called") return self._device.GainMax @property def GainMin(self): + """The minimum gain value supported by the camera. (`int`)""" logger.debug(f"ASCOMCamera.GainMin property called") return self._device.GainMin @property def Gains(self): + """ + 0-indexed array of camera gain descriptions supported by the camera. (`list` of `str`) + + Depending on implementation, the array may contain ISOs, or gain names. + """ logger.debug(f"ASCOMCamera.Gains property called") return self._device.Gains @property def HasShutter(self): + """ + Whether the camera has a mechanical shutter. (`bool`) + + If `False`, i.e. the camera has no mechanical shutter, the `StartExposure` + method will ignore the `Light` parameter. + """ logger.debug(f"ASCOMCamera.HasShutter property called") return self._device.HasShutter @property def HeatSinkTemperature(self): + """ + The current heat sink temperature in degrees Celsius. (`float`) + + The readout is only valid if `CanSetCCDTemperature` is `True`. + """ logger.debug(f"ASCOMCamera.HeatSinkTemperature property called") return self._device.HeatSinkTemperature @@ -304,16 +515,27 @@ def ImageArray(self): @property def ImageReady(self): + """ + Whether the camera has completed an exposure and the image is ready to be downloaded. (`bool`) + + If `False`, the `ImageArray` property will exit with an exception. + """ logger.debug(f"ASCOMCamera.ImageReady property called") return self._device.ImageReady @property def IsPulseGuiding(self): + """Whether the camera is currently pulse guiding. (`bool`)""" logger.debug(f"ASCOMCamera.IsPulseGuiding property called") return self._device.IsPulseGuiding @property def LastExposureDuration(self): + """ + The duration of the last exposure in seconds. (`float`) + + May differ from requested exposure time due to shutter latency, camera timing accuracy, etc. + """ logger.debug(f"ASCOMCamera.LastExposureDuration property called") last_exposure_duration = self._device.LastExposureDuration if last_exposure_duration is None or last_exposure_duration == 0: @@ -323,6 +545,11 @@ def LastExposureDuration(self): @property def LastExposureStartTime(self): + """ + The actual last exposure start time in FITS CCYY-MM-DDThh:mm:ss[.sss...] format. (`str`) + + The date string represents UTC time. + """ logger.debug(f"ASCOMCamera.LastExposureStartTime property called") last_time = self._device.LastExposureStartTime """ This code is needed to handle the case of the ASCOM ZWO driver @@ -346,21 +573,33 @@ def LastInputExposureDuration(self, value): @property def MaxADU(self): + """The maximum ADU value the camera is capable of producing. (`int`)""" logger.debug(f"ASCOMCamera.MaxADU property called") return self._device.MaxADU @property def MaxBinX(self): + """ + The maximum allowed binning factor in the X/column direction. (`int`) + + Value equivalent to `MaxBinY` if `CanAsymmetricBin` is `False`. + """ logger.debug(f"ASCOMCamera.MaxBinX property called") return self._device.MaxBinX @property def MaxBinY(self): + """ + The maximum allowed binning factor in the Y/row direction. (`int`) + + Value equivalent to `MaxBinX` if `CanAsymmetricBin` is `False`. + """ logger.debug(f"ASCOMCamera.MaxBinY property called") return self._device.MaxBinY @property def NumX(self): + """The width of the subframe in binned pixels. (`int`)""" logger.debug(f"ASCOMCamera.NumX property called") return self._device.NumX @@ -371,6 +610,7 @@ def NumX(self, value): @property def NumY(self): + """The height of the subframe in binned pixels. (`int`)""" logger.debug(f"ASCOMCamera.NumY property called") return self._device.NumY @@ -381,6 +621,21 @@ def NumY(self, value): @property def Offset(self): + """ + The camera's offset OR index of the selected camera offset description. + See below for more information. (`int`) + + Represents either the camera's offset, or the 0-index of the selected + camera offset description in the `Offsets` array. + + Depending on a camera's capabilities, the driver can support none, one, or both + representation modes, but only one mode will be active at a time. + + To determine operational mode, read the `OffsetMin`, `OffsetMax`, and `Offsets` properties. + + `ReadoutMode` may affect the gain of the camera, so it is recommended to set + driver behavior to ensure no conflictions occur if both `Gain` and `ReadoutMode` are used. + """ logger.debug(f"ASCOMCamera.Offset property called") return self._device.Offset @@ -391,36 +646,52 @@ def Offset(self, value): @property def OffsetMax(self): + """The maximum offset value supported by the camera. (`int`)""" logger.debug(f"ASCOMCamera.OffsetMax property called") return self._device.OffsetMax @property def OffsetMin(self): + """The minimum offset value supported by the camera. (`int`)""" logger.debug(f"ASCOMCamera.OffsetMin property called") return self._device.OffsetMin @property def Offsets(self): + """The array of camera offset descriptions supported by the camera. (`list` of `str`)""" logger.debug(f"ASCOMCamera.Offsets property called") return self._device.Offsets @property def PercentCompleted(self): + """ + The percentage of completion of the current operation. (`int`) + + As opposed to `CoolerPower`, this is represented as an integer + s.t. 0 <= PercentCompleted <= 100 instead of float. + """ logger.debug(f"ASCOMCamera.PercentCompleted property called") return self._device.PercentCompleted @property def PixelSizeX(self): + """The width of the CCD chip pixels in microns. (`float`)""" logger.debug(f"ASCOMCamera.PixelSizeX property called") return self._device.PixelSizeX @property def PixelSizeY(self): + """The height of the CCD chip pixels in microns. (`float`)""" logger.debug(f"ASCOMCamera.PixelSizeY property called") return self._device.PixelSizeY @property def ReadoutMode(self): + """ + Current readout mode of the camera as an index. (`int`) + + The index corresponds to the `ReadoutModes` array. + """ logger.debug(f"ASCOMCamera.ReadoutMode property called") return self._device.ReadoutMode @@ -431,21 +702,45 @@ def ReadoutMode(self, value): @property def ReadoutModes(self): + """The array of camera readout mode descriptions supported by the camera. (`list` of `str`)""" logger.debug(f"ASCOMCamera.ReadoutModes property called") return self._device.ReadoutModes @property def SensorName(self): + """ + The name of the sensor in the camera. (`str`) + + The name is the manufacturer's data sheet part number. + """ logger.debug(f"ASCOMCamera.SensorName property called") return self._device.SensorName @property def SensorType(self): + """ + The type of color information the camera sensor captures. (`SensorType `_) + + The default representations are as follows: + + * 0 : Monochrome with no Bayer encoding. + * 1 : Color without needing Bayer decoding. + * 2 : RGGB encoded Bayer array. + * 3 : CMYG encoded Bayer array. + * 4 : CMYG2 encoded Bayer array. + * 5 : LRGB Kodak TRUESENSE encoded Bayer array. + """ logger.debug(f"ASCOMCamera.SensorType property called") return self._device.SensorType @property def SetCCDTemperature(self): + """ + The set-target CCD temperature in degrees Celsius. (`float`) + + Contrary to `CCDTemperature`, which is the current CCD temperature, + this property is the target temperature for the cooler to reach. + """ logger.debug(f"ASCOMCamera.SetCCDTemperature property called") return self._device.SetCCDTemperature @@ -456,6 +751,7 @@ def SetCCDTemperature(self, value): @property def StartX(self): + """The set X/column position of the start subframe in binned pixels. (`int`)""" logger.debug(f"ASCOMCamera.StartX property called") return self._device.StartX @@ -466,6 +762,7 @@ def StartX(self, value): @property def StartY(self): + """The set Y/row position of the start subframe in binned pixels. (`int`)""" logger.debug(f"ASCOMCamera.StartY property called") return self._device.StartY @@ -476,6 +773,7 @@ def StartY(self, value): @property def SubExposureDuration(self): + """The duration of the subframe exposure interval in seconds. (`float`)""" logger.debug(f"ASCOMCamera.SubExposureDuration property called") return self._device.SubExposureDuration diff --git a/pyscope/observatory/collect_calibration_set.py b/pyscope/observatory/collect_calibration_set.py index b51eae51..9d9727bf 100644 --- a/pyscope/observatory/collect_calibration_set.py +++ b/pyscope/observatory/collect_calibration_set.py @@ -126,39 +126,39 @@ def collect_calibration_set_cli( Parameters ---------- - observatory : str + observatory : `str` - camera : str, default="ccd" + camera : `str`, default="ccd" - readouts : list, default=[None] + readouts : `list`, default=[`None`] - binnings : list, default=[None] + binnings : `list`, default=[`None`] - repeat : int, default=1 + repeat : `int`, default=1 - dark_exposures : list, default=[] + dark_exposures : `list`, default=[] - filters : list, default=[] + filters : `list`, default=[] - filter_exposures : list, default=[] + filter_exposures : `list`, default=[] - filter_brightness : list, default=None + filter_brightness : `list`, default=`None` - home_telescope : bool, default=False + home_telescope : `bool`, default=`False` - target_counts : int, default=None + target_counts : `int`, default=`None` - check_cooler : bool, default=True + check_cooler : `bool`, default=`True` - tracking : bool, default=True + tracking : `bool`, default=`True` - dither_radius : float, default=0 + dither_radius : `float`, default=0 - save_path : str, default="./temp/" + save_path : `str`, default="./temp/" - new_dir : bool, default=True + new_dir : `bool`, default=`True` - verbose : int, default=0 + verbose : `int`, default=0 """ diff --git a/pyscope/observatory/observatory.py b/pyscope/observatory/observatory.py index 34dd3f96..c4add205 100644 --- a/pyscope/observatory/observatory.py +++ b/pyscope/observatory/observatory.py @@ -1894,13 +1894,13 @@ def dither_mount( Parameters ---------- - radius : float, optional (default = 1) + radius : `float`, optional (default = 1) The radius in arcseconds to dither the telescope. center_pos : `~astropy.coordinates.SkyCoord`, optional The center position to dither around. If None, the current pointing of the mount will be used. - seed : int, optional + seed : `int`, optional The seed to use for the random number generator. If None, the seed will be randomly generated. Returns @@ -1946,54 +1946,54 @@ def repositioning( Parameters ---------- - obj : str or `~astropy.coordinates.SkyCoord`, optional + obj : `str` or `~astropy.coordinates.SkyCoord`, optional The name of the target or a `~astropy.coordinates.SkyCoord` object of the target. If a string, a query will be made to the SIMBAD database to get the coordinates. If a `~astropy.coordinates.SkyCoord` - object, the coordinates will be used directly. If None, the ra and dec parameters must be specified. + object, the coordinates will be used directly. If `None`, the ra and dec parameters must be specified. ra : `~astropy.coordinates.Longitude`-like, optional The ICRS J2000 right ascension of the target that will initialize a `~astropy.coordinates.SkyCoord` object. This will override the ra value in the object parameter. dec : `~astropy.coordinates.Latitude`-like, optional The ICRS J2000 declination of the target that will initialize a `~astropy.coordinates.SkyCoord` object. This will override the dec value in the object parameter. - unit : tuple, optional + unit : `tuple`, optional The units of the ra and dec parameters. Default is ('hr', 'deg'). - frame : str, optional + frame : `str`, optional The coordinate frame of the ra and dec parameters. Default is 'icrs'. - target_x_pixel : float, optional + target_x_pixel : `float`, optional The desired x pixel location of the target. - target_y_pixel : float, optional + target_y_pixel : `float`, optional The desired y pixel location of the target. - initial_offset_dec : float, optional + initial_offset_dec : `float`, optional The initial offset of declination in arcseconds to use for the slew. Default is 0. Ignored if - do_initial_slew is False. - check_and_refine : bool, optional + do_initial_slew is `False`. + check_and_refine : `bool`, optional Whether or not to check the offset and refine the slew. Default is True. - max_attempts : int, optional + max_attempts : `int`, optional The maximum number of attempts to make to center the target. Default is 5. Ignored if check_and_refine is False. - tolerance : float, optional + tolerance : `float`, optional The tolerance in pixels to consider the target centered. Default is 3. Ignored if - check_and_refine is False. - exposure : float, optional + check_and_refine is `False`. + exposure : `float`, optional The exposure time in seconds to use for the centering images. Default is 10. - readout : int, optional + readout : `int`, optional The readout mode to use for the centering images. Default is 0. - save_images : bool, optional - Whether or not to save the centering images. Default is False. - save_path : str, optional + save_images : `bool`, optional + Whether or not to save the centering images. Default is `False`. + save_path : `str`, optional The path to save the centering images to. Default is the current directory. Ignored if - save_images is False. - settle_time : float, optional + save_images is `False`. + settle_time : `float`, optional The time in seconds to wait after the slew before checking the offset. Default is 5. - do_initial_slew : bool, optional - Whether or not to do the initial slew to the target. Default is True. If False, the current + do_initial_slew : `bool`, optional + Whether or not to do the initial slew to the target. Default is `True`. If `False`, the current telescope position will be used as the starting point for the centering routine. Returns ------- - success : bool - True if the target was successfully centered, False otherwise. + success : `bool` + `True` if the target was successfully centered, `False` otherwise. """ """logger.info( f"repositioning called with {obj}, {ra}, {dec}, {unit}, {frame}, {target_x_pixel}, {target_y_pixel}, {initial_offset_dec}, check and refine: {check_and_refine}, {max_attempts}, tol: {tolerance}, {exposure}, {readout}, {save_images}, {save_path}, {sync_mount}, {settle_time}, {do_initial_slew}" diff --git a/pyscope/reduction/avg_fits.py b/pyscope/reduction/avg_fits.py index dc81ae4a..d0a2ca35 100644 --- a/pyscope/reduction/avg_fits.py +++ b/pyscope/reduction/avg_fits.py @@ -84,19 +84,19 @@ def avg_fits_cli( fnames : path path of directory of images to average. - pre_normalize : bool, default=False + pre_normalize : `bool`, default=`False` Normalize each image by its own mean before combining. This mode is most useful for combining sky flats. - mode : str, default="0" + mode : `str`, default="0" Mode to use for averaging images (0 = median, 1 = mean). - datatype : str, default="float32" + datatype : `str`, default="float32" Data type to save out the averaged image. If pre_normalize is True, the data type will be float64. outfile : path Path to save averaged image. If not specified, the averaged image will be saved in the same directory as the input images with the first image's name and _avg.fts appended to it. - verbose : int, default=0 + verbose : `int`, default=0 Print verbose output. Returns diff --git a/pyscope/reduction/avg_fits_ccdproc.py b/pyscope/reduction/avg_fits_ccdproc.py index 3f499667..bbb4e76b 100644 --- a/pyscope/reduction/avg_fits_ccdproc.py +++ b/pyscope/reduction/avg_fits_ccdproc.py @@ -230,71 +230,71 @@ def avg_fits_ccdproc_cli( Parameters ---------- - outfile : str + outfile : `str` path to save combined image. - fnames : list + fnames : `list` list of image paths to combine. - method="median" : str, optional + method="median" : `str`, optional method to use for averaging images. Options are "median", "average", "sum" - datatype : np.datatype, optional - intermediate and resulting dtype for combined CCDs, by default np.uint16 + datatype : `numpy.dtype`, optional + intermediate and resulting dtype for combined CCDs, by default `numpy.uint16` - weights : np.ndarray, optional - Weights to be used when combining images. An array with the weight values. The dimensions should match the the dimensions of the data arrays being combined., by default None + weights : `numpy.ndarray`, optional + Weights to be used when combining images. An array with the weight values. The dimensions should match the the dimensions of the data arrays being combined; by default `None` - scale : callable or np.ndarray, optional - Scaling factor to be used when combining images. Images are multiplied by scaling prior to combining them. Scaling may be either a function, which will be applied to each image to determine the scaling factor, or a list or array whose length is the number of images in the Combiner, by default None + scale : `callable` or `numpy.ndarray`, optional + Scaling factor to be used when combining images. Images are multiplied by scaling prior to combining them. Scaling may be either a function, which will be applied to each image to determine the scaling factor, or a `list` or array whose length is the number of images in the Combiner, by default `None` - mem_limit : float, optional + mem_limit : `float`, optional Maximum memory which should be used while combining (in bytes), by default 16000000000.0 - clip_extrema : bool, optional - Set to True if you want to mask pixels using an IRAF-like minmax clipping algorithm. The algorithm will mask the lowest nlow values and the highest nhigh values before combining the values to make up a single pixel in the resulting image. For example, the image will be a combination of Nimages-low-nhigh pixel values instead of the combination of Nimages. Parameters below are valid only when clip_extrema is set to True, by default False + clip_extrema : `bool`, optional + Set to `True` if you want to mask pixels using an IRAF-like minmax clipping algorithm. The algorithm will mask the lowest nlow values and the highest nhigh values before combining the values to make up a single pixel in the resulting image. For example, the image will be a combination of Nimages-low-nhigh pixel values instead of the combination of Nimages. Parameters below are valid only when clip_extrema is set to `True`, by default `False` - nlow : int, optional + nlow : `int`, optional Number of low values to reject from the combination, by default 1 - nhigh : int, optional + nhigh : `int`, optional Number of high values to reject from the combination, by default 1 - minmax_clip : bool, optional - Set to True if you want to mask all pixels that are below minmax_clip_min or above minmax_clip_max before combining, by default False + minmax_clip : `bool`, optional + Set to `True` if you want to mask all pixels that are below minmax_clip_min or above minmax_clip_max before combining, by default `False` - minmax_clip_min : float, optional - All pixels with values below min_clip will be masked, by default None + minmax_clip_min : `float`, optional + All pixels with values below min_clip will be masked, by default `None` - minmax_clip_max : flaot, optional - All pixels with values above min_clip will be masked, by default None + minmax_clip_max : `float`, optional + All pixels with values above min_clip will be masked, by default `None` - sigma_clip : bool, optional - Set to True if you want to reject pixels which have deviations greater than those set by the threshold values. The algorithm will first calculated a baseline value using the function specified in func and deviation based on sigma_clip_dev_func and the input data array. Any pixel with a deviation from the baseline value greater than that set by sigma_clip_high_thresh or lower than that set by sigma_clip_low_thresh will be rejected, by default False + sigma_clip : `bool`, optional + Set to `True` if you want to reject pixels which have deviations greater than those set by the threshold values. The algorithm will first calculated a baseline value using the function specified in func and deviation based on sigma_clip_dev_func and the input data array. Any pixel with a deviation from the baseline value greater than that set by sigma_clip_high_thresh or lower than that set by sigma_clip_low_thresh will be rejected, by default `False` - sigma_clip_low_thresh : int, optional - Threshold for rejecting pixels that deviate below the baseline value. If negative value, then will be convert to a positive value. If None, no rejection will be done based on low_thresh, by default 3 + sigma_clip_low_thresh : `int`, optional + Threshold for rejecting pixels that deviate below the baseline value. If negative value, then will be convert to a positive value. If `None`, no rejection will be done based on low_thresh, by default 3 - sigma_clip_high_thresh : int, optional - Threshold for rejecting pixels that deviate above the baseline value. If None, no rejection will be done based on high_thresh, by default 3 + sigma_clip_high_thresh : `int`, optional + Threshold for rejecting pixels that deviate above the baseline value. If `None`, no rejection will be done based on high_thresh, by default 3 - sigma_clip_func : callable, optional - The statistic or callable function/object used to compute the center value for the clipping. If using a callable function/object and the axis keyword is used, then it must be able to ignore NaNs (e.g., numpy.nanmean) and it must have an axis keyword to return an array with axis dimension(s) removed. The default is 'median', by default None + sigma_clip_func : `callable`, optional + The statistic or callable function/object used to compute the center value for the clipping. If using a callable function/object and the axis keyword is used, then it must be able to ignore NaNs (e.g., `numpy.nanmean`) and it must have an axis keyword to return an array with axis dimension(s) removed. The default is 'median', by default `None` - sigma_clip_dev_func : callable, optional - The statistic or callable function/object used to compute the standard deviation about the center value. If using a callable function/object and the axis keyword is used, then it must be able to ignore NaNs (e.g., numpy.nanstd) and it must have an axis keyword to return an array with axis dimension(s) removed. The default is 'std', by default None + sigma_clip_dev_func : `callable`, optional + The statistic or callable function/object used to compute the standard deviation about the center value. If using a callable function/object and the axis keyword is used, then it must be able to ignore NaNs (e.g., `numpy.nanstd`) and it must have an axis keyword to return an array with axis dimension(s) removed. The default is 'std', by default `None` - combine_uncertainty_function : callable, optional - If None use the default uncertainty func when using average, median or sum combine, otherwise use the function provided, by default None + combine_uncertainty_function : `callable`, optional + If `None` use the default uncertainty func when using average, median or sum combine, otherwise use the function provided, by default `None` - overwrite_output : bool, optional - If output_file is specified, this is passed to the astropy.nddata.fits_ccddata_writer under the keyword overwrite; has no effect otherwise., by default False + overwrite_output : `bool`, optional + If `output_file` is specified, this is passed to the `astropy.nddata.fits_ccddata_writer` under the keyword overwrite; has no effect otherwise., by default `False` - unit : str, optional + unit : `str`, optional unit for CCDData objects, by default 'adu' - verbose : bool, optional - verbosity of logger, by default False + verbose : `bool`, optional + verbosity of logger, by default `False` """ if verbose: diff --git a/pyscope/reduction/maxim_pinpoint_wcs.py b/pyscope/reduction/maxim_pinpoint_wcs.py index cbfcadd1..16be6c7e 100644 --- a/pyscope/reduction/maxim_pinpoint_wcs.py +++ b/pyscope/reduction/maxim_pinpoint_wcs.py @@ -28,7 +28,7 @@ def maxim_pinpoint_wcs_cli(filepath): Parameters ---------- - filepath : str + filepath : `str` Returns ------- diff --git a/pyscope/telrun/airmass_condition.py b/pyscope/telrun/airmass_condition.py index c0b7e53f..0b2602b1 100644 --- a/pyscope/telrun/airmass_condition.py +++ b/pyscope/telrun/airmass_condition.py @@ -47,16 +47,16 @@ def __init__(self, airmass_limit=3, formula="Schoenberg1929", weight=1, **kwargs Parameters ---------- - airmass_limit : float, default : 3 + airmass_limit : `float`, default : 3 The maximum airmass value that is allowed. - formula: `str`, default : "secant", {"secant", "Schoenberg1929", "Young+Irvine1967", "Hardie1962", "Rozenberg1966", "KastenYoung1989", "Young1994", "Pickering2002"} + formula : `str`, default : "secant", {"secant", "Schoenberg1929", "Young+Irvine1967", "Hardie1962", "Rozenberg1966", "KastenYoung1989", "Young1994", "Pickering2002"} The formula to use to calculate the airmass value. - weight : float, default : 1 + weight : `float`, default : 1 The weight of the condition in the final score. The default is 1. - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the `~pyscope.telrun.BoundaryCondition` constructor for storage in the `~pyscope.telrun.BoundaryCondition.kwargs` attribute. References @@ -89,11 +89,11 @@ def from_string(self, string, airmass_limit=None, formula=None, weight=None): ---------- string : `str`, required - airmass_limit : `float`, default : None + airmass_limit : `float`, default : `None` - formula : `str`, default : None + formula : `str`, default : `None` - weight : `float`, default : None + weight : `float`, default : `None` """ logger.debug( diff --git a/pyscope/telrun/autofocus_field.py b/pyscope/telrun/autofocus_field.py index 3b8c9f32..44fcd754 100644 --- a/pyscope/telrun/autofocus_field.py +++ b/pyscope/telrun/autofocus_field.py @@ -139,9 +139,9 @@ def from_string( ---------- string : `str`, required - config : `~pyscope.telrun.InstrumentConfiguration`, default : None + config : `~pyscope.telrun.InstrumentConfiguration`, default : `None` - repositioning : 2-tuple of `~astropy.units.Quantity`, default : None + repositioning : 2-tuple of `~astropy.units.Quantity`, default : `None` dither : `~astropy.units.Quantity`, default : 0 arcsec diff --git a/pyscope/telrun/boundary_condition.py b/pyscope/telrun/boundary_condition.py index 5f3efb42..b9b45743 100644 --- a/pyscope/telrun/boundary_condition.py +++ b/pyscope/telrun/boundary_condition.py @@ -151,7 +151,7 @@ def __call__(self, target, time, location, **kwargs): location : `~astropy.coordinates.EarthLocation` The location of the observatory. - **kwargs : dict + **kwargs : `dict` Returns ------- diff --git a/pyscope/telrun/coord_condition.py b/pyscope/telrun/coord_condition.py index 7668c675..4fc9fa1b 100644 --- a/pyscope/telrun/coord_condition.py +++ b/pyscope/telrun/coord_condition.py @@ -91,17 +91,17 @@ def from_string( ---------- string : `str`, required - coord_type : `str`, default : None + coord_type : `str`, default : `None` - coord_idx : `int`, default : None + coord_idx : `int`, default : `None` - min_val : `~astropy.units.Quantity`, default : None + min_val : `~astropy.units.Quantity`, default : `None` - max_val : `~astropy.units.Quantity`, default : None + max_val : `~astropy.units.Quantity`, default : `None` - score_type : `str`, default : None + score_type : `str`, default : `None` - ref_coord : `~astropy.coordinates.SkyCoord`, default : None + ref_coord : `~astropy.coordinates.SkyCoord`, default : `None` **kwargs : `dict`, default : {} diff --git a/pyscope/telrun/dark_field.py b/pyscope/telrun/dark_field.py index 6e94cefa..ce4b7b5e 100644 --- a/pyscope/telrun/dark_field.py +++ b/pyscope/telrun/dark_field.py @@ -33,7 +33,7 @@ def __init__( that are captured in the dark frame. If `None`, the pointing will not change and the dark frame will be taken in the current position of the telescope. - config : `~pyscope.telrun.InstrumentConfiguration`, default : None + config : `~pyscope.telrun.InstrumentConfiguration`, default : `None` The instrument configuration to use for the observation. If None, the default configuration from the `~pyscope.telrun.ScheduleBlock` will be used. @@ -47,7 +47,7 @@ def __init__( The output filename for the observation. If not specified, the filename will be automatically generated. - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the instrument for the observation. """ @@ -76,9 +76,9 @@ def from_string( ---------- string : `str`, required - target : `~astropy.coordinates.SkyCoord`, default : None + target : `~astropy.coordinates.SkyCoord`, default : `None` - config : `~pyscope.telrun.Config`, default : None + config : `~pyscope.telrun.Config`, default : `None` exp : `~astropy.units.Quantity`, default : 0 sec diff --git a/pyscope/telrun/field.py b/pyscope/telrun/field.py index f638d5ab..68ac6211 100644 --- a/pyscope/telrun/field.py +++ b/pyscope/telrun/field.py @@ -21,11 +21,11 @@ def __init__(self, target, config=None, **kwargs): The target field to observe. If the target has proper motion, ensure that the reference epoch and the proper motions are set. - config : `~pyscope.telrun.InstrumentConfiguration`, default : None - The instrument configuration to use for the observation. If None, the + config : `~pyscope.telrun.InstrumentConfiguration`, default : `None` + The instrument configuration to use for the observation. If `None`, the default configuration from the `~pyscope.telrun.ScheduleBlock` will be used. - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the instrument for the observation. """ diff --git a/pyscope/telrun/flat_field.py b/pyscope/telrun/flat_field.py index f565dd45..c4004e48 100644 --- a/pyscope/telrun/flat_field.py +++ b/pyscope/telrun/flat_field.py @@ -49,8 +49,8 @@ def __init__( that the reference epoch and the proper motions are set. The default is the `CoverCalibrator` which is a pre-configured location to take flat field images. - config : `~pyscope.telrun.InstrumentConfiguration`, default : None - The instrument configuration to use for the observation. If None, the + config : `~pyscope.telrun.InstrumentConfiguration`, default : `None` + The instrument configuration to use for the observation. If `None`, the default configuration from the `~pyscope.telrun.ScheduleBlock` will be used. dither : `~astropy.units.Quantity`, default : 0 arcsec @@ -119,9 +119,9 @@ def from_string( ---------- string : `str`, required - target : `~astropy.coordinates.SkyCoord`, default : None + target : `~astropy.coordinates.SkyCoord`, default : `None` - config : `~pyscope.telrun.Config`, default : None + config : `~pyscope.telrun.Config`, default : `None` dither : `~astropy.units.Quantity`, default : 0 arcsec diff --git a/pyscope/telrun/hourangle_condition.py b/pyscope/telrun/hourangle_condition.py index 81b7b00c..9647bfbe 100644 --- a/pyscope/telrun/hourangle_condition.py +++ b/pyscope/telrun/hourangle_condition.py @@ -58,9 +58,9 @@ def from_string(cls, string, min_hour_angle=None, max_hour_angle=None): ---------- string : `str`, required - min_hour_angle : `~astropy.units.Quantity`, default : None + min_hour_angle : `~astropy.units.Quantity`, default : `None` - max_hour_angle : `~astropy.units.Quantity`, default : None + max_hour_angle : `~astropy.units.Quantity`, default : `None` Returns ------- diff --git a/pyscope/telrun/light_field.py b/pyscope/telrun/light_field.py index 6c96d063..a6fd9229 100644 --- a/pyscope/telrun/light_field.py +++ b/pyscope/telrun/light_field.py @@ -75,7 +75,7 @@ def __init__( constraints for this field. The `~pyscope.telrun.Optimizer` inside the `~pyscope.telrun.Scheduler` will use the `~pyscope.telrun.BoundaryCondition` objects to determine the best possible schedule. - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the instrument for the observation. """ @@ -135,7 +135,7 @@ def from_string( conditions : `list` of `~pyscope.telrun.BoundaryCondition`, default : [] - kwargs : dict, default : {} + kwargs : `dict`, default : {} Returns ------- diff --git a/pyscope/telrun/mk_mosaic_schedule.py b/pyscope/telrun/mk_mosaic_schedule.py index f5c11609..87e5266e 100644 --- a/pyscope/telrun/mk_mosaic_schedule.py +++ b/pyscope/telrun/mk_mosaic_schedule.py @@ -156,55 +156,55 @@ def mk_mosaic_schedule_cli( Parameters ---------- - source : str + source : `str` Source name to resolve coordinates or a pair of ICRS ra,dec coordinates - filters : str or tuple of str + filters : `str` or `tuple` of `str` Filters to use. Multiple filters can be specified by a tuple, e.g. ('b', 'g', 'r') - exp_times : float or tuple of float + exp_times : `float` or `tuple` of `float` Exposure times to use. Multiple exposure times can be specified by a tuple, e.g. (10, 20) - observer : tuple of str + observer : `tuple` of `str` Observer name and 3-character code, e.g. ('Walter Golay', 'XWG') - overlap : float, default=5 + overlap : `float`, default=5 Overlap between pointings (arcmin). - fov : tuple of float, default=(20, 20) + fov : `tuple` of `float`, default=(20, 20) Field of view (arcmin). - grid_size : tuple of int, default=(3, 3) + grid_size : `tuple` of `int`, default=(3, 3) Grid size (nrows, ncols). - n_exp : int, default=1 + n_exp : `int`, default=1 Number of exposures per filter and exposure time. - readout : int, default=0 + readout : `int`, default=0 Readout mode as specified by the camera. - binning : str, default='1x1' + binning : `str`, default='1x1' Binning mode. - ut_start : str, optional + ut_start : `str`, optional UT start time of the observation in the ISOT format. If none given, the object will be scheduled for the best possible time. - comment : str, optional + comment : `str`, optional Comment to be added to the schedule. - write : str, optional + write : `str`, optional Write a .sch file with the given name. If none given from the command line, a name is generated from the observing code. Otherwise, a file will not be written and the ObservingBlock set will be returned. - verbose : int, {-1, 0, 1}, default=-1 + verbose : `int`, {-1, 0, 1}, default=-1 Verbosity level. 0: no debug messages, 1: debug messages. Default set to -1 for API use and 0 for CLI use. Returns ------- - obsblocks : `~astroplan.ObservingBlock` tuple or None + obsblocks : `~astroplan.ObservingBlock` `tuple` or `None` Set of ObservingBlocks for the mosaic observation. Raises diff --git a/pyscope/telrun/option.py b/pyscope/telrun/option.py index 44bc8b73..99fbf9e5 100644 --- a/pyscope/telrun/option.py +++ b/pyscope/telrun/option.py @@ -31,10 +31,10 @@ def __init__( instruments : `list` of `str`, default : [] The list of instruments used by the `~pyscope.telrun.Option`. This can be used to sort options by instrument. - current_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : None + current_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : `None` The current value of the `~pyscope.telrun.Option`. This is the value that will be used in the observation if the `~pyscope.telrun.Option` is not changed. - default_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : None + default_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : `None` The default value of the `~pyscope.telrun.Option`. This is the value that will be used if the `~pyscope.telrun.Option` is not set by the user. description : `str`, default : "" @@ -43,7 +43,7 @@ def __init__( type : `str`, default : "str" The type of the `~pyscope.telrun.Option`. This can be one of "str", "int", "float", "bool", "list", or "dict". - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the `~pyscope.telrun.Option`. If `type="list"` or `type="dict"`, requested values will be validated against `vlist` or `vdict` respectively. If `type="int"` or `type="float"`, the value will be validated against `min` and `max` if they are set. If `type="bool"`, the value will be converted to a `bool`. If `type="str"`, the @@ -84,17 +84,17 @@ def from_string( ---------- string : `str`, required - name : `str`, default : None + name : `str`, default : `None` - instruments : `list` of `str`, default : None + instruments : `list` of `str`, default : `None` - current_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : None + current_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : `None` - default_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : None + default_value : `str`, `int`, `float`, `bool`, `list`, `dict`, default : `None` - description : `str`, default : None + description : `str`, default : `None` - type : `str`, default : None + type : `str`, default : `None` **kwargs : `dict`, default : {} diff --git a/pyscope/telrun/rst.py b/pyscope/telrun/rst.py index 3ea20e6e..b9c20326 100644 --- a/pyscope/telrun/rst.py +++ b/pyscope/telrun/rst.py @@ -79,22 +79,22 @@ def rst_cli(source=None, date=None, observatory="./config/observatory.cfg", verb Parameters ---------- - source : str, optional + source : `str`, optional Source name. - date : str [YYYY-MM-DD], optional + date : `str` [YYYY-MM-DD], optional Date of observation. If none is given, the current date at the observatory is used. - observatory : str or `~pyscope.observatory.Observatory`, default='./config/observatory.cfg' + observatory : `str` or `~pyscope.observatory.Observatory`, default='./config/observatory.cfg' Observatory configuration file or `~pyscope.observatory.Observatory` object. - verbose : int, {-1, 0, 1}, default=-1 + verbose : `int`, {-1, 0, 1}, default=-1 Verbosity level. 0: no debug messages, 1: debug messages. Default set to -1 for API use and 0 for CLI use. Returns ------- - events: list + events: `list` of `tuple` List of tuples containing the event name and a `~astropy.time.Time` object. Raises diff --git a/pyscope/telrun/schedtab.py b/pyscope/telrun/schedtab.py index 81d45b03..fc6b1ea6 100644 --- a/pyscope/telrun/schedtab.py +++ b/pyscope/telrun/schedtab.py @@ -18,7 +18,7 @@ def blocks_to_table(observing_blocks): Parameters ---------- - observing_blocks : list + observing_blocks : `list` A list of observing blocks. Returns diff --git a/pyscope/telrun/telrun_operator.py b/pyscope/telrun/telrun_operator.py index 368671d2..36f240d0 100644 --- a/pyscope/telrun/telrun_operator.py +++ b/pyscope/telrun/telrun_operator.py @@ -43,7 +43,7 @@ def __init__(self, telhome="./", gui=True, **kwargs): Parameters ---------- - telhome : str, optional + telhome : `str`, optional The path to the TelrunOperator home directory. The default is the current working directory. Telhome must have a specific directory structure, which is created if it does not exist. The directory structure and some relevant files are as follows:: @@ -84,8 +84,8 @@ def __init__(self, telhome="./", gui=True, **kwargs): observing blocks. The `images/` directory structure is dictated by the `~pyscope.reduction` scripts, which are used for rapid image calibration and reduction. - gui : bool, optional - Whether to start the GUI. Default is True. + gui : `bool`, optional + Whether to start the GUI. Default is `True`. **kwargs Keyword arguments to pass to the TelrunOperator constructor. More details in Other Parameters diff --git a/pyscope/telrun/transition_field.py b/pyscope/telrun/transition_field.py index c50e9396..980171c3 100644 --- a/pyscope/telrun/transition_field.py +++ b/pyscope/telrun/transition_field.py @@ -34,7 +34,7 @@ def __init__( est_duration : `~astropy.units.Quantity`, default : 0 sec The duration of the transition in seconds. Typically, the `~pyscope.observatory.Observatory` will calculate the duration and set this value. - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Additional keyword arguments to pass to the instrument for the observation """ @@ -68,7 +68,7 @@ def from_string( est_duration : `~astropy.units.Quantity`, default : 0 sec - **kwargs : dict, default : {} + **kwargs : `dict`, default : {} Returns -------