timewise 1.0.0

Download WISE infrared data for many objects and process them with AMPEL

Infrared light curves from WISE data

This package downloads WISE data for positions on the sky and stacks single-exposure photometry per visit. It is designed to do so efficiently for large samples of millions of objects.

Prerequisites

Python version 3.11, 3.12 or 3.13.

If you want to not only download individual exposure photometry but also stack detections per visit (see below), you must have access to a running MongoDB* **.

_{* On MacOS have alook at the custom brew tap here to get the MongoDB community edition.}

_{** On some systems this is not straight forward to set up. timewise requires it nevertheless as an integral part of the AMPEL system which is used to efficiently schedule and store the stacking of lightcurves. If you do not foresee a big overhead in calculating lightcurves for a sample of O(1000) objects, a more lightweight package might be more applicable.}

Installation

If you use timewise only for downloading

The package can be installed via pip (but make sure to install the v1 pre-release):

pip install timewise

If you use timewise also for stacking individual exposures

You must install with the ampel extra:

pip install timewise[ampel]

To tell AMPEL which modules, aka units, to use, build the corresponding configuration file:

ampel config build -distributions ampel timewise -stop-on-errors 0 -out <path-to-ampel-config-file>

Command line interface

Read the short description below or have a look at the example notebook(s):

 Usage: timewise [OPTIONS] COMMAND [ARGS]...                                                                
                                                                                                            
 Timewsie CLI                                                                                               
                                                                                                            
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --log-level           -l      TEXT  Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)                │
│                                     [default: INFO]                                                      │
│ --install-completion                Install completion for the current shell.                            │
│ --show-completion                   Show completion for the current shell, to copy it or customize the   │
│                                     installation.                                                        │
│ --help                              Show this message and exit.                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ download        Download WISE photometry from IRSA                                                       │
│ prepare-ampel   Prepares the AMPEL job file so AMPEL can be run manually                                 │
│ process         Processes the lightcurves using AMPEL                                                    │
│ export          Write stacked lightcurves to disk                                                        │
│ run-chain       Run download, process and export                                                         │
│ plot            Make diagnostic plots                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The input is a CSV file with at least three columns:

• orig_id: an original identifier that must be an integer (for now)
• ra, dec: Right Ascension and Declination

timewise is configured with a YAML file. This is a sensible default which will use all single exposure photometry from AllWISE and NEOWISE:

download:
  input_csv: <path-to-input>

  backend:
    type: filesystem
    base_path: <path-to-working-directory>

  queries:
    - type: positional
      radius_arcsec: 6
      table:
        name: allwise_p3as_mep
      columns:
        - ra
        - dec
        - mjd
        - cntr_mf
        - w1mpro_ep
        - w1sigmpro_ep
        - w2mpro_ep
        - w2sigmpro_ep
        - w1flux_ep
        - w1sigflux_ep
        - w2flux_ep
        - w2sigflux_ep

    - type: positional
      radius_arcsec: 6
      table:
        name: neowiser_p1bs_psd
      columns:
        - ra
        - dec
        - mjd
        - allwise_cntr
        - w1mpro
        - w1sigmpro
        - w2mpro
        - w2sigmpro
        - w1flux
        - w1sigflux
        - w2flux
        - w2sigflux

ampel:
  mongo_db_name: <mongodb-name>

This configuration file will be the input to all subcommands. Downloading and stacking can be run together or separate.

To only download the data:

timewise download <path-to-config-file>

The photometry can be found in FITS files in the working directory specified in the configuration file
along with metadata JSON files. These tell timewise which quries have already completed (per chunk) so the download process can be interrupted and re-started at a later time.

Stack individual exposure by visits

As mentioned above, this needs installation with the ampel extra.

To execute the stacking after the download:

timewise process <path-to-config-file> <path-to-ampel-config-file>

Make some diagnostic plots to check the datapoint selection and binning:

timewise plot <path-to-config-file> <indices-to-plot> <output-directory>

As a shortcut, you can also run download, stacking, and export in one command:

timewise run-chain <path-to-config-file> <path-to-ampel-config-file> <output-directory>

For more configuration options of the stacking, you can run AMPEL manually.

1. Prepare an AMPEL job file for stacking the single-exposure data:

timewise prepare-ampel <path-to-config-file>

The result will contain the path to the prepared AMPEL job file.

2. Run the AMPEL job

ampel job -config <path-to-ampel-config-file> -schema <path-to-ampel-job-file>

Citation

If you use timewise please make sure to cite Necker et al. A&A 695, A228 (2025). Additionally, you might want to include a reference to the specific version you are using:

Difference lightcurves

Make sure to check out timewise-sup, the Timewise Subtraction Pipeline: link.