APEX user manual

Satellite light curve analysis

Installation of dependecies: relevant Python packages

For interactive windows install the tkinter package (required!):

Python2 version:

sudo apt-get install python-tk

Python3 version:

sudo apt-get install python3-tk

For plotting install the matplotlib package (required!):

sudo pip install -U matplotlib

For PDM (phase dispersion minimization) analysis of the rotation period install the PyAstronomy package (recommended!):

sudo pip install -U PyAstronomy

Basic procedure

The APEX script apex_geo_lightcurve expects you to use an XML file with photometric measurements in 'ISON format' which can be obtained after the image processing by either the apex_geo or the apex_geo_auto APEX script, if you have set the option format = ison in the [apex.extra.GEO.report] section of the APEX configuration file before the image processing.

If necessary, prior to the light curve analysis adjust the script section [apex_geo_lightcurve] in the APEX configuration file.

Put the XML file with photometric measurements in any folder of your choice, open the terminal and run the APEX script:

apex_geo_lightcurve.py

A file dialogue window will pop up. Select and open one XML file with measurements. The script will read in the entire data set contained in the selected file.

Raw light curve plotting

Upon reading the file with measurements, the script will process each satellite block contained in the file one after another, applying the option settings of the script section [apex_geo_lightcurve] in the APEX configuration file.

If a measurement in the satellite block does not contain at least one of the tags <mag> and <mag_error>, or, if at least one of these two tags has the value nan (not a number), then this measurement will be excluded from the analysis. After parsing the entire satellite block, the script outputs in the terminal the final number of valid measurements available for the analysis of the current satellite.

If the number of valid measurements is equal to or smaller than the value of phi_tick_step in the script section [apex_geo_lightcurve] of the APEX configuration file, then the script will immediately terminate with a corresponding warning message in the terminal. Decrease the value of phi_tick_step and re-run the apex_geo_lightcurve script.

If the phase angle calculation was set to be done from the orbit (phi_by_coords = False), but either the orbit catalogue paths are not properly set up in the sections [apex.catalog.ison_reader] and/or [apex.catalog.tle_reader] of the APEX configuration file, or the orbit catalogues are missing in the folders indicated in those two sections, or the satellite ID (tag <id> in the measurements file) is not found in these orbit catalogues, then the script will immediately terminate with a corresponding warning message in the terminal. Solve the problem and re-run the apex_geo_lightcurve script.

Then a window with the raw light curve plot will pop up, showing the measurements of the satellite apparent brightness versus the UT time-stamps as contained in the measurements file (tags <mag> and <utc>). The auxilary x-axis at the top shows the corresponding phase angles – for the first and the last measurement and for evenly spaced measurements in-between. If the title is set to be shown (show_title = True), it will include the ID of the satellite (tag <id> in the measurements file) and the UT date of the first measurement.

Then you can interactively delete and restore deleted data points in the plot. (see below)

If the phase angle calculation was set to be done from the equatorial coordinates (phi_by_coords = True), or, if both the Lomb-Scargle periodogram and the PDM analysis were set to be skipped (skip_lsp = True and skip_pdm = True), then by closing the raw light curve plot window you will proceed to the next satellite block available in the measurements file, thus repeating the raw light curve plotting for each satellite until you reach the last one and thus will finish the script execution. Otherwise, if all three options were set to False, then after closing the raw light curve plot window you will proceed to the rotation period search by means of either Lomb-Scargle periodiogram or PDM analysis alone or both one after another, each succeeded by the folded light curve plotting.

If any data points were deleted interactively, only the remaining data points will be used in further analysis.

WARNING! After closing the raw light curve plot window, if you have deleted any data points, the script saves the current/changed data set overwriting the same measurements file. Hence, make sure to have a copy of your original XML file with measurements before you run the apex_geo_lightcurve script, because otherwise you might lose data by accident.

Lomb-Scargle periodogram (LSP)

