sourcefinder.accessors ====================== .. py:module:: sourcefinder.accessors .. autoapi-nested-parse:: Data accessors. These can be used to populate ImageData objects based on some data source (FITS file, array in memory... etc.). .. !! processed by numpydoc !! Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/sourcefinder/accessors/aartfaaccasaimage/index /autoapi/sourcefinder/accessors/amicasaimage/index /autoapi/sourcefinder/accessors/casaimage/index /autoapi/sourcefinder/accessors/dataaccessor/index /autoapi/sourcefinder/accessors/detection/index /autoapi/sourcefinder/accessors/fitsimage/index /autoapi/sourcefinder/accessors/fitsimageblob/index /autoapi/sourcefinder/accessors/kat7casaimage/index /autoapi/sourcefinder/accessors/lofaraccessor/index /autoapi/sourcefinder/accessors/lofarcasaimage/index /autoapi/sourcefinder/accessors/lofarfitsimage/index /autoapi/sourcefinder/accessors/lofarhdf5image/index Classes ------- .. autoapisummary:: sourcefinder.accessors.Conf sourcefinder.accessors.ExportSettings sourcefinder.accessors.FitsImageBlob sourcefinder.accessors.ImageData sourcefinder.accessors.ImgConf sourcefinder.accessors.LofarFitsImage Functions --------- .. autoapisummary:: sourcefinder.accessors.open sourcefinder.accessors.sourcefinder_image_from_accessor sourcefinder.accessors.writefits Package Contents ---------------- .. py:class:: Conf .. py:attribute:: export :type: ExportSettings .. py:attribute:: image :type: ImgConf .. py:class:: ExportSettings Bases: :py:obj:`_Validate` Selection of output, related to detected sources and/or intermediate image processing products .. !! processed by numpydoc !! .. py:attribute:: csv :type: bool :value: False Generate CSV text file (e.g., for TopCat). .. !! processed by numpydoc !! .. py:attribute:: file_type :type: str :value: 'csv' Output file type (default: csv). .. !! processed by numpydoc !! .. py:attribute:: islands :type: bool :value: False Generate island maps. .. !! processed by numpydoc !! .. py:attribute:: output_dir :type: str :value: '.' Directory in which to write the output files. .. !! processed by numpydoc !! .. py:attribute:: pandas_df :type: bool :value: True If True, the measured and derived source parameters will be returned as a Pandas DataFrame. If false, they will be returned as a `utility.containers.ExtractionResults` object. .. !! processed by numpydoc !! .. py:attribute:: regions :type: bool :value: False Generate DS9 region file(s). .. !! processed by numpydoc !! .. py:attribute:: residuals :type: bool :value: False Generate residual maps. .. !! processed by numpydoc !! .. py:attribute:: rmsmap :type: bool :value: False Generate RMS map. .. !! processed by numpydoc !! .. py:attribute:: sigmap :type: bool :value: False Generate significance map. .. !! processed by numpydoc !! .. py:attribute:: skymodel :type: bool :value: False Generate sky model. .. !! processed by numpydoc !! .. py:attribute:: source_params :type: list[str] Collect all possible source parameters. .. !! processed by numpydoc !! .. py:attribute:: source_params_file :type: list[str] Source parameters to include in a file for storage. .. !! processed by numpydoc !! .. py:class:: FitsImageBlob(hdulist, plane=None, beam=None, hdu_index=0) Bases: :py:obj:`sourcefinder.accessors.fitsimage.FitsImage` A FITS image blob. Same as ``sourcefinder.accessors.fitsimage.FitsImage`` but constructed from an in-memory FITS file, not a FITS file on disk. :Parameters: **hdulist** : astropy.io.fits.HDUList The HDU list representing the in-memory FITS file. **plane** : int, default: None If the data is a datacube, specifies which plane to use. **beam** : tuple, default: None Beam parameters in degrees, in the form (bmaj, bmin, bpa). If not supplied, the method will attempt to read these from the header. **hdu_index** : int, default: 0 The index of the HDU to use from the HDU list. .. !! processed by numpydoc !! .. py:method:: _get_header(*args) Retrieve the header from the specified HDU. :Parameters: **\*args** : tuple Positional arguments where: - args[0] is the HDU list (astropy.io.fits.HDUList). - args[1] is the index of the HDU to use. :Returns: astropy.io.fits.Header The header of the specified HDU. .. !! processed by numpydoc !! .. py:method:: read_data(*args) Read and process the data from the specified HDU. :Parameters: **\*args** : tuple Positional arguments where: - args[0] is the HDU list (astropy.io.fits.HDUList). - args[1] is the index of the HDU to use. - args[2] is the plane index (int) if the data is a datacube. :Returns: numpy.ndarray The processed 2D data array. Processing here means remove axes of length 1, select the plane index from the datacube if needed, and transpose. .. !! processed by numpydoc !! .. py:attribute:: data .. py:attribute:: header .. py:attribute:: pixelsize .. py:attribute:: url :value: 'AARTFAAC streaming image' .. py:attribute:: wcs .. py:class:: ImageData(data, beam, wcs, conf: sourcefinder.config.Conf = Conf(image=ImgConf(), export=ExportSettings())) Bases: :py:obj:`object` Encapsulates an image in terms of a numpy array + meta/headerdata. This is your primary contact point for interaction with images: it includes facilities for source extraction and measurement, etc. :Parameters: **data** : 2D np.ndarray Observational image data. Must be a regular np.ndarray, since image data read from e.g. a FITS file is not a MaskedArray. **beam** : tuple Clean beam specification as (semi-major axis, semi-minor axis, position angle) with the axes in pixel coordinates and the position angle in radians **wcs** : utility.coordinates.wcs World coordinate system specification, in our case it is always about sky coordinates. **conf** : Conf, default: Conf(image=ImgConf(), export=ExportSettings()) Configuration options for source finding. This includes settings related to image processing (e.g., background and rms noise estimation, thresholds) as well as export options (e.g., source parameters and output maps). .. !! processed by numpydoc !! .. py:method:: __grids() Calculate background and RMS grids of this image. These grids can be interpolated up to make maps of the original image dimensions: see _interpolate(). This is called automatically when ImageData.backmap, ImageData.rmsmap or ImageData.fdrmap is first accessed. .. !! processed by numpydoc !! .. py:method:: _interpolate(grid, inds, roundup=False) Interpolate a grid to produce a map of the dimensions of the image. :Parameters: **grid** : np.ma.MaskedArray The grid to be interpolated. **roundup** : bool, default: False If True, values of the resultant map which are lower than the input grid are trimmed. Default is False. :Returns: np.ma.MaskedArray The interpolated map. .. rubric:: Notes This function is used to transform the RMS, background or FDR grids produced by :func:`_grids()` to a map we can compare with the image data. .. !! processed by numpydoc !! .. py:method:: _pyse(detectionthresholdmap, analysisthresholdmap, labelled_data=None, labels=np.array([], dtype=np.int32)) Run Python-based source extraction on this image. :Parameters: **detectionthresholdmap** : np.ma.MaskedArray 2D array of floats with the same shape as the observational image (self.rawdata). The detection threshold map imposes an extra threshold for source detection and is therefore higher than the analysis threshold map. **analysisthresholdmap** : np.ma.MaskedArray 2D array of floats with the same shape as the observational image (self.rawdata). analysisthresholdmap imposes the primary threshold for source detection. All the pixels within the island that exceed this will be used when measuring the source. It is lower (or equal) than detectionthresholdmap, or else we would be left with too few pixels for proper source shape measurements, in some cases. This map is computed as analysis_threshold * self.rmsmap. **labelled_data** : np.ndarray, optional, default=None Labelled island map (output of np.ndimage.label()). Will be calculated automatically if not provided. **labels** : np.ndarray, optional, default=np.array([], dtype=np.int32) Array of integers representing the labels in the island map to use for fitting. :Returns: A `utility.containers.ExtractionResults` instance or a Pandas .. DataFrame containing the results of the source extraction. .. .. rubric:: Notes This is described in detail in the "LOFAR Transients Pipeline" article by John D. Swinbank et al., see https://doi.org/10.1016/j.ascom.2015.03.002 .. !! processed by numpydoc !! .. py:method:: box_slice_about_pixel(x, y, box_radius) :staticmethod: Returns a slice centred about (x,y), of width = 2 * int(box_radius) + 1. :Parameters: **x** : int Desired row index. **y** : int Desired column index. **box_radius** : float Radius of the box in pixel coordinates. :Returns: tuple of slice Slice centred about (x,y) with width = 2*box_radius + 1. .. !! processed by numpydoc !! .. py:method:: clearcache() Zap any calculated data stored in this object. Clear the background and rms maps, labels, clip, and any locally held data. All of these can be reconstructed from the data accessor. Note that this *must* be run to pick up any new settings. .. !! processed by numpydoc !! .. py:method:: extract(noisemap=None, bgmap=None, labelled_data=None, labels=None) Kick off conventional (ie, rms island finding) source extraction. :Parameters: **noisemap** : np.ndarray, default: None Noise map, i.e. the standard deviation (rms) of the background noise across the observational image **bgmap** : np.ndarray, default: None Background map, i.e. the mean of the background noise across the observational image. **labelled_data** : np.ndarray, default: None The output of a connected component analysis of the image, with a unique label for each source. Should have the same shape as the observational image. **labels** : np.ndarray, default: None Labels array, i.e. a 1D integer array of labels for each source. :Returns: A `utility.containers.ExtractionResults` instance or a .. Pandas DataFrame containing the results of the source .. extraction. .. .. !! processed by numpydoc !! .. py:method:: extract_parms_image_slice(some_image, inds, labelled_data, label, dummy, maxpos, maxi, npix) :staticmethod: Find the highest pixel value and its position. For an island, indicated by a group of pixels with the same label, find the highest pixel value and its position, first relative to the upper left corner of the rectangular slice encompassing the island, but finally relative to the upper left corner of the image, i.e. the [0, 0] position of the Numpy array with all the image pixel values. Also, derive the number of pixels of the island. :Parameters: **some_image** : np.ndarray 2D array with all the pixel values, typically self.data_bgsubbed.data. **inds** : np.ndarray Array of four indices indicating the slice encompassing an island. Such a slice would typically be a pick from a list of slices from a call to scipy.ndimage.find_objects. Since we are attempting vectorized processing here, the slice should have been replaced by its four coordinates through a call to slices_to_indices. **labelled_data** : np.ndarray Array with the same shape as some_image, with labelled islands with integer values and zeroes for all background pixels. **label** : int The label (integer value) corresponding to the slice encompassing the island. Or actually it should be the other way round, since there can be multiple islands within one rectangular slice. **dummy** : np.ndarray Artefact of the implementation of guvectorize: Empty array with the same shape as maxpos. It is needed because of a missing feature in guvectorize: There is no other way to tell guvectorize what the shape of the output array will be. Therefore, we define an otherwise redundant input array with the same shape as the desired output array. Defined as int32, but could be any type. **maxpos** : np.ndarray Array of two integers indicating the indices of the highest pixel value of the island with label = label relative to the position of pixel [0, 0] of the image. **maxi** : np.float32 Float32 equal to the highest pixel value of the island with label=label. **npix** : np.int32 Integer indicating the number of pixels of the island. :Returns: None No return values, because of the use of the guvectorize decorator: 'guvectorize() functions don’t return their result value: they take it as an array argument, which must be filled in by the function'. In this case maxpos, maxi and npix will be filled with values. .. !! processed by numpydoc !! .. py:method:: fd_extract(alpha, noisemap=None, bgmap=None) False Detection Rate based source extraction. The FDR procedure guarantees that the False Detection Rate (FDR) is less than alpha. :Parameters: **alpha** : float Maximum allowed fraction of false positives. Must be between 0 and 1, exclusive. **noisemap** : np.ndarray, default: None Noise map, i.e. the standard deviation (rms) of the background noise across the observational image **bgmap** : np.ndarray, default: None Background map, i.e. the mean of the background noise across the observational image. :Returns: A`utility.containers.ExtractionResults` instance or a .. Pandas Dataframe containing the results of the source .. extraction. .. .. rubric:: Notes See Hopkins et al., AJ, 123, 1086 (2002) for more details. http://adsabs.harvard.edu/abs/2002AJ....123.1086H .. !! processed by numpydoc !! .. py:method:: fit_fixed_positions(positions, boxsize, threshold=None, fixed='position+shape', ids=None) Convenience function to fit a list of sources at the given positions. This function wraps around :py:func:`fit_to_point`. :Parameters: **positions** : list of tuples List of (RA, Dec) tuples. Positions to be fit, in decimal degrees. **boxsize** : int Length of the square section of the image to use for the fit. **threshold** : float, default: None Threshold below which data is not used for fitting. **fixed** : str, default: 'position+shape' If set to `position`, the pixel coordinates are fixed in the fit. **ids** : tuple, default: None List of identifiers. If not None, must match the length and order of the requested fits. :Returns: tuple A list of successful fits. If ``ids`` is None, returns a single list of :class:`sourcefinder.extract.Detection` s. Otherwise, returns a tuple of two matched lists: ([detections], [matching_ids]). .. rubric:: Notes boxsize is in pixel coordinates, not in sky coordinates. .. !! processed by numpydoc !! .. py:method:: fit_islands(fudge_max_pix_factor, beamsize, correlation_lengths, fixed, island) :staticmethod: This function was created to enable the use of 'partial' such that we can parallellize source measurements .. !! processed by numpydoc !! .. py:method:: fit_to_point(x: int, y: int, boxsize: int, threshold: float, fixed: str) Fit an elliptical Gaussian to a specified point on the image. :Parameters: **x** : int Pixel x-coordinate of the point to fit. **y** : int Pixel y-coordinate of the point to fit. **boxsize** : int Length of the square section of the image to use for the fit. **threshold** : float Threshold below which data is not used for fitting (in units of rmsmap). **fixed** : str If set to ``position``, the pixel coordinates are fixed in the fit. :Returns: Detection An instance of :class:`sourcefinder.extract.Detection` containing the fit results. .. !! processed by numpydoc !! .. py:method:: label_islands(detectionthresholdmap, analysisthresholdmap) Return a labelled array of pixels for fitting. :Parameters: **detectionthresholdmap** : np.ma.MaskedArray Detection threshold map with shape (nrow, ncol), matching the shape of the observational image (self.rawdata). The values are of dtype np.float32. **analysisthresholdmap** : np.ma.MaskedArray Analysis threshold map with shape (nrow, ncol), matching the shape of the observational image (self.rawdata). The values are of dtype np.float32. :Returns: tuple - labels_above_det_thr (np.ndarray): 1D array of labels above detection threshold, with shape (num_islands_above_detection_threshold,) and dtype np.int64. Note that the length of this array may be smaller than the total number of islands above the analysis threshold, as some labels may have been filtered out due to a peak spectral brightness lower than the local detection threshold. - labelled_data (np.ndarray): Array of labelled pixels, where each pixel with a nonzero label corresponds to an island above the analysis threshold. The array has the same shape as the observational image (self.rawdata) and contains integer values corresponding to the labels of the islands. Pixels that do not belong to any island are assigned a label of 0. The number of islands above the analysis threshold is equal to the number of unique labels in this array, which is equal to or larger than num_islands_above_detection_threshold, i.e. the number of islands above the detection threshold. This array has dtype np.int32. - num_islands_above_detection_threshold (int): Number of islands above detection threshold. - maxposs_above_det_thr (np.ndarray): Array of indices of the maximum pixel values above detection threshold, with shape (num_islands_above_detection_threshold, 2) and dtype np.int32. - maxis_above_det_thr (np.ndarray): Array of maximum pixel values above detection threshold, with shape (num_islands_above_detection_threshold,) and dtype np.float32. - npixs_above_det (np.ndarray): 1D array of pixel counts for each island with peak spectral brightness above the detection threshold, with shape (num_islands_above_detection_threshold,) and dtype np.int32. - all_indices_above_det_thr (np.ndarray): Array of indices of the islands above detection threshold, with shape (num_islands_above_detection_threshold, 4) and dtype np.int32. .. !! processed by numpydoc !! .. py:method:: reverse_se() Run source extraction on the negative of this image. This process can be used to estimate the false positive rate, as there should be no sources in the negative image. :Returns: :class:`sourcefinder.utility.containers.ExtractionResults` .. To prevent interference with the normal extraction process, cached .. data (background map, clips, etc.) is cleared before and after .. running this method. If this method is used frequently, a separate .. cache may be implemented in the future. .. .. !! processed by numpydoc !! .. py:method:: slices_to_indices(slices) :staticmethod: Convert the list of tuples of slices generated by scipy.ndimage.find_objects into a 2D int32 array with number of rows equal to the number of islands and 4 columns, i.e 4 integers per island, containing the same information as the slices, but more suitable for compilation by Numba .. !! processed by numpydoc !! .. py:attribute:: _conf .. py:property:: backmap Mean background map .. !! processed by numpydoc !! .. py:attribute:: beamsize .. py:attribute:: clip :type: dict[float, numpy.ndarray] .. py:property:: conf :type: sourcefinder.config.Conf .. py:attribute:: correlation_lengths .. py:property:: data Masked image data .. !! processed by numpydoc !! .. py:property:: data_bgsubbed Background subtracted masked image data .. !! processed by numpydoc !! .. py:attribute:: fudge_max_pix_factor .. py:property:: grids Gridded RMS and background data for interpolating .. !! processed by numpydoc !! .. py:attribute:: labels :type: dict[float, tuple[numpy.ndarray, int]] .. py:property:: pixmax Maximum pixel value (pre-background subtraction) .. !! processed by numpydoc !! .. py:property:: pixmin Minimum pixel value (pre-background subtraction) .. !! processed by numpydoc !! .. py:attribute:: rawdata .. py:property:: rmsmap root-mean-squares map, i.e. the standard deviation of the local background noise, interpolated across the image. .. !! processed by numpydoc !! .. py:attribute:: wcs .. py:property:: xdim X pixel dimension of (unmasked) data .. !! processed by numpydoc !! .. py:property:: ydim Y pixel dimension of (unmasked) data .. !! processed by numpydoc !! .. py:class:: ImgConf Bases: :py:obj:`_Validate` Configuration that should cover all the specifications for processing the image. .. !! processed by numpydoc !! .. py:attribute:: alpha :type: float :value: 0.01 FDR alpha value (float, default 0.01) that sets an upper limit on the fraction of pixels erroneously detected as source pixels, relative to all source pixels. This requirement should be met when averaged over a large ensemble of images, but problems were encountered with alpha as low as 0.001, see paragraph 3.6 of Spreeuw's thesis. .. !! processed by numpydoc !! .. py:attribute:: alpha_brightness1 :type: float :value: 1.5 First exponent for scaling errors in peak brightness, see equation 26 and paragraph 5.2.5 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_brightness2 :type: float :value: 1.5 Second exponent for scaling errors in peak brightness, see equation 26 and paragraph 5.2.5 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_maj1 :type: float :value: 2.5 First exponent for scaling errors along the fitted major axis, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_maj2 :type: float :value: 0.5 Second exponent for scaling errors along the fitted major axis, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_min1 :type: float :value: 0.5 First exponent for scaling errors along the fitted minor axis and for scaling errors in the position angle, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_min2 :type: float :value: 2.5 Second exponent for scaling errors along the fitted minor axis and for scaling errors in the position angle, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: analysis_thr :type: float :value: 3.0 Analysis threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image. .. !! processed by numpydoc !! .. py:attribute:: back_size_x :type: int | None :value: None Subimage size for estimation of background node values (X direction). The nodes are centred on the subimages. .. !! processed by numpydoc !! .. py:attribute:: back_size_y :type: int | None :value: None Subimage size for estimation of background node values (Y direction). The nodes are centred on the subimages. .. !! processed by numpydoc !! .. py:attribute:: bmaj :type: float | None :value: None Set beam: Major axis of restoring beam (degrees). .. !! processed by numpydoc !! .. py:attribute:: bmin :type: float | None :value: None Set beam: Minor axis of restoring beam (degrees). .. !! processed by numpydoc !! .. py:attribute:: bpa :type: float | None :value: None Set beam: Restoring beam position angle (degrees). .. !! processed by numpydoc !! .. py:attribute:: clean_bias :type: float :value: 0.0 Clean bias to subtract from the peak brightnesses (Jy/beam), see parapagraph 5.2.5 and equation 34 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: clean_bias_error :type: float :value: 0.0 1-sigma uncertainty in clean bias (Jy/beam), see parapagraph 5.2.5 and equation 37 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: deblend_mincont :type: float :value: 0.005 Minimum flux density fraction (relative to the original, i.e. unblended, island) required for a subisland to be considered a valid deblended component. .. !! processed by numpydoc !! .. py:attribute:: deblend_nthresh :type: int :value: 0 Number of deblending subthresholds; 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: detection_image :type: str | None :value: None Path to detection map. PySE will identify sources and the positions of pixels which comprise them on the detection image, but then use the corresponding pixels on the target images to perform measurements. Of course, the detection image and the target image(s) must have the same pixel dimensions. Note that only a single detection image may be specified, and the same pixels are then used on all target images. Note further that this detection-image option is incompatible with --fdr .. !! processed by numpydoc !! .. py:attribute:: detection_thr :type: float :value: 10.0 Detection threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image. .. !! processed by numpydoc !! .. py:attribute:: eps_dec :type: float :value: 0.0 Calibration uncertainty in declination (degrees), see equation 27b of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: eps_ra :type: float :value: 0.0 Calibration uncertainty in right ascension (degrees), see equation 27a of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: ew_sys_err :type: float :value: 0.0 Systematic error in east-west direction, see paragraph 5.2.3 of the NVSS paper. Note that this parameter is currently not applied in PySE, because it should be considered a final step before entering source parameters in a catalog, i.e. it is simply returned to allow for systematic positional offset cf. the NVSS. Therefore, its unit (degrees, arcseconds) is up to the user. .. !! processed by numpydoc !! .. py:attribute:: fdr :type: bool :value: False Use False Detection Rate (FDR) algorithm for determining detection threshold. .. !! processed by numpydoc !! .. py:attribute:: ffbox :type: float :value: 3.0 When fitting to a fixed position, a square “box” of pixels is chosen around the requested position, and the optimization procedure allows the source position to vary within that box. The size of the box may be changed with this option. Note that this parameter is given in units of the major axis of the beam in pixels. .. !! processed by numpydoc !! .. py:attribute:: fixed_posns :type: str | None :value: None JSON __list__ of RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements). .. !! processed by numpydoc !! .. py:attribute:: fixed_posns_file :type: str | None :value: None Path to JSON file with RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements). .. !! processed by numpydoc !! .. py:attribute:: force_beam :type: bool :value: False Force source shape to align restoring beam shape (bmaj, bmin, bpa) for Gauss fits and vetorized source measurement, i.e. when vectorized=True (as of 2025-06-13: upcoming, issue #131). .. !! processed by numpydoc !! .. py:attribute:: frac_flux_cal_error :type: float :value: 0.0 Intensity-proportional calibration uncertainty, see paragraph 5.2.5 and equation 37 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: grid :type: int | None :value: 64 Background subimage size used as fallback for back_size_x and back_size_y. If both are not set, this implies back_size_x=backsize_y=grid, i.e. the subimages are squares. .. !! processed by numpydoc !! .. py:attribute:: interpolate_order :type: int :value: 1 Order of interpolation to use for the background mean and background standard deviation (rms) maps (e.g. 1 for linear) .. !! processed by numpydoc !! .. py:attribute:: margin :type: int :value: 0 Margin in pixels to ignore near the edge of the image, i.e. sources within this margin will not be detected. .. !! processed by numpydoc !! .. py:attribute:: median_filter :type: int :value: 0 Size of the median filter to apply to background and RMS grids prior to interpolating. This is used to discard outliers. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: mf_threshold :type: int :value: 0 Threshold (Jy/beam) used with the median filter if median_filter is non-zero. This is used to only discard outliers (i.e. extreme background mean or rms node values) beyond a certain threshold. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: nr_threads :type: int | None :value: None The number of threads used to parallelize Gaussian fits to detected sources. Note: this does not change numba's 'num threads' for parallel numba operations. .. !! processed by numpydoc !! .. py:attribute:: ns_sys_err :type: float :value: 0.0 Systematic error in north-south direction, see paragraph 5.2.3 of the NVSS paper. Note that this parameter is currently not applied in PySE, because it should be considered a final step before entering source parameters in a catalog, i.e. it is simply returned to allow for systematic positional offset cf. the NVSS. Therefore, its unit (degrees, arcseconds) is up to the user. .. !! processed by numpydoc !! .. py:attribute:: radius :type: float :value: 0.0 Radius in pixels (from image center) considered valid, i.e. sources beyond this radius will not be detected. .. !! processed by numpydoc !! .. py:attribute:: remove_edge_sources :type: bool :value: True When source pixels - with values above the analysis threshold - connect with the edge of a map or with masked pixels, do not measure the source properties. Consequently, the parameters of this source will not be returned. The idea here is that, when source pixels are adjacent to edges or masked pixels, we'll likely be missing some pixels and any source measurement will be compromised. .. !! processed by numpydoc !! .. py:attribute:: rms_filter :type: float :value: 0.001 Any interpolated background standard deviation (rms) value should be above this threshold times the median of all background standard deviation (rms) node values. This is used to avoid picking up sources towards the edges of the image where the values of the background rms map may be the result of poor interpolation, i.e. are the result of extrapolation rather than interpolation. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: structuring_element :type: list[list[int]] :value: [[1, 1, 1], [1, 1, 1], [1, 1, 1]] The "structuring element" defines island connectivity as in "4-connectivity" and "8-connectivity". These two are the only reasonable choices, since the structuring element must be centrosymmetric. The structuring element is applied in scipy.ndimage.label, so check its documentation for some background on its use. .. !! processed by numpydoc !! .. py:attribute:: vectorized :type: bool :value: True Measure sources in a vectorized way. Expect peak spectral brightnesses with a lower bias (downwards) than for Gaussian fits (also downwards), but with a higher bias (upwards for both) for the elliptical axes. .. !! processed by numpydoc !! .. py:class:: LofarFitsImage(url, plane=False, beam=False, hdu=0) Bases: :py:obj:`sourcefinder.accessors.fitsimage.FitsImage`, :py:obj:`sourcefinder.accessors.lofaraccessor.LofarAccessor` Use PyFITS to pull image data out of a FITS file. Provide standard attributes, as per :class:`DataAccessor`. In addition, we provide a ``telescope`` attribute if the FITS file has a ``TELESCOP`` header. :Parameters: **url** : Path or str The path or URL to the FITS file. **plane** : int, default: None If the data is a datacube, specifies which plane to use. **beam** : tuple, default: None Beam parameters in degrees, in the form (bmaj, bmin, bpa). If not supplied, the method will attempt to read these from the header. **hdu_index** : int, default: 0 The index of the HDU to use from the HDU list. .. !! processed by numpydoc !! .. py:attribute:: antenna_set .. py:attribute:: ncore .. py:attribute:: nintl .. py:attribute:: nremote .. py:attribute:: subbands .. py:attribute:: subbandwidth .. py:function:: open(path, *args, **kwargs) Returns an accessor object (if available) for the file or directory 'path'. This function attempts to find an appropriate accessor for the given file or directory path. Accessors are tried in order from most specific to least specific. For example, an accessor providing `LofarAccessor` is preferred over one providing `DataAccessor`, but the latter will be used if no better match is found. :Parameters: **path** : str or HDUList The file path or HDUList object to be processed. **\*args** : tuple Additional positional arguments to pass to the accessor constructor. **\*\*kwargs** : dict Additional keyword arguments to pass to the accessor constructor. :Returns: DataAccessor or subclass An accessor object for the given file or directory. :Raises: OSError If the file does not exist, cannot be read, or no matching accessor class is found. Exception If the `path` parameter is neither a string nor an `HDUList`. .. !! processed by numpydoc !! .. py:function:: sourcefinder_image_from_accessor(image, conf: sourcefinder.config.Conf = Conf(image=ImgConf(), export=ExportSettings())) Create a sourcefinder.image.ImageData object from an image 'accessor'. This function initializes a `sourcefinder.image.ImageData` object using the data, beam, and WCS information provided by the given image accessor. :Parameters: **image** : DataAccessor FITS/AIPS/HDF5 image available through an accessor. **conf** : Conf, default: Conf(image=ImgConf(), export=ExportSettings()) Configuration options for source finding. This includes settings related to image processing (e.g., background and rms noise estimation, thresholds) as well as export options (e.g., source parameters and output maps). :Returns: ImageData A sourcefinder.image.ImageData object. .. !! processed by numpydoc !! .. py:function:: writefits(data, filename, header={}) Dump a NumPy array to a FITS file. This function writes a given NumPy array to a FITS file, optionally including header information. The header can be provided as a dictionary containing key-value pairs to be added to the FITS file's metadata. :Parameters: **data** : numpy.ndarray The NumPy array to be written to the FITS file. **filename** : Path or str The path to the output FITS file. **header** : dict, default: {} A dictionary containing key-value pairs for the FITS header. :Raises: OSError If the file cannot be written due to permission issues or other errors. .. rubric:: Notes The data is transposed before writing to match the transpose from `fitsimage.FitsImage.read_data()`. This is necessary to ensure that the data is stored in the correct orientation in the FITS file. .. !! processed by numpydoc !!