Usage

Running PyStoch is a three-step process. All commands read parameters.ini (and, after step 1, framesets.ini) from the current working directory unless told otherwise.

1. Read frames — read_frames

Keep the frames you want to process in subdirectories; each subdirectory is a frameset. For example, FSID frames for the O3 run from the H1L1 baseline can live in ./frames/O3_H1L1/, giving a frameset named O3_H1L1. You can have framesets for different baselines (e.g. O3_H1V1, O3_L1V1).

All frames within a frameset are assumed to share the same parameters (duration, sampling rate, etc.).

Point the frames_location field in parameters.ini at the parent of the framesets, then run:

read_frames

This creates (or updates) framesets.ini with each frameset and its parameters. Every frameset has a process flag: if True, it is included in the map calculation; if False, it is ignored. Always double-check the detected parameters.

usage: read_frames [-h] [--param_file PARAM_FILE] [--log_file LOG_FILE] [--err_file ERR_FILE]

2. Convert frames — convert_frames

Once framesets.ini is correct, convert the .gwf frames to a compressed HDF5 file (this only has to be done once per frameset, and speeds up reading):

convert_frames

usage: convert_frames [-h] [--param_file PARAM_FILE] [--datasets [DATASETS ...]]
                      [--log_file LOG_FILE] [--err_file ERR_FILE]

3. Make maps — pystoch

Check parameters.ini and framesets.ini, then run:

pystoch

Framesets whose process flag is True are processed. Results are written as pickle (.pkl) files in output_map_location, along with a run_parameters.ini recording the exact settings used.

Most parameters can also be overridden on the command line (these take precedence over parameters.ini), for example:

pystoch --param_nside 8 --param_f_min 20 --param_f_max 100 \
        --param_sph True --param_pixel True --output_prefix run1_

Run pystoch --help for the full list of overrides.

Outputs

Depending on the selected bases, PyStoch writes:

  • Pixel_<dataset>_<nside>_<date>.pkl — pixel-basis dirty map and Fisher information.

  • SpH_<dataset>_<lmax>_<date>.pkl — spherical-harmonic dirty map and Fisher.

  • Pixel_NBR_<dataset>_<nside>_<date>.pkl — narrowband-radiometer point estimate and sigma (when nbr is enabled).

Each pickle is a dictionary that also stores the run parameters and frameset metadata.

Using PyStoch as a library

The main building blocks are available directly from the top-level pystoch namespace, so PyStoch can be scripted as well as run from the command line. They are imported lazily, so import pystoch itself stays lightweight (it does not pull in healpy/gwpy until you actually use a function that needs them).

import pystoch

# detector geometry and antenna response
location = pystoch.gwdetectors("H1")["Location"]
gmst = pystoch.gmst_calculate(1369056000)

# build the parameter object from a parameters.ini file
params = pystoch.PystochParam("parameters.ini")

# spherical-harmonic index table, notching, spectral index, ...
lm = pystoch.complex_getlm(params.lmax)

The map-making pieces (FramesetParam, FramesetIntermediates, calculate_maps, calculate_fisher_diag) are exposed the same way. See the API reference reference for the complete list.