Input arguments

This section includes a list of arguments that can be passed to trap-run. Equivalent information can be shown in the terminal by running trap-run –help.

The arguments can be modified in the configuration file (default: trap_config.toml) or via the command line. The arguments supplied on the command line take precedence.

options

  • -h, –help: show this help message and exit

General

  • –version: Display the version of the currently installed TraP.

  • –pyse_version, –pyse-version: Display the version of the currently installed radio-pyse.

  • –config_file, –config-file: TOML file containing default input arguments to TraP. Default file name: trap_config.toml This is especially convenient when swapping between configurations for the same project.

  • –log_dir, –log-dir: The directory in which to write the log and the error log file. The same information is also printed to the terminal standard output.

  • –nr_threads, –nr-threads, -n: Number of threads to spawn. With multiple threads, images can be read and processed in parallel. If None, use as many theads as there are cores. Using multiple threads speeds up computation significantly. Note that there is a point where the association becomes the bottleneck, since it is fundamentally a sequential operation. That means that adding more processes to pre-load the images has diminishing returns. Warning: there is a known bug where the RAM of your device might blow up if you use many processes but either have little RAM or very many images to process. It can happen that all of the images get loaded in before the program is near completion. To work around this, use a low number of processes. This bug will be addressed in the future. When the distributed scheduler is used, the nr_threads will be divided over the processes and threads. For example, if nr_threads=12, we might get 3 processes with 4 workers each. If a prime number is chosen this might result in a skewed distribution. When nr_threads is set to 13, we might for example get one process with 13 threads, which will run fine but is often non-optimal in terms of performance. Also see argument: scheduler

  • –max_concurrent_images, –max-concurrent-images: Make sure we don’t read more than N images at a time. A consrvative limit protects agains RAM overflows.

  • –scheduler: The Dask scheduler to use. Options are: [‘threads’, ‘distributed’]. Default: ‘threads’. The ‘threads’ scheduler uses multithreading to process in parallel. This has the least overhead but is limited by Python’s GIL. The ‘distributed’ scheduler uses a balance of both processes and threads which allows for more versitile parallel computing but can carry more overhead, especially when data between processes needs to be communicated. The distributed scheduler also provides a real-time diagnostics dashboard and allows for running accross multiple nodes. In general I recommend using the threads scheduler when running on a smaller machine like a laptop and use the distributed scheduler when running on a compute node with lots of RAM and many CPU cores. See also the argument: nr_threads.

  • –pdb: Enter debug mode when the application crashes. Meant to be used for more comprehensive debugging. This argument is not exported to the database.

Database parameters

  • –db_backend, –db-backend: The database solution to use. Options are: [‘sqlite’, ‘postgres’]. Default: ‘sqlite’. If set to ‘postgres’, the following parameters also need to be provided: ‘db_user’, ‘db_password’, ‘db_host’, ‘db_port’.

  • –db_name, –db-name: When ‘db_backend’ is sqlite, ‘db_name’ represents the path to the file. When ‘db_backend’ is ‘postgres’, ‘db_name’ represents the name of the database.

  • –db_host, –db-host: The name of the host where the database is located (used for ‘postgres’).

  • –db_port, –db-port: The port number to go along with ‘db_host’ (used for ‘postgres’).

  • –db_user, –db-user: The username used for accessing the database (used for ‘postgres’).

  • –db_password, –db-password: The password used for accessing the database (used for ‘postgres’). This argument is not exported to the database.

  • –db_overwrite, –db-overwrite: If supplied, clears the database and starts fresh. Only use this if you are OK losing the existing database with the supplied ‘db_name’. When not supplied, the program will error if the database already exists, preventing deletion of existing data.

Input image parameters

  • –input_images, –input-images, -i: The input images in which to find the sources. Only .fits images are supported. This can refer to either a file, directory or glob pattern (e.g. ‘images/my_image_*.fits’). When using a glob pattern, remember to wrap the line in quotes or the terminal might get confused. If a directory or glob pattern is used, all fits images found there will be used. If a nested directory is supplied, the subdirectories will also be searched for fits files. These arguments can be supplied multiple times to refer to multiple files or locations.

  • –rms_min, –rms-min: Lower bound for the RMS quality check. If an image has a lower RMS value than ‘rms_min’, it is ‘rejected’ and not processed.

  • –rms_max, –rms-max: Upper bound for the RMS quality check. If an image has a larger RMS value than ‘rms_max’, it is ‘rejected’ and not processed.

  • –reduction_factor_for_rms: Only the region around the center of the image is used to determine the RMS of the image on which the rejection is based. The ‘reduction_factor_for_rms’ determines the size of this region around the center, where ‘reduction_factor_for_rms’ is the fraction of each axis to use. To illustrate: if an image is 100x100 pixels, a reduction_factor_for_rms=2 results in a 50x50 slice around the center that is used to calculate the RMS of the image.

  • –frequency_band, –frequency-band, -f: Pre-definde frequency band. To be supplied as a Json dictionary like so: ‘{“center_frequency”: 140000000, “bandwidth”: 4687500.0}’. This can also be a file path to a json file with a list of such dictionaries. A mix can be supplied by supplying it multiple times, e.g.: trap-run -f ‘{“center_frequency”: 140000000, “bandwidth”: 4687500.0}’ -f frequency_bands.json

Extraction parameters

  • –ew_sys_err, –ew-sys-err: Systematic error in arcseconds along the east-west axis.

  • –monitor_loc, –monitor-loc, -m: A list of locations to always monitor. The coordinates are to be supplied in decimal degrees in the form [Ra, Dec] (e.g ‘[12.3, 45.6]’ or ‘[[123.4,56.7],[359.9,89.9]]’) It can also be the path to a json file with similar structure. A mix of these can be supplied by supplying it multiple times, e.g.: trap-run -m ‘[12.3, 45.6]’ -m monitor_locations.json

  • –ns_sys_err, –ns-sys-err: Systematic error in arcseconds along the north-south axis.

  • –detection_threshold, –detection-threshold: The detection threshold, as a multiple of the RMS noise.

  • –analysis_threshold, –analysis-threshold: Analysis threshold, as a multiple of the RMS noise.

  • –deblend_nthresh, –deblend-nthresh: Number of subthresholds to use for deblending. Set to 0 to disable.

  • –max_nr_consecutive_force_fits, –max-nr-consecutive-force-fits: Stop force fitting if the source has not naturally been found after a specified number of images. If the source has been found naturally again this is reset and we will again force fit for the specified number of images. If the source is naturally detected at a regular interval that is smaller than max_nr_consecutive_force_fits, the lightcurve will be continuous. If there are periods where the source is not naturally found within the specified number of images, there will be gaps in the time axis of the lightcurve. Since the number of images is also related to the number of frequency bands, we multiply the max_nr_consecutive_force_fits by the number of frequency bands in order to make sure we work with the number epochs, not images. This assumes each epoch has the same number of frequency bands. If some epochs miss frequency bands, we might end up sampling a few more epochs than intended.

  • –force_beam, –force-beam: Force all extractions to have major/minor axes equal to the restoring beam.

  • –im_margin, –im-margin: The number of pixels from the edge of the image within which sources are ignored.

  • –im_radius, –im-radius: The radius in pixels around the center of the image, outside of which sources are ignored.

  • –im_back_size_x, –im-back-size-x: Width of the background boxes as used in SEP.

  • –im_back_size_y, –im-back-size-y: Height of the background boxes as used in SEP.

Association parameters

  • –de_ruiter_r_max, –de-ruiter-r-max: If the de Ruiter radius is larger than this value, sources are considered different.