APEX user manual

APEX configuration file: apex.conf

General information

For proper funcionality of APEX its configuration file (apex.conf) must be adjusted according to different pecularities of each case: geographical position of the observing site, local folder pathnames, image characteristics, etc.

On Ubuntu APEX configuration file is located in the default folder: ~/.Apex

On Windows APEX configuration file is located in the default folder: C:\Users\{username}\.Apex

Configuration file consists of sections; sections consist of options and their values.

Any text string behind the "#" symbol is considered in the configuration file to be a comment.

If the configuration file is located in the same folder, in which an APEX script is run, it will have higher priority than the configuration file in the default folder.

To use a configuration file located in an arbitrary folder, load it with a parameter "-c:" when runnning an APEX script (specify the full path to the configuration file in accordance with the operating system syntax):

script_name.py -c:<full_path>/apex.conf

Sections

Sections are separated from each other by blank lines. There are two types of sections: 1) APEX script sections (having exactly the same names as the corresponding scripts), and 2) APEX module sections (having names made of "apex.*" and of corresponding module/submodule names). Each section name is written in square parentheses, e.g. [apex_geo] or [apex.extraction]. If a section is missing in the configuration file, then APEX uses default values of all options of that section. If needed, the missing section can be added to the configuration file manually by editing it in an ASCII text editor. For practical reasons it is advisable to keep sections in alphabetical order within the configuration file, but internally it makes no difference for APEX in which order the sections are listed.

Options

If an option is missing in a section in the configuration file, then APEX uses its default value. If needed, the missing option can be added to the related section in the configuration file manually by editing it in an ASCII text editor. For practical reasons it is advisable to keep options in alphabetical order within their sections in the configuration file, but internally it makes no difference for APEX in which order the options are listed within their sections.

Script section [apex_calibrate]

cosmetic =                      # [bool] Enable cosmetic correction, default: 1
cosmics =                       # [bool] Enable cosmic ray elimination, default: 0
dark =                          # [bool] Enable dark frame correction, default: 1
flat =                          # [bool] Enable flat field correction, default: 1
sky =                           # [bool] Enable sky background correction, default: 1

This section is always used by the script apex_calibrate, as well as by the scripts apex_geo and apex_geo_auto when run with the option disable_calib = 0 set in the corresponding script section. To minimize image processing time it is advisable to set the options "dark" and "flat" to 0, if there is no need of precise photometric reduction. An unexperienced user is advised to use the default value of the option "cosmics".

If the option "cosmetic" is set to 1, then the module section [apex.calibration.cosmetic] is implied.

If the option "cosmics" is set to 1, then the module section [apex.calibration.cosmic_rays] is implied.

If the option "dark" is set to 1, then the module section [apex.calibration.dark] is implied.

If the option "flat" is set to 1, then the module section [apex.calibration.flat] is implied.

If the option "sky" is set to 1, then the module sections [apex.calibration.background*] are implied.

Script section [apex_geo]

auto_postfilter =               # [bool] Automatically choose between trail_cluster and cluster postfilter based on the expected star trail length, default: 1
disable_calib =                 # [bool] Turn off automatic image calibration, default: 0
disable_measurement =           # [bool] Disable PSF fitting stage; use barycenter/manual XY positions of objects, default: 0
ignore_refstars =               # [bool] Ignore explicit XY positions of reference stars in the image header, default: 0
overwrite_frame =               # [bool] Overwrite the original frame file after processing, default: 0
target_match_tol =              # [float] Manual target GEO XY position accuracy, px (target_match_tol >= 0), default: 5.0
trail_len_tol =                 # [float] Star trail length tolerance, px (0 to disable trail length check) (trail_len_tol >= 0), default: 5.0
trail_width_tol =               # [float] Star trail width tolerance factor (0 to disable trail width check) (trail_width_tol >= 0), default: 3.0

Script section [apex_geo_auto]

