### Set up ccdproc for development install

Source: https://github.com/astropy/ccdproc/blob/main/docs/install.rst

This command sets up a development installation of ccdproc. Changes made to the source code will be immediately reflected in the installed package without needing to reinstall.

```bash
pip install -e .
```

--------------------------------

### Build ccdproc from source

Source: https://github.com/astropy/ccdproc/blob/main/docs/install.rst

These commands build and install ccdproc from the source code. This is typically done after cloning the repository or downloading the source package.

```bash
python setup.py build
```

```bash
pip install .
```

--------------------------------

### Install ccdproc using pip

Source: https://github.com/astropy/ccdproc/blob/main/docs/install.rst

This command installs the ccdproc package and its dependencies using the pip package manager. Ensure pip is up-to-date for the best experience.

```bash
pip install ccdproc
```

--------------------------------

### ccdproc Image Combination with Scaling

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Demonstrates how to scale images before combining them. This is useful for normalizing images, for example, by their mean, before performing an average combination.

```python
scaling_func = lambda arr: 1/np.ma.average(arr)
combiner.scaling = scaling_func  # doctest: +IGNORE_WARNINGS
combined_average_scaled = combiner.average_combine()  # doctest: +IGNORE_WARNINGS
```

--------------------------------

### Print Astropy version

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Prints the currently installed version of the Astropy library.

```python
print('Astropy version: ', apy_version)
```

--------------------------------

### Install ccdproc using conda

Source: https://github.com/astropy/ccdproc/blob/main/docs/install.rst

This command installs the ccdproc package and its dependencies using the conda package manager from the conda-forge channel. This is recommended for users with Anaconda or Miniconda.

```bash
conda install -c conda-forge ccdproc
```

--------------------------------

### GET /image-collection/combine

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Demonstrates how to combine images managed by an ImageFileCollection using the Combiner class or the high-level combine function.

```APIDOC
## GET /image-collection/combine

### Description
Combines images retrieved from an ImageFileCollection. This can be done via the Combiner class or directly using the combine function.

### Method
GET

### Parameters
#### Query Parameters
- **mem_limit** (float) - Optional - Memory limit in bytes for the combination process.

### Request Example
GET /image-collection/combine?mem_limit=1e9

### Response
#### Success Response (200)
- **result** (object) - The combined CCDData object.
```

--------------------------------

### Test ccdproc source build

Source: https://github.com/astropy/ccdproc/blob/main/docs/install.rst

This command runs tests on a built ccdproc from the source code without installing the package. It's a way to verify the build integrity.

```bash
python setup.py test
```

--------------------------------

### Calculating CCDData Uncertainty

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Shows an example of how pixel-by-pixel uncertainty can be calculated for CCDData. This typically involves providing the data and potentially a scale factor or other parameters to a function that computes the uncertainty.

```python
import numpy as np
from astropy.nddata import CCDData

data = np.random.default_rng().normal(size=(10, 10), loc=1.0, scale=0.1)

# Example of creating CCDData with uncertainty (actual calculation method may vary)
# Assuming a function `calculate_uncertainty` exists or using astropy's capabilities
# ccd = CCDData(data, unit='adu', uncertainty=calculate_uncertainty(data))

# For demonstration, creating a placeholder uncertainty array
uncertainty_data = np.full_like(data, 0.1)
ccd_with_uncertainty = CCDData(data, unit='adu', uncertainty=uncertainty_data)
```

--------------------------------

### subtract_overscan: Remove Overscan Region from Image in Python

Source: https://context7.com/astropy/ccdproc/llms.txt

Provides an example of using `subtract_overscan` to remove the overscan region from a CCD image. The overscan region can be processed using averaging, median, or polynomial fitting before subtraction.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
from astropy.modeling import models
import ccdproc

# Create image with overscan region (100x110, last 10 columns are overscan)
data = np.ones((100, 110)) * 1000
data[:, 100:] = 50  # Overscan region with bias level
ccd = CCDData(data, unit=u.adu)


```

--------------------------------

### Initialize ImageFileCollection

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_management.rst

Demonstrates how to initialize an ImageFileCollection with a directory of FITS images and specify keywords to track. It also shows options for tracking all keywords or reading files to determine FITS format, and for filtering filenames using glob patterns.

```python
from ccdproc import ImageFileCollection
from ccdproc.utils.sample_directory import sample_directory_with_files
keys = ['imagetyp', 'object', 'filter', 'exposure']
dir = sample_directory_with_files()
ic1 = ImageFileCollection(dir, keywords=keys) # only keep track of keys
ic_all = ImageFileCollection(dir, keywords='*')
ic_from_content = ImageFileCollection(dir, find_fits_by_reading=True)
ic_all = ImageFileCollection(dir, glob_include='1d_*',
                             glob_exclude='*bad*')  # doctest: +IGNORE_WARNINGS
