SNAD ZTF DR web viewer

https://ztf.snad.space

This projects contains a source of ZTF Data Releases light curve viewer developed by the SNAD team.

Please use the GitHub issue tracker for suggestions and bug reports. If the Portal is unavailable or some functionality doesn’t work, please check the status page. If it’s red, we are already aware of the problem; if not, please report it to us!

Evaluation

Both production and development versions can be started via Docker compose using docker-compose.yml and docker-compose.dev.yml correspondingly. Current production configuration assumes that there is a Docker proxy network shared with jwilder/nginx-proxy which proxies the webserver to the outer world. Also, this configuration requires secret.env file containing secret environment variables, such as API keys.

Environment variables

Environment variables to configure the server, see default values in config.py:

• CACHE_TYPE: cache type, specify redis to use redis server, or memory to use in-process cache
• UNAVAILABLE_CATALOGS_CACHE_TYPE: unavailable catalog cache type, specify redis to use redis server, or memory to use in-process cache
• REDIS_URL: redis server address (Redis 6.2+ required)
• LC_API_URL: SNAD ZTF database API address
• AKB_API_URL: knowledge database address
• FEATURES_API_URL: feature extraction service address
• OGLE_III_API_URL: SNAD OGLE III mirror address
• ZTF_PERIODIC_API_URL: SNAD mirror of the ZTF periodic variables catalog
• TNS_API_URL: SNAD mirror of the TNS
• ZTF_FITS_PROXY_URL: address of SNAD proxy for ZTF FITS
• JS9_URL: address of full-functional JS9 viewer supporting JS9.LoadProxy

Running development docker-compose

You could run a development version of the server at http://127.0.0.1:8050 using docker-compose.dev.yml file:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

This will run the Dash app under uvicorn (FastAPI/Starlette backend) in debug/reload mode, and will reload the server on code changes if you mount the source code directory ztf_viewer as a volume:

docker compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.dev.local.yml up --build

Running without docker

The server can be run locally without Docker in debug mode using uv. uv run syncs the .venv from uv.lock (see Dependencies) before running, so no separate install step is needed:

CACHE_TYPE="memory" UNAVAILABLE_CATALOGS_CACHE_TYPE="memory" uv run python -m ztf_viewer

Go to the url specified in the command line output, it should be something like http://localhost:8050/ Some features like FITS viewer wouldn't work.

Dependencies

Update JS9 version in Dockerfile.

Python dependencies are pinned in uv.lock, managed with uv. The lockfile is a universal, multi-platform lock covering x86_64 Linux (production), plus aarch64 Linux and arm64 macOS (development) — see [tool.uv].environments in pyproject.toml.

Add or change a dependency with uv add/uv remove (this updates both pyproject.toml and uv.lock), e.g.:

uv add "some-package>=1.0"

After editing pyproject.toml by hand, refresh the lockfile with:

uv lock

Commit uv.lock along with pyproject.toml.

Web-services used by the viewer

• SNAD catalog
• SNAD ZTF DR API gives HTTP access to SNAD ClickHouse installation of ZTF DR light curve database. Source code: https://github.com/snad-space/snad-ztf-db
• SNAD Light-curve feature API is a HTTP service to extract light-curve features using light-curve-feature Rust crate. Source code: https://github.com/snad-space/web-light-curve-features
• SNAD OGLE-III metadata API provides cone search within OGLE-III variable star catalog. Source code: https://github.com/snad-space/snad-ogle3
• SNAD ZTF Periodic Catalog API provides cone search within ZTF Catalog of Periodic Variable Stars. Source code: https://github.com/snad-space/ztf-periodic-catalog-db
• SNAD Transient Name Server API provides cone search within TNS. Source code: https://github.com/snad-space/snad-tns
• SNAD ZTF FITS Proxy is a FITS image service used by the embedded JS9 FITS viewer. Source code: https://github.com/snad-space/ztf-fits-proxy
• SNAD Anomaly Knowledge Base is an internal database for experts. Source code: https://github.com/snad-space/akb-backend
• NASA/IPAC Infrared Science Archive is a original source of ZTF FITS files
• Vizier is used to access various catalogs
• Simbad is used for both cone search and identifier queries
• Astrocats are used for cone search
• Astro-Colibri is used for multi-messenger events code search

Citation

Please cite our paper as well as papers describing the data you accessed through the Viewer

@ARTICLE{2023PASP..135b4503M,
       author = {{Malanchev}, Konstantin and {Kornilov}, Matwey V. and {Pruzhinskaya}, Maria V. and {Ishida}, Emille E.~O. and {Aleo}, Patrick D. and {Korolev}, Vladimir S. and {Lavrukhina}, Anastasia and {Russeil}, Etienne and {Sreejith}, Sreevarsha and {Volnova}, Alina A. and {Voloshina}, Anastasiya and {Krone-Martins}, Alberto},
        title = "{The SNAD Viewer: Everything You Want to Know about Your Favorite ZTF Object}",
      journal = {\pasp},
     keywords = {Variable stars, Astronomy software, Open source software, Publicly available software, Astronomy web services, 1761, 1855, 1866, 1864, 1856, Astrophysics - Instrumentation and Methods for Astrophysics},
         year = 2023,
        month = feb,
       volume = {135},
       number = {1044},
          eid = {024503},
        pages = {024503},
          doi = {10.1088/1538-3873/acb292},
archivePrefix = {arXiv},
       eprint = {2211.07605},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2023PASP..135b4503M},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}