auto_postfilter =               # [bool] Automatically choose between trail_cluster and cluster postfilter based on the expected star shape, default: 1
deblend =                       # [bool] GEO detection: enable deblending, default: 0
disable_calib =                 # [bool] Turn off automatic image calibration, default: 0
disable_measurement =           # [bool] Disable the PSF fitting stage; use barycenter/manual XY positions'), default: 0
disable_search =                # [bool] Disable the automatic GEO detection stage, default: 0
exclude_starlike =              # [bool] Exclude star-like detections, default: 1
fit_tol =                       # [float] Desired relative error of fit for GEO objects (geo_fit_tol > 0), default: 0.0001
identify_detections =           # [bool] Match GEOs detected against orbital element databases available, default: 0
max_detections =                # [int] Discard images with that many detections (0 to disable) (max_detections >= 0), default: 500
max_iter =                      # [int] Maximum number of fitting iterations for GEO objects (0 = auto) (geo_max_iter >= 0), default: 0
min_frames =                    # [int] Minimum number of frames in a series (min_frames >= 0), default: 5
postfilter_chain =              # [str] GEO detection: filters applied before segmentation, default: trail_elim, cluster
prefilter_chain =               # [str] GEO detection: filters applied before thresholding, default: upenv
rois =                          # [str] List of regions of interest in the X:Y[:R] form; default for R is inferred from seeing, default: ,
series_by_target =              # [bool] Match frames of the same series by target name (and by target name only, if series_tol = series_len = 0), default: 0
series_len =                    # [float] Maximum allowed duration of a single series, minutes (series_len >= 0), default: 30.0
series_tol =                    # [float] Maximum relative displacement of frames within a series, arcmin (series_tol >= 0), default: 10.0
subtract_stars =                # [bool] Subtract detected reference stars before detecting GEO objects, default: 1
target_match_tol =              # [float] Manual target GEO XY position accuracy, px (target_match_tol >= 0), default: 2.0
threshold =                     # [float] GEO detection threshold in units of noise RMS (geo_threshold > 0), default: 2.5
trail_len_tol =                 # [float] Star trail length tolerance, px (0 to disable trail length check) (trail_len_tol >= 0), default: 5.0
trail_width_tol =               # [float] Star trail width tolerance factor (0 to disable trail width check) (trail_width_tol >= 0), default: 3.0

Script section [apex_geo_ephem]

interval =                      # [float] Ephemeris interval in days (interval > 0), default: 7.0
max_h_sun =                     # [float] Skip intervals where Sun is above this elevation, in degrees (-90 < max_h_sun <= 90), default: -10.0
max_mag =                       # [float] Skip intervals where the object is fainter than specified (0 - no magnitude constraint) (max_mag >= 0), default: 0.0
max_vel =                       # [float] Skip intervals where the object is faster than specified, in arcsec/s (0 - no velocity constraint) (max_vel >= 0), default: 0.0
min_h =                         # [float] Skip intervals where elevation is below this limit, in degrees (-90 <= min_h < 90), default: 15.0
radec =                         # [str] Choose to output true or mean RA and Dec (true, mean), default: true
refraction =                    # [bool] Account for refraction in coordinates, default: 1
skip_shadow =                   # [bool] Skip intervals where the object is eclipsed, default: 0
step =                          # [float] Ephemeris step in seconds (step > 0), default: 600.0
template =                      # [str] Ephemeris file name template, default: (obj)_(site)_(rdate)

Script section [apex_geo_lightcurve]

