punchbowl.level1.alignment#

Attributes#

`_ROOT`
`HIPPARCOS_URL`

Functions#

`filter_distortion_table`(→ numpy.ndarray)	Filter a copy of the distortion lookup table.
`get_data_path`(→ str)	Get the path to the local data directory.
`load_hipparcos_catalog`() → pandas.DataFrame)	Load the Hipparcos catalog from the local, reduced version. This version only keeps necessary columns.
`load_raw_hipparcos_catalog`(→ pandas.DataFrame)	Download hipparcos catalog from the website. Not recommended for routine use.
`filter_for_visible_stars`(→ pandas.DataFrame)	Filter to only include stars brighter than a given magnitude.
`find_catalog_in_image`(→ pandas.DataFrame)	Convert the RA/DEC catalog into pixel coordinates using the provided WCS.
`find_star_coordinates`(→ numpy.ndarray)	Extract the coordinates of observed stars in an image using sep.
`astrometry_net_initial_solve`(, num_stars, ...)	Solve for the WCS of an image using Astrometry.net.
`_residual`(→ float)	Residual used when optimizing the pointing.
`extract_crota_from_wcs`(→ tuple[float, float])	Extract CROTA from a WCS.
`convert_cd_matrix_to_pc_matrix`(→ astropy.wcs.WCS)	Convert a WCS with a CD matrix to one with a PC matrix.
`refine_pointing_single_step`(→ astropy.wcs.WCS)	Perform a single step of pointing refinement.
`solve_pointing`(→ astropy.wcs.WCS)	Carefully refine the pointing of an image based on a guess WCS.
`measure_wcs_error`(→ float)	Estimate the error in the WCS based on an image.
`build_distortion_model`(→ astropy.wcs.WCS)	Create a distortion model from a set of PUNCH L0 images.
`align_task`(→ ndcube.NDCube)	Determine the pointing of the image and updates the metadata appropriately.

Module Contents#

punchbowl.level1.alignment._ROOT = b'.'#

punchbowl.level1.alignment.HIPPARCOS_URL = 'https://cdsarc.cds.unistra.fr/ftp/cats/I/239/hip_main.dat'#

punchbowl.level1.alignment.filter_distortion_table(data: numpy.ndarray, blur_sigma: float = 4, med_filter_size: float = 3) → numpy.ndarray[source]#

Filter a copy of the distortion lookup table.

Any rows/columns at the edges that are all NaNs will be removed and replaced with a copy of the closest non-removed edge at the end of processing.

Any NaN values that don’t form a complete edge row/column will be replaced with the median of all surrounding non-NaN pixels.

Then median filtering is performed across the whole map to remove outliers, and Gaussian filtering is applied to accept only slowly-varying distortions.

Parameters:

data – The distortion map to be filtered
blur_sigma (float) – The number of pixels constituting one standard deviation of the Gaussian kernel. Set to 0 to disable Gaussian blurring.
med_filter_size (int) – The size of the local neighborhood to consider for median filtering. Set to 0 to disable median filtering.

Notes

Modified from svank/wispr_analysis

punchbowl.level1.alignment.get_data_path(path: str) → str[source]#: Get the path to the local data directory.

punchbowl.level1.alignment.load_hipparcos_catalog(catalog_path: str = get_data_path('reduced_hip.csv')) → pandas.DataFrame[source]#

Load the Hipparcos catalog from the local, reduced version. This version only keeps necessary columns.

Parameters:: catalog_path (str) – path to the catalog, defaults to a provided version
Returns:: loaded catalog with selected columns
Return type:: pd.DataFrame

punchbowl.level1.alignment.load_raw_hipparcos_catalog(catalog_path: str = HIPPARCOS_URL) → pandas.DataFrame[source]#

Download hipparcos catalog from the website. Not recommended for routine use.

Parameters:: catalog_path (str) – path to the Hipparcos catalog
Returns:: loaded catalog with selected columns
Return type:: pd.DataFrame

punchbowl.level1.alignment.filter_for_visible_stars(catalog: pandas.DataFrame, dimmest_magnitude: float = 6) → pandas.DataFrame[source]#

Filter to only include stars brighter than a given magnitude.

Parameters:

catalog (pd.DataFrame) – a catalog loaded from ~load_hipparcos_catalog or ~load_raw_hipparcos_catalog
dimmest_magnitude (float) – the dimmest magnitude to keep

Returns:

a catalog with stars dimmer than the dimmest_magnitude removed

Return type:

