API

Core Function

preface.run_preface(TelescopeConfigurations: TelescopeConfigurations, OutputConfigurations: OutputConfigurations, MoonlightNoiseConfigurations: MoonlightNoiseConfigurations | None = None, MultiprocessingConfigurations: MultiprocessingConfigurations | None = None)[source]

Execute the complete PREFACE processing pipeline.

This function orchestrates all stages of the PREFACE workflow, including Phase One (target score ranking), Phase Two (transit event filtering), parallel event processing, and final post-processing. The behavior of the pipeline is controlled through the provided configuration objects.

Parameters:

TelescopeConfigurations (TelescopeConfigurations) – Configuration specifying the observing instrument, photometric filter, and telescope-related settings.
OutputConfigurations (OutputConfigurations) – Configuration specifying the observation window, output location, ranking metric type, viability threshold, and graph generation options.
MoonlightnoiseConfigurations (MoonlightNoiseConfigurations) – Configuration controlling moonlight noise modelling, including atmospheric scattering parameters and moonlight amplification factors.
MultiprocessingConfigurations (MultiprocessingConfigurations) – Configuration defining multiprocessing behavior and CPU core allocation.

Return type:

None

Configuration Classes

class preface.configs.TelescopeConfigurations(instrument: str, filter_name: str, run_mode: str, toggle_sky_noise=True, toggle_defocus=False)[source]

Bases: object

Configuration container for telescope and instrument settings.

property unpack

Return the stored telescope configuration as an ordered list.

Returns:: Values in the order: [instrument, filter_name, run_mode, toggle_sky_noise, toggle_defocus].
Return type:: list

class preface.configs.OutputConfigurations(observation_start: datetime, observation_end: datetime, output_folder: str | Path, metric_mode='Rank', viable_cumulative_cut=0.9, toggle_graph_outputs=True, event_weight_graph_threshold=0.75)[source]

Bases: object

Configuration container controlling PREFACE output generation and exoplanet ranking settings.

property unpack

Return the stored output configuration as an ordered list.

Returns:: Values in the order: [observation_start, observation_end, output_folder, metric_mode, viable_cumulative_cut, toggle_graph_outputs, event_weight_graph_threshold].
Return type:: list

class preface.configs.MoonlightNoiseConfigurations(toggle_moonlight_noise=False, scattering_aod=0.2, absorption_aod=0.3, asymmetry_factor=0.6, moonlight_amplification_factor=9)[source]

Bases: object

Configuration container for moonlight background noise modelling.

property unpack

Return the stored moonlight noise configuration as an ordered list.

Returns:: Values in the order: [toggle_moonlight_noise, scattering_aod, absorption_aod, asymmetry_factor, moonlight_amplification_factor].
Return type:: list

class preface.configs.MultiprocessingConfigurations(toggle_multiprocessing=True, cores_to_leave_out=1)[source]

Bases: object

Configuration container controlling multiprocessing behaviour and CPU resource allocation.

property unpack

Return the stored multiprocessing configuration as an ordered list.

Returns:: Values in the order: [toggle_multiprocessing, total_cores, cores_to_leave_out, cores_used].
Return type:: list

Utilities

preface.telescope_list = ['PROMPT-8_Dark', 'PROMPT-8_Grey', 'PROMPT-8_Bright', 'TRT-TNO', 'Gao Mei Gu', 'TNT ULTRASPEC', 'VLT FORS2 (200kHz)', 'VLT FORS2 (200kHz) 600RI+19', 'VLT FORS2 (100kHz)', 'VLT HAWK-I', 'VLT KMOS_HK', 'LT RISE', 'LT SPRAT Red', 'LT SPRAT Blue', 'ROPNM', 'NARIT SBO', 'NTT ULTRACAM', 'NTT EFOSC2 GR01', 'Kottamia_Phot', 'MuSCAT2_Dark', 'MuSCAT2_Bright', 'Sutherland_1.9_SHOC1', 'Sierra Remote', 'MeerLICHT', 'HST STIS G750M', 'Twinkle_Band1', 'Twinkle_Band2', 'Twinkle_Band3', 'ARIEL_1.3', 'DOT_TIRCAM2']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

preface.get_available_filters_list(instrument: str)[source]

Retrieve the list of supported photometric filters for an instrument.

The available filters are determined by identifying filter names for which both zero-point magnitude (mzp_*) and sky brightness (msky_*) entries are defined in the instrument database.

Parameters:: instrument (str) – Name of the telescope or instrument as listed in Scope.csv. See preface.telescope_list for list of available telescopes.
Returns:: Alphabetically sorted list of supported filter names.
Return type:: list[str]
Raises:: ValueError – If the specified instrument is not present in the instrument database.

preface.open_scope_csv()[source]

Open the bundled Scope.csv database using the default system application.

Return type:: None

preface.wipe_intermediate_csvs()[source]

Delete all files contained within the intermediate CSV directory.

This utility recursively removes every file and symbolic link located in the PREFACE intermediate data directory while preserving the directory structure itself. It is intended for clearing temporary outputs generated during previous runs.

Return type:: None