ccd_filter =                    # [str] Abbreviated name of the CCD filter (e.g. R, V, B, G); default: G
folded_y_lim_max =              # [float] Upper limit for the y-axis (min brightness) in the folded light curve; default: None
folded_y_lim_min =              # [float] Lower limit for the y-axis (max brightness) in the folded light curve; default: None
forced_period =                 # [float] Forced value of the rotation period; default: None
max_period =                    # [float] Maximum period (sec) for the period search; default: 1000
min_period =                    # [float] Minimum period (sec) for the period search; default: 10
pdm_covers =                    # [int] Number of covers for the bin sequences offset by 1/(nbins*covers) in PDM analysis; default: 3
pdm_nbins =                     # [int] Number of equidistant bins in PDM analysis; default: 20
period_factor =                 # [int] Rotation period factor of the light curve period; default: 1
period_precision =              # [float] Number of decimals to round the rotation period to (1 <= period_precision <= 14); default: 3
phi_by_coords =                 # [bool] Calculate phase angles from equatorial coordinates if True, else calculate from orbit; default: True
phi_m0 =                        # [float] The satellite phase angle (deg) for the reduced brightness m0 (0 <= phi_m0 <= 180); default: 90
phi_tick_step =                 # [int] Step in measurements for the ticks of the phase angle axis (phi_tick_step => 2); default: 20
plot_res =                      # [int] Resolution (dpi) for saving the plots; default: 300
plot_title =                    # [str] Part of the plot title with observatory name; default: None
range_m0 =                      # [float] The satellite range (km) for the reduced brightness m0; default: 1000
round_phi =                     # [int] Number of decimals to round the phase angle value to (1 <= round_phi <= 14); default: 1
samples =                       # [float] Samples per peak for the Lomb-Scargle periodogram and for the frequency step of the PDM as 0.1/samples; default: 1000
show_errorbars =                # [bool] Show the magnitude error bars for each brightness data point; default: True
show_title =                    # [bool] Show the plot title; default: True
skip_lsp =                      # [bool] Skip Lomb-Scargle periodogram and folded light curve plotting; default: True
skip_pdm =                      # [bool] Skip PDM analysis and folded light curve plotting; default: True
slider_max =                    # [float] Maximum value for the rotation period slider (slider_max > 0); default: 600.0
slider_min =                    # [float] Minimum value for the rotation period slider (slider_min > 0); default: 0.001
slider_step =                   # [float] Step value for the rotation period slider (slider_step > 0); default: 0.001
time_interval =                 # [int] Step in minutes for the ticks of the time axis (time_interval => 1); default: 2
time_rotation =                 # [float] Counter-clockwise rotation angle (deg) for the tick labels of the time axis; default: 45
y_lim_max =                     # [float] Upper limit for the y-axis (min brightness); default: None
y_lim_min =                     # [float] Lower limit for the y-axis (max brightness); default: None

This section is always used by the script apex_geo_lightcurve whenever you run it.

The options phi_tick_step, plot_title, show_errorbars, show_title, time_interval and time_rotation refer only to the raw light curve plot.

If the option forced_period is set to some value, then the application of the Lomb-Scargle periodogram and of the PDM analysis will be skipped (even if the options skip_lsp and skip_pdm are set to False), and the folded light curve will immediately be plotted to the forced period.

The option period_factor should be given higher values than the default in cases when the actual satellite rotation period is a multiple of the light curve period.

If the option phi_by_coords is set to True (default value), then the satellite phase angles will be calculated from the topocentric equatorial coordinates of the Sun and of the satellite with an assumption that the vectors Sun-satellite and Sun-observer are parallel; this will introduce some errors of calculated phase angles, the smaller is the observer-satellite distance, the smaller will be these errors; this option setting allows only to plot the raw light curve of the measured apparent brightness, and the rotation period search along with the folded light curve plotting will be excluded, being impossible due to the lack of the satellite orbital data, which is necessary both for the observer-satellite distance calculation and, thereupon, for the reduced brightness calculation, with the latter being the requirement for precise rotation period search.

If the option phi_by_coords is set to False, then the satellite phase angles will be calculated on the basis of the satellite orbit; to enable reading of orbit catalogue(s), refer to the module sections [apex.catalog.ison_reader] and [apex.catalog.tle_reader] of the APEX configuration file; if there are multiple catalogues for the same satellite, the one which is closer in time to the epoch of the observation start will be used.

The options max_period, min_period and samples influence the Lomb-Scargle periodogram.

