MagPy

D:  MagPy

  1. The MagPy.py python script is called from the same working directory we used before with the terminal command magpy.  I assume you have edited the magpy bash script to point to the Python file.
  2. MagPy opens.  There may be some messages saying ‘Star id does not exist. Will be dropped: ‘.  Ignore these.  We will now look at the input fields.
  3. Mag of COMP is only used as a reference to place reported magnitudes on a scale.  COMP can be included in the ensemble or not.  For exoplanet work a reference mag is not usually necessary because we are more interested in brightness changes.  But I like to have some indication of approx brightness and usually use a catalog Vmag.
  4. Several fields are there purely to populate the AAVSO format report, i.e. COMP Label, Chart ID, Group, Notes, Obs Code and Software.  Optional if not submitting data to AAVSO.
  5. Use detrended ens?  This is an option to use de-trended light curves for the ensemble stars. Experimental at this time.
  6. Ingress/ Egress BJD/HJD are predicted transit times will be marked on the light curve plots.  Enter 0 if not wanted.
  7. Block size (s) Bin/block together data points within this time interval.   These blocked points will be displayed as red squares on the lightcurves.
  8. List of stars…  This comma separated list specifies the ensemble stars to be used (using “star ids”, see the discussion on this here).  If the tickbox Optimise ensemble? is selected, MagPy will auto-optimise, so you may start with any list, or even a blank list.
  9. The Filter band is read automatically.
  10. Scope Dia and Exp Time are used in scintillation calcs.  Exp Time should already be filled in based on the catalog XML file.    This will be wrong if you used a catalog file from a previous run with a different exposure time.  In that case, check and change.
  11. Click on RUN.  Once a run has been done, Status show either ‘Optimisation done:’ or ‘Opt Criteria:’ followed by a number.  This is a measure of the extent to which using the ensemble has improved scatter.  The more negative the number, the better.
  12. To change ensemble stars, de-select Optimise ensemble?, modify the ensemble list and click RUN again.
  13. If you are running MagPy after PESTphot, the Mag of COMP and Ingress/ Egress BJD/HJD will have been pre-filled.

 

D.2

E: Lightcurve optimisation

A MagPy run produces lots of files, mostly images.

For now, note the files with names in the form *_LCx_StarID-n.png.  Each is a lightcurve for star id n.  The sequential number x is always 1 for the target, and 2 for COMP.  For example, the target lightcurve here is TIC259377017-01_20190113_PEST_V_LC1-StarID-7.png.

 

With Optimise ensemble? ticked, i.e. with auto-optimisation, the resulting target light curve:

Result of auto-optimisation

There is a hint of the predicted transit at the right time (between the green and red dotted verticals).  But there is a downwards trend that obscures this.  From the MagPy window we see that auto-optimisation has chosen the following ensemble:  3,15,25,26,4,18,24,23,10,17,2,12,13

Ensemble stars that have an upward trend will tend to impart a downward trend on the target.  On examination of the other ensemble star lightcurves we find that stars 2 and 4, among others have an upward trend.  N.B.  On Ubuntu it is very easy to successively view all the produced plots – just use the left/ right arrow keys.

 

Example of ensemble star with upward trend

Re-running MagPy with these stars dropped (remember to un-tick Optimise ensemble?) results in this target lightcurve.

 

Final lightcurve showing transit event

The final lightcurve shows a clear ~3mmag dip at about the right time.  This was a transit of the sub-Neptune planet TOI-270c.  It was just 3.4mmag, or 0.3% deep.

 

 

