ysfitsutilpy

Convenience utilities made by ysBach especially for dealing FITS files in astronomical sciences.

Please always refer to GitHub repo for the most recent updates.

Why "ys"fitsutilpy? The name "fitsutilpy" is too general, and I believe a better package should take that name, so I decided not to occupy the name. I see many useless packages that preoccupy meaningful names...

Install by

$ pip install ysfitsutilpy

or

$ cd <where you want to download this package>
$ git clone https://github.com/ysBach/ysfitsutilpy
$ cd ysfitsutilpy
$ git pull && pip install -e .

From the second time, just run the last line.

This package is made to be used for

• Preprocessing (= bias, dark, and flat) of imaging data (not tested for spectroscopy yet)
• Simple analysis of FITS files by making summary csv file, getting statistics (misc.give_stats), etc.
• Educational purpose
• ...

Although I tried to make some functions as general as possible, this package as a whole is not designed for very general use, e.g., MEF (multi-extension FITS) and radio data, for instance. MEF is somewhat treatable in current version, but not satisfactorily yet.

You may import using import ysfitsutilpy as yfu.

An example usage to make a summary file of FITS files:

import ysfitsutilpy as yfu

summary = yfu.make_summary(
    "observation_2018-01-01/R*.fits",
    keywords=["DATE-OBS", "FILTER", "OBJECT"],  # header keywords; actually it is case-insensitive
    fname_option='name',  # 'file' column will contain only the name of the file (not full path)
    sort_by="DATE-OBS",  # 'file' column will be sorted based on "DATE-OBS" value in the header
    output="summary_2018-01-01.csv",
)

summary
# shows results of the summary CSV file.

A simple example to combine multiple images:

import ysfitsutilpy as yfu

comb = yfu.imcombine(
    "observation_2018-01-01/R*M101*.fits",
    combine="med",  # med, median | avg, mean, average | sum
    reject="sc",  # sc, sigc, sigclip, ... | ccd, ccdc, ccdclip
    sigma=[2, 2],  # default is [3., 3.]
    offset="wcs",  # combine by integer shift based on WCS information in headers
    output="combined.fits",
    output_err="comb_err.fits",  # errormap of survived pixels
    output_mask="comb_mask.fits",  # N+1-dimensional mask of the rejected pixel positions
    output_nrej="comb_nrej.fits",  # number of pixels rejected in the output file.
    output_low="comb_low.fits",  # the lower limit used in pixel value rejection
    output_upp="comb_upp.fits",  # the upper limit used in pixel value rejection
    output_rejcode="comb_rejcode.fits",  # represents what rejection has happened (see docstring)
    full=True,
    verbose=True
)

A quick dark combine:

import ysfitsutilpy as yfu

# Say dark frames have header OBJECT = "calib" && "IMAGE-TYP" = "DARK"
comb = yfu.group_combine(
    "observation_2018-01-01/*DARK*.fits",
    type_key=["OBJECT", "IMAGE-TYP"],
    type_val=["calib", "DARK"],
    group_key=["FILTER", "EXPTIME"],
    fmt="dark_{:s}_{:.1f}sec.fits",  # output file name format
    outdir="cal-dark"  # output directory (will automatically be made if not exist)
)

BSD 3-Clause License

Copyright (c) 2020, Yoonsoo P. Bach All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.