Keep example ini files up to date
As @salvatore-vitale raised on the call today the example ini files easily get outdated.
The proposal was to automate the generation of these ini files.
I think a nice way to do this would be to build them in the ci as part of the package documentation. The code to print an ini file with the comments from the help should be something like the following. (I'm not sure that this will necessarily work for the arguments that just either store true or false.)
from bilby_pipe.parser import create_parser
parser = create_parser()
with open("example.ini", "w") as ff:
# the first two groups in the parser are the "positional" and
# "optional" arguments and shouldn't be printed in the ini file
for group in parser._action_groups[2:]:
ff.write("\n## {}\n\n.".format(group.title))
for action in group._group_actions:
ff.write("# {}\n".format(action.help))
ff.write("{}={}\n".format(action.dest, action.default))There's also a question about what range of extra examples we should give or if this is sufficient (possibly with improved documentation).
This currently generates the following.
## Calibration arguments
# Choice of calibration model, if None, no calibration is used
calibration_model=None
# Dictionary pointing to the spline calibration envelope files
spline_calibration_envelope_dict=None
# Number of calibration nodes
spline_calibration_nodes=5
# Dictionary of the amplitude uncertainties for the constant uncertainty model
spline_calibration_amplitude_uncertainty_dict=None
# Dictionary of the phase uncertainties for the constant uncertainty model
spline_calibration_phase_uncertainty_dict=None
## Data generation arguments
# File containing segment GPS start times
gps_file=None
# The trigger time
trigger_time=None
# If true, use simulated Gaussian noise with aLIGO design sensitivity
gaussian_noise=False
# Dictionary of paths to gwf, or hdf5 data files
data_dict=None
# If given, the data format to pass to `gwpy.timeseries.TimeSeries.read(), see gwpy.github.io/docs/stable/timeseries/io.html
data_format=None
# Channel dictionary: keys relate to the detector with values the channel name, e.g. 'GDS-CALIB_STRAIN'. Note, the dictionary should follow basic python dict syntax.
channel_dict=None
## Detector arguments
# Run the analysis for all detectors together and for each detector separately
coherence_test=False
# The names of detectors to use. If given in the ini file, detectors are specified by `detectors=[H1, L1]`. If given at the command line, as `--detectors H1 --detectors L1`
detectors=None
# The duration of data around the event to use
duration=4
# Random seed used during data generation
generation_seed=None
# Dictionary of PSD files to use
psd_dict=None
# Fractional overlap of segments used in estimating the PSD
psd_fractional_overlap=0.5
# Time (in s) after the trigger_time to the end of the segment
post_trigger_duration=2
# None
sampling_frequency=4096
# Number of duration-lengths used to generate the PSD, default is 32.
psd_length=32
# PSD method see gwpy.timeseries.TimeSeries.psd for options
psd_method=median
# Start time of data (relative to the segment start) used to generate the PSD. Defaults to psd-duration before the segment start time
psd_start_time=None
# The maximum frequency, given either as a float for all detectors or as a dictionary (see minimum-frequency)
maximum_frequency=None
# The minimum frequency, given either as a float for all detectors or as a dictionary where all keys relate the detector with values of the minimum frequency, e.g. {H1: 10, L1: 20}.
minimum_frequency=20
# Use a zero noise realisation
zero_noise=False
# Roll off duration of tukey window in seconds, default is 0.4s
tukey_roll_off=0.4
## Injection arguments
# Create data from an injection file
injection=False
# Injection file: overrides `n-injection`.
injection_file=None
# Number of injections to generate by sampling from the prior
n_injection=None
## Job submission arguments
# Accounting group to use (see, https://accounting.ligo.org/user)
accounting=None
# Output label
label=label
# Run the job locally, i.e., not through a batch submission
local=False
# Run the data generation job locally. Note that if you are running on a cluster where the compute nodes do not have internet access, e.g. on ARCCA, you will need to run the data generation job locally.
local_generation=False
# Run the plot job locally
local_plot=False
# Output directory
outdir=.
# Memory allocation request (GB), defaults is 4GB
request_memory=4
# Memory allocation request (GB) for data generation step
request_memory_generation=None
# CPU allocation request (required multi-processing jobs)
request_cpus=1
# Singularity image to use
singularity_image=None
# Attempt to submit the job after the build
submit=False
# If true, use HTCondor file transfer mechanism, default is False
transfer_files=False
# If true, format condor submission for running on OSG, default is False
osg=False
## Likelihood arguments
# Boolean. If true, use a distance-marginalized likelihood
distance_marginalization=False
# Path to the distance-marginalization lookup table
distance_marginalization_lookup_table=None
# Boolean. If true, use a phase-marginalized likelihood
phase_marginalization=False
# Boolean. If true, use a time-marginalized likelihood
time_marginalization=False
# The likelihood. Can be one of[GravitationalWaveTransient, ROQGravitationalWaveTransient]Need to specify --roq-folder if ROQ likelihood used
likelihood_type=GravitationalWaveTransient
# The data for ROQ
roq_folder=None
# Rescaling factor for the ROQ, default is 1 (no rescaling)
roq_scale_factor=1
## Output arguments
# Create diagnostic and posterior plots
create_plots=False
# Create a PESummary page
create_summary=False
# Email for notifications
email=None
# If given, add results to an directory with an an existing summary.html file
existing_dir=None
# Directory to store summary pages. If not given, defaults to outdir/results_page
webdir=None
## Prior arguments
# The name of the prior set to base the prior on. Can be one of[PriorDict, BBHPriorDict, BNSPriorDict, CalibrationPriorDict]
default_prior=BBHPriorDict
# The symmetric width (in s) around the trigger time to search over the coalesence time
deltaT=0.2
# The prior file
prior_file=None
## Post processing arguments
# An executable name for postprocessing. A single postprocessing job is run as a child of all analysis jobs
postprocessing_executable=None
# Arguments to pass to the postprocessing executable
postprocessing_arguments=None
## Sampler arguments
# Sampler to use, or a list of samplers to use
sampler=dynesty
# Random sampling seed
sampling_seed=None
# Number of identical parallel jobs to run per event
n_parallel=1
# Dictionary of sampler-kwargs to pass in, e.g., {nlive: 1000}
sampler_kwargs=None
## Waveform arguments
# The reference frequency
reference_frequency=20
# The name of the waveform approximant
waveform_approximant=IMRPhenomPv2
# Name of the frequency domain source model. Can be one of[lal_binary_black_hole, lal_binary_neutron_star,lal_eccentric_binary_black_hole_no_spins, sinegaussian, supernova, supernova_pca_model]
frequency_domain_source_model=lal_binary_black_hole
Edited by Colm Talbot