If the phase angle calculation was set to be done from the orbit (phi_by_coords = False), the forced rotation period was not set to any value (forced_period =), and the Lomb-Scargle periodogram was not set to be skipped (skip_lsp = False), then after closing the raw light curve plot window the script will apply the Lomb-Scargle periodogram to the satellite data set to search for a light curve period in it; it will be applied within the period range set by the options max_period and min_period and with a frequency resolution set by the option samples in the script section [apex_geo_lightcurve] of the APEX configuration file.

Then a window with the Lomb-Scargle periodogram plot will pop up, showing the periodogram itself and the satellite rotation period calculated from the light curve period and the option period_factor. In ideal case, the periodogram will show only one single maximum power peak at a frequency corresponding to the light curve period of highest probability.

After closing the Lomb-Scargle periodogram plot window, the script will forward the obtained satellite rotation period to the folded light curve plotting procedure. (see below)

Folded light curve plotting

After closing either the Lomb-Scargle periodogram plot window or the PDM analysis plot window, a new window with a triple folded light curve plot will pop up. The folded light curve shows the satellite brightness reduced to the observer-satellite distance 1000 km and the phase angle 90 degrees.

Then you can interactively delete and restore deleted data points in the plot. (see below)

Also, you can interactively re-draw the folded light curve with a forced satellite rotation period different from the one found automatically by the Lomb-Scargle periodogram or by the PDM analysis. There are two ways to do that: 1) by pulling the slider (red line) with a mouse pointer along the Period (s) bar in the range set by the options slider_max and slider_min with a slider step set by the option slider_step, 2) by entering any fixed value in the Set period (s) text field and hitting the Enter key. After the manual change of the satellite rotation period you can always re-draw the folded light curve plot with the original rotation period automatically found by the Lomb-Scargle periodogram or the PDM analysis by clicking on the Reset button.

If you have set the option forced_period with some value of the satellite rotation period, then, after closing the raw light curve plot, the folded light curve will immediately be plotted being forced to this value skipping the application of the Lomb-Scargle periodogram and the PDM analysis.

WARNING! After closing the folded light curve plot window, if you have deleted any data points, the script saves the current/changed data set overwriting the same measurements file.

Phase dispersion minimization (PDM) analysis

If the phase angle calculation was set to be done from the orbit (phi_by_coords = False), the forced rotation period was not set to any value (forced_period =), and the PDM (phase dispersion minimization) analysis was not set to be skipped (skip_pdm = False), then after closing either the raw light curve plot window (when the Lomb-Scargle periodogram is set to be skipped) or the folded light curve plot window (previously produced on the basis of the Lomb-Scargle periodogram) the script will apply the PDM analysis to the satellite data set to search for a light curve period in it; it will be applied within the period range set by the options max_period and min_period and with a frequency resolution set by the option samples, with a number of covers for bin sequences and with a number of equidistant bins set by the options pdm_covers and pdm_nbins in the script section [apex_geo_lightcurve] of the APEX configuration file.

Then a window with the PDM plot will pop up, showing the PDM itself and the satellite rotation period calculated from the light curve period and the option period_factor. In ideal case, the periodogram will show only one single minimum power peak at a frequency corresponding to the light curve period of highest probability.

After closing the PDM plot window, the script will forward the obtained satellite rotation period to the folded light curve plotting procedure. (see above)

Deleting/restoring data points in light curve plots

Both in the raw light curve and in the folded light curve plot you can delete single data points by left-clicking on them in the plot; in case of the folded light curve the deletion can be done only in the middle part of the triple plot. By right-clicking anywhere in the plot you can restore the deleted data points in reverse order (from the last to the first).

Remarks

It is better to use an XML measurements file which contains a data set for only one single satellite, because many different satellites in the same measurements file will require a very broad period range (set by the options max_period and min_period) due to possibly very different rotation periods, this may cause wrong determination of the rotation period and will also considerably increase the analysis time.

Frequently, the PDM analysis yields better results than the Lomb-Scargle periodogram.

Too high values of the option samples may produce a memory error.

last updated: 12.12.2020