Metadata-Version: 2.1
Name: vasca
Version: 1.0.16
Summary: Ultraviolet Variability Analysis is an astronomy pipeline for time-variable sources.
Author-email: Julian Schliwinski <julian.schliwinski@desy.de>, Rolf Bühler <rolf.buehler@desy.de>
License: BSD 3-Clause License
        
        Copyright (c) 2023, Rolf Buehler
        
        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.
        
Project-URL: homepage, https://schliwiju.github.io/vasca-mirror/
Project-URL: documentation, https://schliwiju.github.io/vasca-mirror/
Project-URL: repository, https://github.com/rbuehler/vasca
Project-URL: changelog, https://tbd.desy.de
Keywords: astronomy,ultraviolet,pipeline
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy~=5.3
Requires-Dist: astroquery~=0.4.6
Requires-Dist: coverage~=7.2.7
Requires-Dist: healpy~=1.17
Requires-Dist: loguru~=0.7.0
Requires-Dist: matplotlib~=3.7.1
Requires-Dist: numpy~=1.24.3
Requires-Dist: pandas~=2.0.2
Requires-Dist: pytest~=7.3.1
Requires-Dist: pytest-cov~=4.1.0
Requires-Dist: python-dotenv~=1.0.0
Requires-Dist: PyYAML~=6.0
Requires-Dist: scikit-learn~=1.3.0
Requires-Dist: setuptools~=67.8.0
Requires-Dist: setuptools_scm
Requires-Dist: regions~=0.7
Requires-Dist: pyyaml-include~=1.3
Requires-Dist: ipywidgets~=8.0.6
Requires-Dist: ipympl~=0.9.3
Requires-Dist: jupyterlab~=4.0.2
Requires-Dist: sphinx~=7.2.6
Requires-Dist: myst-nb
Requires-Dist: furo
Requires-Dist: sphinx_autodoc2
Requires-Dist: sphinx_copybutton
Requires-Dist: sphinx-tippy
Requires-Dist: jupytext
Requires-Dist: itables


![VASCA icon](docs/images/VASCA_icon.png)
[![🧪 pytest](https://github.com/rbuehler/vasca/actions/workflows/ci.yml/badge.svg)](https://github.com/rbuehler/vasca/actions/workflows/ci.yml)
[![📚 docs](https://github.com/rbuehler/vasca/actions/workflows/docs.yml/badge.svg)](https://rbuehler.github.io/vasca/)
[![🚀 pypi](https://github.com/rbuehler/vasca/actions/workflows/pypi.yml/badge.svg)](https://pypi.org/project/vasca/)


# Variable Source Cluster Analysis (VASCA)

1. [Motivation](#motivation)
2. [Pipeline Overview](#pipeline-overview)
3. [Key Features](#key-features)
4. [Proof-of-Principle Study](#proof-of-principle-study)
5. [Documentation and Installation](#documentation-and-installation)
6. [Getting Started](docs/getting_started.md#getting-started)

## Motivation
VASCA (Italian for "bathtub" 🛁) is a high-performance software package developed to
address the challenges of time-domain astronomy, especially given the increasing volume
of data from large-scale surveys such as [ZTF](https://en.wikipedia.org/wiki/Zwicky_Transient_Facility),
[LSST](https://en.wikipedia.org/wiki/Vera_C._Rubin_Observatory), and [ULTRASAT](https://www.weizmann.ac.il/ultrasat/).
Designed to analyze time-variable cosmic sources like active galactic nuclei, stars, and
transient events, VASCA provides a modular, scalable solution for integrating data from
multiple instruments and conducting a cohesive analysis.

## Pipeline Overview

The VASCA analysis pipeline consists of three primary steps:
1. **Spatial Clustering**: Associate detections from repeated observations to unique
cosmic sources using [mean-shift](https://en.wikipedia.org/wiki/Mean_shift) clustering.
2. **Statistical Variability Detection**: Identify time-variable sources by testing flux
variations against a constant hypothesis at a 5-σ significance level.
3. **Source Classification**: Classify detected sources, including cross-matching with
external catalogs (e.g., SIMBAD, Gaia).

The main output of the pipeline is a catalog of time-variable cosmic
sources, including detailed classifications and cross-matches with existing astronomical
databases.

## Key Features

- **Simplicity and Modularity**: The software uses a hierarchical data model and modular
processing to ensure scalability and ease of use. It supports data from multiple
instruments seamlessly.
- **Proven Algorithms**: VASCA relies on established algorithms and statistical methods,
ensuring robustness and reducing the maintenance burden.
- **Focus on Specific Use Case**: Optimized for analyzing time-domain astronomical data,
VASCA keeps complexity low, simplifying auditing and debugging.
- **Standards Compliance**: Outputs are designed for publication readiness by adhering to
IAU and CDS standards, using widely-accepted, non-proprietary data formats. 
- **Customization and Extensibility**: VASCA allows flexible configuration, making it
adaptable to different datasets and instrument-specific requirements.

## Proof-of-Principle Study

VASCA was applied to a proof-of-principle study  using the Galaxy Evolution Explorer
(GALEX) archive (2003-2013). This study produced a catalog of over 4,000 UV-variable
sources, revealing UV variability across all classes of stars. Notably, a massive,
pulsating white dwarf exhibited unique long-term variability in the UV. The full article
including a description of VASCA's pipeline can be found here:
[The time-variable ultraviolet sky: Active galactic nuclei, stars, and white dwarfs](https://ui.adsabs.harvard.edu/abs/2024A%26A...687A.313B/abstract).

## Documentation and Installation

VASCA is distributed as an open-source package. Comprehensive documentation is available
[here](https://rbuehler.github.io/vasca/), including example notebooks and an API reference to help users get started.
For quick installation, VASCA can be installed via [PyPI](https://pypi.org/project/vasca/) using:
```shell
pip install vasca
```
For more info see the [installation guide](docs/getting_started.md#installation).