The options max_period, min_period, samples, pdm_covers and pdm_nbins influence the PDM (phase dispersion minimization) algorithm.

The options y_lim_max and y_lim_min are used to scale only the raw light curve plot along the brightness axis (y-axis) by these fixed values; if they are not set (as by default), then the scaling will be done automatically.

The options folded_y_lim_max and folded_y_lim_min are used to scale only the folded light curve plot along the brightness axis (y-axis) by these fixed values; if they are not set (as by default), then the scaling will be done automatically.

The options slider_max, slider_min and slider_step must be larger than 0, otherwise it will produce a division by zero error.

Script section [apex_geo_monitor]

ask_for_directory =             # [bool] Run directory selection dialog at startup, use watched_directory as a starting point, default: 1
excluded_files_mask =           # Regular expression describing image file names to be ingnored. Case insensitive., default: r'^dummy.*'
worker_script_options =         # Options to be passed to the script (separated with blanks), default: ''
files_check_interval =          # [s] Directory poll rate (files_check_interval >= 0), default: 2.0
watched_directory =             # [str] Directory to monitor or default for startup directory selection if enabled, default: .

Script section [apex_geo_postprocess]

dump_orbit =                    # [bool] Dump orbital elements to .check file, default: 0
max_track_len =                 # [float] Maximum allowed duration of a single track, minutes (max_track_len > 0), default: 300.0
save_orbit =                    # [str] Save orbital elements to files (none, uncorrelated, all), default: none
split_by_match =                # [bool] Split series in .check file according to catalog match, default: 0

Module section [apex]

Module section [apex.catalog.ison_reader]

cat_path =                      # [str] Path to catalog files; default: ~/.Apex/ison
priority =                      # [int] Priority of the catalog for object identification; default: 15

This catalogue reader uses files with satellite orbits given in a format developed by Z.N. Khutorovsky.

The option cat_path indicates the full path to the folder, where the catalogue files are stored.

The option priority tells APEX to prefer the ison_reader over the tle_reader, if the value is higher than the corresponding value of the same option in the module section [apex.catalog.tle_reader].

Module section [apex.catalog.tle_reader]

priority =                      # [int] Priority of TLE data for object identification; default: 16
stdmag =                        # [float] Standard magnitude at 1000km range and 90deg phase angle; default: 2.0
tle_path =                      # [str] Path to TLE files; default: ~/.Apex/tle

This catalogue reader uses files with satellite orbits given in the TLE format.

The option priority tells APEX to prefer the tle_reader over the ison_reader, if the value is higher than the corresponding value of the same option in the module section [apex.catalog.ison_reader].

The option tle_path indicates the full path to the folder, where the catalogue files are stored.

Module section [apex.catalog.tyc2_reader]

Module section [apex.catalog.ucac_reader]

Module section [apex.extra.GEO.detection]

Module section [apex.extra.GEO.ephem]

Module section [apex.extra.GEO.report]

Module section [apex.extra.MP.mpc_report]

Module section [apex.extraction]

Module section [apex.identification]

Module section [apex.measurement.aperture]

Module section [apex.measurement.rejection.standard_rejectors]

Module section [apex.parallel]

Module section [apex.photometry]

Module section [apex.photometry.differential]

Module section [apex.sitedef]

altitude =                      # [float] [m] Observatory elevation above the reference spheroid (MSL), for example: 1256.21
latitude =                      # [float] [deg] Observatory latitude (positive for North) (-90 <= latitude <= 90), for example: 40.817566
longitude =                     # [float] [deg] Observatory longitude (positive for East) (-180 <= longitude <= 180), for example: 15.463387
observatory_code =              # [str] IAU observatory code, for example: L28
update_interval =               # [int] [day] MPC observatory code database update interval (0 to disable auto-update) (update_interval >= 0), default value: 0

First three options must be assigned values prior to any image processing with implicit astrometric reduction. Last two options are voluntary in general, but can automatize and simplify the work with the script apex_mpc.

Module section [apex.util.automation.calibration]

last updated: 12.12.2020