ic_names = ImageFileCollection(filenames=['a.fits', '/some/path/b.fits.gz'])
```

--------------------------------

### Build and Upload Package to PyPI

Source: https://github.com/astropy/ccdproc/wiki/Creating-a-new-release

Standard commands to build the distribution package and upload it to the Python Package Index using twine.

```bash
python -m build
twine upload dist/*
```

--------------------------------

### Combiner Initialization and Basic Usage

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Demonstrates how to initialize a Combiner object with a list of CCDData objects and provides an overview of its capabilities.

```APIDOC
## Combiner Initialization

### Description
Initializes a Combiner object with a list of CCDData objects. This object is used for image combination and mask generation.

### Method
`Combiner(ccd_data_list, mask=None, ...)`

### Parameters
- **ccd_data_list** (list of CCDData) - A list of CCDData objects to be combined.
- **mask** (CCDData, optional) - A mask to be applied to all images.

### Request Example
```python
from astropy import units as u
from astropy.nddata import CCDData
from ccdproc import Combiner
import numpy as np

# Create dummy CCDData objects
ccd1 = CCDData(np.random.default_rng().normal(size=(10,10)), unit=u.adu)
ccd2 = ccd1.copy()
ccd3 = ccd1.copy()

# Initialize Combiner
combiner = Combiner([ccd1, ccd2, ccd3])
```

### Response
#### Success Response (200)
- **Combiner object**: An instance of the ccdproc.Combiner class.

#### Response Example
```python
# The combiner object is ready for further operations
print(type(combiner))
```
```

--------------------------------

### CCDData Initialization and I/O

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Methods for creating CCDData objects from memory or reading from FITS files, and writing data back to disk.

```APIDOC
## CCDData Initialization and I/O

### Description
Create a CCDData object from array-like data or read from a FITS file. The object requires a unit to be specified.

### Method
POST / CCDData.read

### Parameters
#### Request Body
- **data** (array-like) - Required - The image data array.
- **unit** (str/Unit) - Required - The unit of the data (e.g., 'adu', 'photon').
- **filename** (str) - Optional - Path to FITS file for reading.
- **hdu** (int) - Optional - The FITS extension index to read.

### Request Example
{
  "data": [1, 2, 3],
  "unit": "adu"
}

### Response
#### Success Response (200)
- **ccd** (CCDData) - The initialized CCDData object.

#### Response Example
{
  "status": "success",
  "object": "CCDData"
}
```

--------------------------------

### Initialize ccdproc Combiner

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Demonstrates how to create an instance of the `Combiner` class from the `ccdproc` library, which is the first step for image combination. It takes a list of `CCDData` objects as input.

```python
from astropy import units as u
from astropy.nddata import CCDData
from ccdproc import Combiner
import numpy as np

ccd1 = CCDData(np.random.default_rng().normal(size=(10,10)),
               unit=u.adu)
cod2 = ccd1.copy()
cod3 = ccd1.copy()
combiner = Combiner([ccd1, ccd2, ccd3])
```

--------------------------------

### Reproject and Align Images via WCS

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Illustrates the process of aligning multiple images to a common WCS footprint using wcs_project before performing a stack.

```python
from ccdproc import wcs_project, Combiner

# Reproject list of images
reprojected = []
for img in my_list_of_images:
    new_image = wcs_project(img, target_wcs)
    reprojected.append(new_image)

# Combine aligned images
combiner = Combiner(reprojected)
stacked_image = combiner.average_combine()
```

--------------------------------

### Process Multi-Extension FITS Files

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Illustrates how to iterate over extensions in a Multi-Extension FITS (MEF) file to apply calibration steps like flat correction while preserving headers.

```python
from astropy.utils.data import get_pkg_data_filename
from astropy.io import fits
from astropy.nddata import CCDData
from ccdproc import flat_correct

science_name = get_pkg_data_filename('data/science-mef.fits', package='ccdproc.tests')
flat_name = get_pkg_data_filename('data/flat-mef.fits', package='ccdproc.tests')
science_mef = fits.open(science_name)
flat_mef = fits.open(flat_name)

new = []
new.append(science_mef[0])

for science_hdu, flat_hdu in zip(science_mef[1:], flat_mef[1:]):
    # Apply processing logic here
```

--------------------------------

### Perform an initial memory profile run

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Executes a single memory profiling run with the 'average' combination method and discards the result. This is done because the first run can have different characteristics than subsequent runs.

```python
_, _ = run_memory_profile(num_files, sampling_interval, size=image_size, 
                          memory_limit=memory_limit, combine_method='average')
```

--------------------------------

### Combine Images using ImageFileCollection

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Shows how to manage a folder of FITS files using ImageFileCollection and combine them using either the Combiner class or the high-level combine function.

```python
from ccdproc import ImageFileCollection, Combiner, combine

# Using Combiner class
c = Combiner(ifc.ccds())
avg_combined = c.average_combine()

# Using combine function with file paths
avg_combo_mem_lim = combine(ifc.files_filtered(include_path=True), mem_limit=1e9)

# Using combine function with CCDData objects
avg_combo = combine(ifc.ccds())
```

--------------------------------

### Create CCDData from FITS File

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Shows how to initialize a CCDData object by reading from a FITS file. The unit can be specified, overriding the BUNIT keyword in the FITS header if present. Allows specifying the HDU to read from.

```python
from astropy.nddata import CCDData

# Read from FITS file, specifying unit
ccd = CCDData.read('my_file.fits', unit="adu")

# Read from a specific HDU in the FITS file
ccd = CCDData.read('my_file.fits', hdu=1, unit="adu")
```

--------------------------------

### Apply Weighted Image Combination

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Demonstrates how to apply image-wise and pixel-wise weights to a Combiner object. Note that weighting is only supported for average or summation combination methods.

```python
import numpy as np
# Image-wise weighting
combiner.weights = np.array([0.5, 1, 2.0])
combine_weighted_by_image = combiner.average_combine()

# Pixel-wise weighting
combiner.weights = np.random.default_rng().random([3, 10, 10])
combine_weighted_by_pixel = combiner.average_combine()
```

--------------------------------

### Initialize data structure for profiling results

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Initializes a dictionary to store profiling results (times, memory usage, image size) for different combination methods ('average', 'median', 'sum'), including a deep copy for sigma clipping tests.

```python
runs = {
    'average': {
        'times': [],
        'memory': [],
        'image_size': 0.
    },
    'median': {
        'times': [],
        'memory': [],
        'image_size': 0.
    },
    'sum': {
        'times': [],
        'memory': [],
        'image_size': 0.
    }
}
runs_clip = deepcopy(runs)
```

--------------------------------

### Process image collections with custom array packages

Source: https://github.com/astropy/ccdproc/blob/main/docs/array_api.rst

Shows how to configure an ImageFileCollection to use a specific array library, such as Dask, for processing multiple FITS files. This ensures that subsequent operations like trimming or combination are performed using the specified library.

```python
import dask.array as da
import ccdproc
from astropy.nddata import CCDData

images = ccdproc.ImageFileCollection('path/to/images/*.fits', array_package=da)
for ccd in images.ccds():
    ccd = ccdproc.trim_image(ccd[:900, :900])
```

--------------------------------

### Iterate and Process Images with ImageFileCollection

Source: https://github.com/astropy/ccdproc/blob/main/docs/getting_started.rst

Demonstrates how to use `ImageFileCollection` to manage and process a collection of image files in a directory. It allows filtering images based on keywords and iterating through them for analysis. This is particularly useful for batch processing large datasets.

```python
from ccdproc import ImageFileCollection
import numpy as np
from glob import glob

dirs = glob('/Users/mcraig/Documents/Data/feder-images/fixed_headers/20*-??-??')

for d in dirs:
    print(d)
    ic = ImageFileCollection(d, keywords='*')
    for data, fname in ic.data(imagetyp='LIGHT', return_fname=True):
        if data.mean() > 4000.:
            print(fname)
```

--------------------------------

### POST /wcs/project

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Reprojects an image onto a target WCS footprint, enabling alignment of images before combination.

```APIDOC
## POST /wcs/project

### Description
Rescales and reprojects an input image to match a target WCS. This is a prerequisite step for stacking images with different coordinate systems.

### Method
POST

### Parameters
#### Request Body
- **input_image** (object) - Required - The source image data.
- **target_wcs** (object) - Required - The target WCS header or object.

### Request Example
{
  "input_image": "...",
  "target_wcs": "..."
}

### Response
#### Success Response (200)
- **reprojected_image** (object) - The transformed image data.
```

--------------------------------

### Combine images using a specific array library

Source: https://github.com/astropy/ccdproc/blob/main/docs/array_api.rst

Illustrates how to perform image combination using a chosen array library like Dask by passing the array_package argument to the combine_images function.

```python
import dask.array as da
import ccdproc
from astropy.nddata import CCDData

images = ccdproc.ImageFileCollection('path/to/images/*.fits', array_package=da)
combined = ccdproc.combine_images(images.ccds(), method='median')
```

--------------------------------

### ccd_process: Complete CCD Image Reduction Pipeline in Python

Source: https://context7.com/astropy/ccdproc/llms.txt

Illustrates the use of the `ccd_process` function to perform a full CCD data reduction pipeline. This includes overscan correction, trimming, gain correction, bias/dark/flat calibration, and error frame creation in a single call.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
import ccdproc

# Create sample data
raw_data = np.random.normal(loc=1000, scale=50, size=(100, 232))
ccd = CCDData(raw_data, unit=u.adu)
ccd.header['exposure'] = 30.0

# Create calibration frames
master_bias = CCDData(np.random.normal(size=(100, 200)), unit=u.electron)
master_dark = CCDData(np.random.normal(size=(100, 200)) * 0.1, unit=u.electron)
master_dark.header['exposure'] = 15.0
master_flat = CCDData(np.random.normal(loc=1.0, scale=0.05, size=(100, 200)), unit=u.electron)

# Complete processing pipeline
reduced = ccdproc.ccd_process(
    ccd,
    oscan='[201:232, 1:100]',      # Overscan region (FITS notation)
    trim='[1:200, 1:100]',          # Trim to this region
    error=True,                      # Create uncertainty array
    gain=2.0 * u.electron / u.adu,  # Apply gain correction
    readnoise=5 * u.electron,        # Read noise for uncertainty
    master_bias=master_bias,         # Subtract bias
    dark_frame=master_dark,          # Subtract dark
    exposure_key='exposure',         # Header keyword for exposure
    exposure_unit=u.second,          # Unit for exposure time
    dark_scale=True,                 # Scale dark by exposure ratio
    master_flat=master_flat          # Divide by flat field
)
```

--------------------------------

### Cherry-pick Merge Commits for Patching

Source: https://github.com/astropy/ccdproc/wiki/Creating-a-new-release

Demonstrates how to identify parent commits of a merge and apply specific fixes from master to a release branch using git cherry-pick with the -m flag.

```bash
git show 26b6050
git cherry-pick -m 1 26b6050
```

--------------------------------

### Process Dask arrays with ccdproc functions

Source: https://github.com/astropy/ccdproc/blob/main/docs/array_api.rst

Demonstrates how to initialize a CCDData object using a Dask array and perform image trimming. This approach allows users to leverage Dask's lazy evaluation for large datasets within the ccdproc workflow.

```python
import dask.array as da
import ccdproc
from astropy.nddata import CCDData

data = da.random.random((1000, 1000))
ccd = CCDData(data, unit='adu')
ccd = ccdproc.trim_image(ccd[:900, :900])
```

--------------------------------

### Execute memory profiling with sigma clipping

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Calls the `run_them` function to perform memory profiling for the 'average', 'median', and 'sum' combination methods with sigma clipping enabled.

```python
run_them(runs_clip, clipping=True)
```

--------------------------------

### Define profiling parameters for ccdproc

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Sets up parameters for memory profiling, including image size, number of files, sampling interval, memory limit, and retrieves the Git commit hash for identification.

```python
image_size = 4000   # Square image, so 4000 x 4000
num_files = 10
sampling_interval = 0.01 # sec
memory_limit = 1000000000  # bytes, roughly 1GB

commit = get_git_devstr(sha=True)[:7]
print(commit)
```

--------------------------------

### Select and Filter Images in ImageFileCollection

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_management.rst

Shows how to select images from an ImageFileCollection based on FITS header keyword values, using boolean logic or the convenience method `files_filtered`. It also covers using regular expressions for more flexible matching.

```python
matches = (ic1.summary['filter'] == 'R') & (ic1.summary['exposure'] < 15)
my_files = ic1.summary['file'][matches]
my_files = ic1.files_filtered(filter='R', exposure=15)
my_files = ic1.files_filtered(regex_match=True, object='kelt.*')
my_files = ic1.files_filtered(regex_match=True,
                              imagetyp='bias|light')
new_ic = ic1.filter(regex_match=True,
                    imagetyp='bias|light')
```

--------------------------------

### Working with CCDData Objects in Python

Source: https://context7.com/astropy/ccdproc/llms.txt

Demonstrates how to create, read, access, and write CCDData objects, the core data structure used by ccdproc. These objects store image data along with metadata, uncertainties, and masks.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData

# Create CCDData from numpy array
image = CCDData(np.ones((100, 100)), unit="adu")

# Read CCDData from FITS file
image = CCDData.read('my_image.fits', unit="electron")

# Access data, metadata, and slices
sub_image = image[:, 10:90]  # Returns CCDData object
raw_data = image.data[:, 10:90]  # Returns numpy array

# Write to FITS file
image.write('output.fits', overwrite=True)
```

--------------------------------

### Generate FITS files for testing

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Generates a specified number of FITS files with a given size, used as input for memory profiling tests.

```python
generate_fits_files(num_files, size=image_size)
```

--------------------------------

### Image Masking with Clipping Techniques

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Explains and demonstrates the different clipping methods available in ccdproc for generating masks.

```APIDOC
## Image Masking and Clipping

### Description
These methods generate masks for pixels based on various clipping criteria. These masks are then used during image combination. Masking done by clipping operations is combined with the image mask provided when the `Combiner` is created.

### Min/Max Clipping

#### Description
Masks all pixels above or below user-specified levels.

#### Method
`combiner.minmax_clipping(min_clip=None, max_clip=None)`

#### Parameters
- **min_clip** (float, optional) - The minimum value threshold. Pixels below this value will be masked.
- **max_clip** (float, optional) - The maximum value threshold. Pixels above this value will be masked.

#### Request Example
```python
combiner.minmax_clipping(min_clip=-0.3, max_clip=0.1)
```

### Sigma Clipping

#### Description
Masks pixels that deviate significantly from the central value (e.g., median or mean) across the stack of images.

#### Method
`combiner.sigma_clipping(low_thresh=3.0, high_thresh=3.0, func=np.ma.mean, **kwargs)`

#### Parameters
- **low_thresh** (float) - The number of standard deviations below the central value to mask.
- **high_thresh** (float) - The number of standard deviations above the central value to mask.
- **func** (callable) - The function to calculate the central value (e.g., `np.ma.median`, `np.ma.mean`).
- **kwargs**: Additional keyword arguments passed to the `func`.

#### Request Example
```python
combiner.sigma_clipping(low_thresh=2, high_thresh=5, func=np.ma.median)
```

### Extrema Clipping

#### Description
Masks the lowest `nlow` and highest `nhigh` pixel values for each pixel position across the input arrays.

#### Method
`combiner.clip_extrema(nlow=0, nhigh=0)`

#### Parameters
- **nlow** (int) - The number of lowest pixel values to mask.
- **nhigh** (int) - The number of highest pixel values to mask.

#### Request Example
```python
combiner.clip_extrema(nlow=1, nhigh=2)
```

### Iterative Clipping

#### Description
Applies a clipping method iteratively until no more pixels are rejected.

#### Method
Requires looping around a clipping method (e.g., `sigma_clipping`).

#### Request Example
```python
old_n_masked = 0
new_n_masked = combiner.mask.sum()
while (new_n_masked > old_n_masked):
    combiner.sigma_clipping(func=np.ma.median)
    old_n_masked = new_n_masked
    new_n_masked = combiner.mask.sum()
```
```

--------------------------------

### Manage FITS Collections with ImageFileCollection

Source: https://context7.com/astropy/ccdproc/llms.txt

Facilitates the organization and filtering of FITS files in a directory based on header keywords. Useful for batch processing.

```python
from ccdproc import ImageFileCollection

ic = ImageFileCollection('/path/to/data', keywords=['imagetyp', 'filter', 'exptime'])
bias_files = ic.files_filtered(imagetyp='BIAS', include_path=True)
flat_files = ic.files_filtered(imagetyp='flat.*', regex_match=True, include_path=True)
print(ic.summary)
```

--------------------------------

### BibTeX Entry for ccdproc v1.3.0.post1

Source: https://github.com/astropy/ccdproc/blob/main/CITATION.rst

This BibTeX entry is for citing a specific version (v1.3.0.post1) of the ccdproc package. It includes author information, title, month, year, DOI, and URL for the Zenodo record.

```bibtex
@misc{matt_craig_2017_1069648,
    author       = {Matt Craig and Steve Crawford and Michael Seifert and
                    Thomas Robitaille and Brigitta Sip{\H o}cz and
                    Josh Walawender and Z`e Vin{\'i}cius and Joe Philip Ninan and Michael Droettboom and Jiyong Youn and
                    Erik Tollerud and Erik Bray and
                    Nathan Walker and VSN Reddy Janga and
                    Connor Stotts and Hans Moritz G{"u}nther and Evert Rol and
                    Yoonsoo P. Bach and Larry Bradley and Christoph Deil and
                    Adrian Price-Whelan and Kyle Barbary and Anthony Horton and
                    William Schoenell and Nathan Heidt and Forrest Gasdia and
                    Stefan Nelson and Ole Streicher},
    title        = {astropy/ccdproc: v1.3.0.post1},
    month        = dec,
    year         = 2017,
    doi          = {10.5281/zenodo.1069648},
    url          = {https://doi.org/10.5281/zenodo.1069648}
}
```

--------------------------------

### Combine Images with Convenience Function

Source: https://context7.com/astropy/ccdproc/llms.txt

A high-level function for combining image lists. It handles memory management for large datasets and supports direct file I/O.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
from ccdproc import combine

images = [CCDData(np.random.normal(100, 10, (50, 50)), unit=u.adu) for _ in range(5)]
master = combine(images, method='median', sigma_clip=True, sigma_clip_low_thresh=3, sigma_clip_high_thresh=3)

master_file = combine(['image1.fits', 'image2.fits'], method='median', mem_limit=4e9, output_file='master.fits', overwrite_output=True)
```

--------------------------------

### Apply CCDMask Task

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Uses the ccdproc.ccdmask function to generate a mask where good pixels are zero and bad pixels are one, following the IRAF ccdmask algorithm.

```python
ccd.mask = ccdproc.ccdmask(ccd, ncmed=7, nlmed=7, ncsig=15, nlsig=15, lsigma=9, hsigma=9, ngood=5)
```

--------------------------------

### Sort Images in ImageFileCollection

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_management.rst

Illustrates how to sort the images within an ImageFileCollection based on specified FITS header keywords, similar to sorting an Astropy Table.

```python
ic1.sort(['exposure', 'imagetyp'])
```

--------------------------------

### Writing CCDData to FITS

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Demonstrates how to convert a CCDData object to a FITS HDU list and write it directly to a FITS file. Metadata from the CCDData object is converted to the FITS header.

```python
from astropy.nddata import CCDData

ccd_masked = CCDData([1, 2, 3], unit="adu", mask=[0, 0, 1])

# Convert to FITS HDU list
hdulist = ccd_masked.to_hdu()

# Write directly to a FITS file
ccd_masked.write('my_image.fits')
```

--------------------------------

### Subtract Overscan from CCD Image

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Demonstrates how to subtract overscan from an image using either Python-style array slicing or FITS/IRAF section strings. It also shows how to apply a polynomial model to the overscan region for more advanced subtraction.

```python
# python-style indexing
oscan_subtracted = ccdproc.subtract_overscan(cr_cleaned, overscan=cr_cleaned[:, 200:], overscan_axis=1)

# FITS/IRAF-style indexing
oscan_subtracted = ccdproc.subtract_overscan(cr_cleaned, fits_section='[201:232,1:100]', overscan_axis=1)

# Using a polynomial model
from astropy.modeling import models
poly_model = models.Polynomial1D(1)
oscan_subtracted = ccdproc.subtract_overscan(cr_cleaned, overscan=cr_cleaned[:, 200:], overscan_axis=1, model=poly_model)
```

--------------------------------

### Create CCDData from Array

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Demonstrates how to create a CCDData object from a NumPy array. Requires a unit to be specified, which can be a string or an astropy Unit object. Supports dimensionless units.

```python
import numpy as np
from astropy.nddata import CCDData
from astropy import units as u

# From numpy array with string unit
ccd = CCDData(np.arange(10), unit="adu")

# From list with astropy Unit object
ccd_photon = CCDData([1, 2, 3], unit=u.photon)

# From list with string unit
ccd_electron = CCDData([1, 2, 3], unit="electron")

# With dimensionless unit
ccd_unitless = CCDData(np.zeros((10, 10)), unit=u.dimensionless_unscaled)
```

--------------------------------

### Create Deviation and Assign Uncertainty to CCDData

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Demonstrates how to generate a deviation map using ccdproc.create_deviation and how to manually assign uncertainty to a CCDData object using StdDevUncertainty or a numpy array.

```python
from astropy.nddata import CCDData
import ccdproc
from astropy import units as u
from astropy.nddata.nduncertainty import StdDevUncertainty

# Create deviation
ccd = CCDData(data, unit="electron")
ccd_new = ccdproc.create_deviation(ccd, readnoise=5 * u.electron)

# Assign uncertainty using StdDevUncertainty
uncertainty = 0.1 * ccd.data
my_uncertainty = StdDevUncertainty(uncertainty)
ccd.uncertainty = my_uncertainty

# Assign uncertainty using numpy array
ccd.uncertainty = 0.1 * ccd.data
```

--------------------------------

### Setting CCDData Metadata

Source: https://github.com/astropy/ccdproc/blob/main/docs/ccddata.rst

Explains how to set metadata (header information) for a CCDData object. Metadata can be provided as a dictionary during initialization or assigned to the .header or .meta attributes after creation. FITS headers are case-insensitive, while Python dictionaries are case-sensitive.

```python
import numpy as np
from astropy.nddata import CCDData

ccd_simple = CCDData(np.arange(10), unit="adu")
my_meta = {'observer': 'Edwin Hubble', 'exposure': 30.0}

# Assign metadata using .header attribute
ccd_simple.header = my_meta

# Alternatively, use .meta attribute
ccd_simple.meta = my_meta
```

--------------------------------

### Read CCDData Object from FITS File

Source: https://github.com/astropy/ccdproc/blob/main/docs/getting_started.rst

Shows how to create a CCDData object by reading data from a FITS file. This method is crucial for loading existing astronomical images. The 'electron' unit is defined as part of ccdproc.

```python
from astropy.nddata import CCDData

image_2 = CCDData.read('my_image.fits', unit="electron")
```

--------------------------------

### Import necessary libraries for ccdproc memory profiling

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Imports essential libraries such as gc, deepcopy, matplotlib, numpy, and specific functions from run_for_memory_profile and ccdproc. It also includes error handling for missing dependencies.

```python
import gc
from copy import deepcopy

%matplotlib inline 
from matplotlib import pyplot as plt
import numpy as np

try:
    from run_for_memory_profile import run_memory_profile, generate_fits_files
except ImportError:
    raise ImportError('Please install memory_profiler before running this notebook.')

from ccdproc.version import get_git_devstr
from astropy import __version__ as apy_version
```

--------------------------------

### gain_correct: Apply Gain Correction to CCD Data in Python

Source: https://context7.com/astropy/ccdproc/llms.txt

Demonstrates the `gain_correct` function for converting CCD image data from ADU to electrons by multiplying with the gain factor. It also correctly scales the associated uncertainty array.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
import ccdproc

# Create sample data in ADU
data = CCDData(np.ones((100, 100)) * 1000, unit=u.adu)

# Apply gain correction
gain_corrected = ccdproc.gain_correct(
    data,
    gain=1.5 * u.electron / u.adu
)

# Result is now in electrons
print(gain_corrected.unit)  # electron
print(gain_corrected.data[0, 0])  # 1500.0
```

--------------------------------

### Reproject Image to Different WCS

Source: https://context7.com/astropy/ccdproc/llms.txt

Reproject an image onto a target WCS footprint. Useful for image alignment and creating mosaics from multiple exposures.

```python
import ccdproc
from astropy.wcs import WCS

target_wcs = WCS(naxis=2)
target_wcs.wcs.crpix = [50, 50]
target_wcs.wcs.cdelt = [0.001, 0.001]
target_wcs.wcs.crval = [180.0, 45.0]
target_wcs.wcs.ctype = ['RA---TAN', 'DEC--TAN']

reprojected = ccdproc.wcs_project(input_image, target_wcs, target_shape=(100, 100), order='bilinear')
```

--------------------------------

### Trim CCD Image

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Shows how to trim an image to remove the overscan region using both Python and FITS-style indexing conventions.

```python
# FITS-style trimming
trimmed = ccdproc.trim_image(oscan_subtracted, fits_section='[1:200, 1:100]')
```

--------------------------------

### Apply Median Filter with ccdproc

Source: https://context7.com/astropy/ccdproc/llms.txt

Demonstrates how to apply a median filter to a CCDData object or a numpy array to mitigate noise spikes. This function preserves edges while smoothing the image data.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
import ccdproc

# Create image with noise spikes
data = np.random.normal(100, 10, (100, 100))
data[50, 50] = 10000  # Noise spike
ccd = CCDData(data, unit=u.adu)

# Apply median filter
filtered = ccdproc.median_filter(ccd, size=5)

# The spike is removed/reduced
print(f"Original spike: {ccd.data[50, 50]}")
print(f"After filtering: {filtered.data[50, 50]}")

# For numpy arrays
filtered_array = ccdproc.median_filter(data, size=5)
```

--------------------------------

### Create CCDData Object from Numpy Array

Source: https://github.com/astropy/ccdproc/blob/main/docs/getting_started.rst

Demonstrates how to initialize a CCDData object from a NumPy array. This object is fundamental for storing and processing astronomical image data within the ccdproc framework. It requires the numpy and astropy units libraries.

```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData

image_1 = CCDData(np.ones((10, 10)), unit="adu")
```

--------------------------------

### Execute memory profiling without sigma clipping

Source: https://github.com/astropy/ccdproc/blob/main/ccdproc/tests/run_profile.ipynb

Calls the `run_them` function to perform memory profiling for the 'average', 'median', and 'sum' combination methods without sigma clipping.

```python
run_them(runs)
```

--------------------------------

### Reproject Image to Different WCS

Source: https://github.com/astropy/ccdproc/blob/main/docs/getting_started.rst

Explains the usage of the `wcs_project` function, which allows for the reprojection of an astronomical image onto a different World Coordinate System (WCS). This is useful for aligning images with different spatial references.

```python
import ccdproc

# Assuming 'image' is a CCDData object with WCS information
# and 'new_wcs' is the target WCS object
# projected_image = ccdproc.wcs_project(image, new_wcs)
```

--------------------------------

### Flat Correction for Astronomical Images

Source: https://github.com/astropy/ccdproc/blob/main/docs/getting_started.rst

Demonstrates how to perform flat correction on an image using the `flat_correct` function. This operation divides the image by a flat field image, propagating uncertainties if they are set. It requires the image to be corrected and the flat field image as input.

```python
import ccdproc
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData

# Assuming image_1 is a CCDData object
image_1 = CCDData(np.ones((10, 10)), unit="adu") # Placeholder

flat = CCDData(np.random.default_rng().normal(1.0, scale=0.1, size=(10, 10)),
               unit='adu')

image_1_flat = ccdproc.flat_correct(image_1, flat)
```

--------------------------------

### POST /combiner/weights

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Configures weighting for image combination. Supports both image-level weighting (array of length N) and pixel-wise weighting (array of shape N x H x W).

```APIDOC
## POST /combiner/weights

### Description
Sets the weights for the Combiner instance. Weighting is only supported for average or summation combination methods.

### Method
POST

### Parameters
#### Request Body
- **weights** (array) - Required - An array of floats representing weights. Can be 1D for image-wise weighting or 3D for pixel-wise weighting.

### Request Example
{
  "weights": [0.5, 1.0, 2.0]
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of weight application.
```

--------------------------------

### Automated CCD Processing Pipeline

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Executes a complete processing workflow in a single command, including overscan correction, trimming, gain correction, uncertainty estimation, bias subtraction, and flat-fielding.

```python
nccd = ccdproc.ccd_process(ccd, oscan='[201:232,1:100]', trim='[1:200, 1:100]', error=True, gain=2.0*u.electron/u.adu, readnoise=5*u.electron, dark_frame=master_dark, exposure_key='exposure', exposure_unit=u.second, dark_scale=True, master_flat=master_flat)
```

--------------------------------

### Push Changes and Tags to Remote Repository

Source: https://github.com/astropy/ccdproc/wiki/Creating-a-new-release

Commands to push code changes, specific release tags, and new branches to the upstream astropy/ccdproc repository.

```bash
git push -v https://github.com/astropy/ccdproc.git main:main
git push -v https://github.com/astropy/ccdproc.git 2.1.0
git push -v https://github.com/astropy/ccdproc.git 2.1.x:2.1.x
```

--------------------------------

### Convert FITS Bitfield to Boolean Mask

Source: https://github.com/astropy/ccdproc/blob/main/docs/reduction_toolbox.rst

Demonstrates how to extract a bitfield extension from a FITS file and convert it into a boolean mask compatible with CCDData objects. This is necessary because CCDData does not natively support bitfield extensions.

```python
import numpy as np
from astropy.io import fits
from ccdproc import bitfield_to_boolean_mask, CCDData

fitsfilename = 'some_fits_file.fits'
bitfieldextension = extensionname_or_extensionnumber

# Read the data of the fits file as CCDData object
ccd = CCDData.read(fitsfilename)

# Open the file again (assuming the bitfield is saved in the same FITS file)
mask = bitfield_to_boolean_mask(fits.getdata(fitsfilename, bitfieldextension))

# Save the mask as "mask" attribute of the ccd
ccd.mask = mask
```

--------------------------------

### combine - Convenience Function for Image Combination

Source: https://context7.com/astropy/ccdproc/llms.txt

A high-level convenience function for combining images, designed to manage memory efficiently for large datasets.

```APIDOC
## ccdproc.combine

### Description
A high-level convenience function that combines images with memory management for large datasets. It supports various combination methods and clipping algorithms.

### Method
`ccdproc.combine`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **images** (list of CCDData or list of file paths) - A list of CCDData objects or FITS file paths to be combined.
- **method** (str, optional) - The combination method ('average', 'median', 'sum'). Defaults to 'average'.
- **mem_limit** (int, optional) - Memory limit in bytes for processing large datasets. Defaults to None.
- **sigma_clip** (bool, optional) - Whether to apply sigma clipping. Defaults to False.
- **sigma_clip_low_thresh** (float, optional) - Lower threshold for sigma clipping.
- **sigma_clip_high_thresh** (float, optional) - Upper threshold for sigma clipping.
- **sigma_clip_func** (callable, optional) - Function to use for sigma clipping (e.g., np.ma.median).
- **sigma_clip_dev_func** (callable, optional) - Function to calculate deviation for sigma clipping (e.g., np.ma.std).
- **minmax_clip** (bool, optional) - Whether to apply min/max clipping. Defaults to False.
- **minmax_clip_min** (float, optional) - Minimum value for min/max clipping.
- **minmax_clip_max** (float, optional) - Maximum value for min/max clipping.
- **clip_extrema** (bool, optional) - Whether to clip extreme values. Defaults to False.
- **nlow** (int, optional) - Number of lowest values to clip.
- **nhigh** (int, optional) - Number of highest values to clip.
- **scale** (callable, optional) - A function to scale images before combining (e.g., lambda arr: 1 / np.median(arr)).
- **output_file** (str, optional) - Path to save the combined image.
- **overwrite_output** (bool, optional) - Whether to overwrite the output file if it exists. Defaults to False.

### Request Example
```python
import numpy as np
from astropy import units as u
from astropy.nddata import CCDData
from ccdproc import combine

# Create sample images
images = [CCDData(np.random.normal(100, 10, (50, 50)), unit=u.adu) for _ in range(5)]

# Simple average combine
master = combine(images, method='average')

# Median combine with sigma clipping
master = combine(
    images,
    method='median',
    sigma_clip=True,
    sigma_clip_low_thresh=3,
    sigma_clip_high_thresh=3,
    sigma_clip_func=np.ma.median,
    sigma_clip_dev_func=np.ma.std
)

# Average with minmax clipping
master = combine(
    images,
    method='average',
    minmax_clip=True,
    minmax_clip_min=-100,
    minmax_clip_max=500
)

# Combine with extrema clipping and scaling
master = combine(
    images,
    method='average',
    clip_extrema=True,
    nlow=1,
    nhigh=1,
    scale=lambda arr: 1 / np.median(arr)
)

# Combine from file list with memory limit
master = combine(
    ['image1.fits', 'image2.fits', 'image3.fits'],
    method='median',
    mem_limit=4e9,  # 4 GB memory limit
    sigma_clip=True
)

# Write output directly to file
master = combine(
    images,
    output_file='master_bias.fits',
    method='average',
    overwrite_output=True
)
```

### Response
#### Success Response (200)
- **master_image** (CCDData) - The combined image.

#### Response Example
```json
{
  "master_image": "CCDData object representing the combined image"
}
```
```

--------------------------------

### Image Combination Methods

Source: https://github.com/astropy/ccdproc/blob/main/docs/image_combination.rst

Details the methods for combining images after masks have been generated.

```APIDOC
## Image Combination

### Description
Combines the images within the Combiner object using specified methods, respecting any generated masks.

### Average Combination

#### Description
Combines images by taking the average, excluding masked pixels.

#### Method
`combiner.average_combine()`

#### Request Example
```python
combined_average = combiner.average_combine() # doctest: +IGNORE_WARNINGS
```

### Median Combination

#### Description
Combines images by taking the median, excluding masked pixels. This can be computationally intensive.

#### Method
`combiner.median_combine()`

#### Request Example
```python
combined_median = combiner.median_combine() # doctest: +IGNORE_WARNINGS
```

### Combination with Image Scaling

#### Description
Allows scaling of all images to a common value before combination. This is useful for normalizing images before averaging or median combining.

#### Method
Set the `combiner.scaling` attribute to a callable function.

#### Parameters
- **combiner.scaling** (callable) - A function that takes an array and returns a scaling factor or scaled array.

#### Request Example
```python
# Example: Normalize each image by its mean before combining
scaling_func = lambda arr: 1/np.ma.average(arr)
combiner.scaling = scaling_func
combined_average_scaled = combiner.average_combine() # doctest: +IGNORE_WARNINGS
```
```