F: Other products from MagPy

  1. The ENSEMBLE_STATS.txt file quantifies of the quality of the data and the improvement as a result of using the ensemble .  It lists, for each selected star, the mean mag, std dev and no. of valid data points, both with standard (V-C) photometry, and using the ensemble.  Note that, as expected SD generally decreases.  The no. of valid data points will also decrease, because if there is any ensemble star with invalid data at a particular timestep, no result will be recorded for that timestep.
  2. The file *_data.txt contains time, magnitude and error data for the target.  Time will be BJD or HJD as specified in config.  This file is the one to send to enable others to plot and analyze your observations.
  3. The *_Comments.txt file is a pre-populated observation report.   It has key information such as target name, date, filter, ensemble stars, and whether date type is HJD or BJD.  I also just copy the part of the first line after ‘Photometric follow-up: ‘ and use that as the title of any email notification of the observation.
  4. An AAVSO report is prepared.  In this case the filename is INVALID_AAVSO_TIC259377017-01.txt.  The reason for the INVALID is that the ensemble includes COMP.  To prepare a valid AAVSO data submission leave COMP out of the ensemble.
  5. The TESS team may want to try different de-trending choices on your data.  To enable this, the file TIC259377017-01_20190113_PEST_V_mag+detrend-data.txt contains potential detrending parameters (airmass, FWHM etc.) for each timestep.
  6. One way of assessing if an apparent feature in the target lightcurve is real is to examine other field stars to see if their lightcurves show similar features.  These are in the file TIC259377017-01_20190113_PEST_V_sample-lightcurves.png .

 

F.1
F.2
F.3

Behind the scenes

  • On startup, MagPy pre-fills some of its input fields using the param_MagPy.txt file (but others, eg target name, input directory, filter band are read from the environment, or previous pipeline products).  config specifies where to place this file.  I place it on the desktop for convenient access.  This is because each MagPy run produces an INFO.txt file containing exactly the same data as goes into param_MagPy.txt.  So to re-create a previous run, just copy the contents of INFO.txt into param_MagPy.txt.
  • MagPy uses a couple of files created by PESTphot as input.  These are named Muni_dddd.txt and det_Muni_dddd.txt where dddd is the date.  Both are text files in C-Munipack output data format, i.e. it’s the file you would get if you select Save in the C-Munipack ‘Plot Light Curve’ screen. The difference between the two files is that the latter has detrended ensemble star data.
  • Detrending has been built into the pipeline, but at the moment it is of limited use because it is only applied to ensemble stars, and often the target lightcurve has systematics as well.  On my to-do list is to to improve this.
  • The ensemble calculation weights each ensemble star by its scatter.  Lower scatter stars (usually brighter and well behaved) have greater weight in the ensemble.
  • The ensemble optimisation algorithm applied is as follows.  Calculate the average scatter (std dev) of magnitudes of all potential ensemble stars (i.e. those selected manually in C-Munipack as well as by PESTphot).  Then select those stars having scatter lower than this average.  These are designated the ‘Better stars’.  An optimisation criteria is calculated from the improvement in the collective scatters of these ‘Better stars’ when an ensemble selection is applied.  MagPy starts the ensemble optimisation process with the ‘Better stars’ as the ensemble list, then tests each star to see if dropping it will improve the optimisation criteria.  This process stops when the optimisation criteria can no longer be improved, and the auto-optimised ensemble list is returned.

 

You may get an ugly MagPy if you run it from within Anaconda

There is a known bug in Anaconda that results in any GUI built using Tkinter being very ugly.  The screenshots of MagPy here look decent because I run it using my system Python.  This is a hassle because the dependencies then have to be installed outside of the conda virtual environment.  If you can live with the ugly fonts it all works fine – but it’s just ugly!

 

MagPy dependencies

It helps that MagPy has relatively few dependencies.  To install these outside of the conda environment create a text file called magpy_requirements.txt with the following text:

cycler==0.10.0
kiwisolver==1.1.0
matplotlib==3.1.1
numpy==1.17.2
pandas==0.25.1
Pillow==6.1.0
pkg-resources==0.0.0
pyparsing==2.4.2
python-dateutil==2.8.0
pytz==2019.2
six==1.12.0

Then install these dependencies with:
pip3 install -r magpy_requirements.txt

Previous: PESTphot  Next: The config file

Back to PEST pipeline page index.