dfcosmic

A high-performance Python package for cosmic ray removal strictly following the procedure outlined in van Dokkum 2001. Although several other implementations exist, their procedures differ slightly from that described in van Dokkum 2001. In this package, we use PyTorch to achieve considerable speedup over the original implementation while retaining fidelity to the algorithmic choices presented in the original paper.

Installation

Using PyPi

If you want to install using PyPi (which is certainly the easiest way), you can simply run

pip install dfcosmic

Installing from Source

For the latest development version, install directly from the GitHub repository:

git clone https://github.com/DragonflyTelescope/dfcosmic.git
cd dfcosmic
pip install -e .

Note: the CPU extensions (median filter + dilation) are compiled during install for speed. This requires a working C++ toolchain. If you need to pass custom OpenMP flags, you can do so via environment variables, for example:

export CXXFLAGS="-O3 -fopenmp -march=native"
export LDFLAGS="-fopenmp"
pip install -e .

For development installation with documentation dependencies:

pip install -e ".[docs]"

Basic Usage

We follow the same parameter naming conventions presented in the original IRAF code.

• objlim: The contrast limit between CR and underlying objects
• sigfrac: The fractional detection limit for neighboring pixels
• sigclip: The detection limit for cosmic rays

from dfcosmic import lacosmic

clean_image, crmask = lacosmic(
    image=original_data,
    objlim=2,
    sigfrac=1,
    sigclip=6,
    gain=1,
    readnoise=10,
    niter=1,
    device="cuda",
)

If you are unsure of either the gain or the readnoise you can leave them blank or set to 0. If so, then the gain will be estimated at each iteration.

Memory-Constrained CPU Runners

On small CPU runners, PyTorch CPU convolutions can request a large temporary workspace. dfcosmic supports two environment variables to force safer behavior:

export DFCOSMIC_CONVOLVE_DIRECT_MAX_NUMEL=0
export DFCOSMIC_MAX_MEMORY_MB=2048

• DFCOSMIC_CONVOLVE_DIRECT_MAX_NUMEL=0 forces CPU convolution onto the chunked path.
• DFCOSMIC_MAX_MEMORY_MB=2048 reduces chunk sizes in the main memory-heavy CPU steps to fit a rough 2 GB workspace budget.

For the tightest runners, also set cpu_threads=1 when calling lacosmic(...).

Simple Example

Timing Comparisons

We compare our pytorch implementation running on either a CPU (torch), CPU (torch & c++) or GPU with two popular cosmic ray removal codes: lacosmic and astroscrappy.

In order to run this timing comparison, we use the synthetic data described (and created) in the astroscrappy testing suite. The full notebook can be found in demos/Comparison.ipynb.

Running Tests

The unit tests can be run using the following command:

pytest

The default settings are in the pytest.ini file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Citation

If you use this package, please include a reference to the GitHub repository and the following Zenodo DOI: 10.5281/zenodo.18451351

License

The License for all past and present versions is the GPL-3.0.

AI Disclosure

Claude code was used to help with the unit tests only. CodeX was used to create only the c++ code for the median filter and make the code more memory efficient. Every line of code was manually inspected.