pd.DataFrame`

punchbowl.level1.alignment.find_catalog_in_image(catalog: pandas.DataFrame, wcs: astropy.wcs.WCS, image_shape: tuple[int, int], mask: collections.abc.Callable | None = None, mode: str = 'all') → pandas.DataFrame[source]#

Convert the RA/DEC catalog into pixel coordinates using the provided WCS.

Parameters:

catalog (pd.DataFrame) – a catalog loaded from ~thuban.catalog.load_hipparcos_catalog or ~thuban.catalog.load_raw_hipparcos_catalog
wcs (WCS) – the world coordinate system of a given image
image_shape ((int, int)) – the shape of the image array associated with the WCS, used to only consider stars with coordinates in image
mask (Callable) – a function that indicates whether a given coordinate is included
mode (str) – either “all” or “wcs”, see <https://docs.astropy.org/en/stable/api/astropy.coordinates.SkyCoord.html#astropy.coordinates.SkyCoord.to_pixel>

Returns:

pixel coordinates of stars in catalog that are present in the image

Return type:

pd.DataFrame

punchbowl.level1.alignment.find_star_coordinates(image_data: numpy.ndarray, saturation_limit: float = np.inf, max_distance_from_center: float = 700, background_size: int = 16, detection_threshold: float = 5.0) → numpy.ndarray[source]#

Extract the coordinates of observed stars in an image using sep.

Parameters:

image_data (np.ndarray) – an array of an image
saturation_limit (float) – stars brighter than this are ignored
max_distance_from_center (float) – only returns stars at most this distance from the center of th eimage
background_size (int) – pixel size used by sep when building background model
detection_threshold (float) – number of sigma brighter than noise level a star must be for detection

Returns:

pixel coordinates of stars that are present in the image

Return type:

np.ndarray

punchbowl.level1.alignment.astrometry_net_initial_solve(observed_coords: numpy.ndarray, image_wcs: astropy.wcs.WCS, search_scales: tuple[int] = (14, 15, 16), num_stars: int = 150, lower_arcsec_per_pixel: float = 80.0, upper_arcsec_per_pixel: float = 100.0) → astropy.wcs.WCS | None[source]#

Solve for the WCS of an image using Astrometry.net.

Parameters:

observed_coords (np.ndarray) – pixel coordinates of stars in image, returned by find_star_coordinates
image_wcs (WCS) – best guess WCS
search_scales (tuple[int]) – scales to use for search, see neuromorphicsystems/astrometry
num_stars (int) – number of stars in the observed_coords to use for search
lower_arcsec_per_pixel (float) – lower guess on the platescale
upper_arcsec_per_pixel (float) – upper guess on the platescale

Returns:

the best WCS if search successful, otherwise None

Return type:

WCS | None

punchbowl.level1.alignment._residual(params: lmfit.Parameters, subcatalog: pandas.DataFrame, observed_coords: numpy.ndarray, guess_wcs: astropy.wcs.WCS, max_error: float = 30) → float[source]#

Residual used when optimizing the pointing.

Parameters:

params (Parameters) – optimization parameters from lmfit
observed_coords (np.ndarray) – pixel coordinates of stars observed in the image, i.e. the coordinates found by sep of the actual star location
subcatalog (pd.DataFrame) – image catalog of stars to match against
guess_wcs (WCS) – initial guess of the world coordinate system, must overlap with the true WCS
max_error (float) – stars more distant than this are complete misses, and their error is zeroed out

Returns:

residual

Return type:

np.ndarray

punchbowl.level1.alignment.extract_crota_from_wcs(wcs: astropy.wcs.WCS) → tuple[float, float][source]#: Extract CROTA from a WCS.

punchbowl.level1.alignment.convert_cd_matrix_to_pc_matrix(wcs: astropy.wcs.WCS) → astropy.wcs.WCS[source]#: Convert a WCS with a CD matrix to one with a PC matrix.

punchbowl.level1.alignment.refine_pointing_single_step(guess_wcs: astropy.wcs.WCS, observed_coords: numpy.ndarray, subcatalog: pandas.DataFrame, method: str = 'least_squares', ra_tolerance: float = 10, dec_tolerance: float = 5, fix_crval: bool = False, fix_crota: bool = False, fix_pv: bool = True) → astropy.wcs.WCS[source]#: Perform a single step of pointing refinement.

punchbowl.level1.alignment.solve_pointing(image_data: numpy.ndarray, image_wcs: astropy.wcs.WCS, distortion: astropy.wcs.WCS | None = None, saturation_limit: float = np.inf) → astropy.wcs.WCS[source]#: Carefully refine the pointing of an image based on a guess WCS.

punchbowl.level1.alignment.measure_wcs_error(image_data: numpy.ndarray, w: astropy.wcs.WCS, dimmest_magnitude: float = 6.0, max_error: float = 15.0) → float[source]#: Estimate the error in the WCS based on an image.

punchbowl.level1.alignment.build_distortion_model(l0_paths: list[str], dimmest_magnitude: float = 6.5, num_bins: int = 60, psf_transform: regularizepsf.ArrayPSFTransform | None = None) → astropy.wcs.WCS[source]#: Create a distortion model from a set of PUNCH L0 images.

punchbowl.level1.alignment.align_task(data_object: ndcube.NDCube, distortion_path: str | None) → ndcube.NDCube[source]#

Determine the pointing of the image and updates the metadata appropriately.

Parameters:

data_object (NDCube) – data object to align
distortion_path (str | None) – path to a distortion model

Returns:

a modified version of the input with the WCS more accurately determined

Return type:

NDCube