Users' Manual for TRIPP

This site is under construction, and will probably forever be. Several sections will need further attention before they reasonably answer questions of the user: If you want to contribute explanations, or have suggestions for the TO DO section, please contact us.

You might have come here to get a quick start, reminding you how to write an image logfile. Should you however be a first-time user, it is strongly recommended that you read the General remarks first.


next up previous contents
Next: (Short) Contents Up: Top of page Previous: Top of page

Table of Contents


next up previous contents
Next: General remarks Up: Top of page Previous: Table of Contents


(Short) Contents


next up previous contents
Next: Routines chronological Up: Top of page Previous: (Short) Contents

General remarks

The general principle is that a logfile and an aperture mask guide the reduction process, and that the call to any of the reduction procedures is simply 
IDL> tripp_procedure,"logfile"
The TRIPP routines are usually quite talkative about which files they use as input and what output they produce. That's why the following descriptions focus on the fine-tuning needed for their successful usage rather than on the exact data flow. Also, the exact methods employed may be found rather in the procedure headers than here.

The following data structure is suggested: 

somewhere/Data/           store (then read) original fits files (from) here

somewhere/Data_reduced/   will contain fits_reduced files and other results

somewhere/Logs/           run IDL session here; store the log files here
To begin, create these directories, store the original CCD data where indicated, change to the Logs directory, start an IDL session and start working with TRIPP. - So what do you do first?
The software provides more routines than just the aperture photometry core; to avoid confusion, the routines which are absolutely necessary for the extraction of light curves have been marked in yellow in the following. If you neglect to run one of these, the next step will fail due to missing input. For an introductory first run of the software, it is recommended to follow just the "yellow" routines. If a second, non-marked routine follows such a "core" routine, its purpose usually is to illustrate (or sometimes modify) the result of the previous one. This kind of monitoring of the progress is generally very useful, and once you have gotten familiar with the main components of TRIPP, we vividly suggest that, in a second step, you take advantage of the intermediate quality control, too. In several cases, the output of these "show" routines is not on-screen, but is one or more .ps file(s).
You will also notice that none of the first couple of routines are marked yellow at all; but even though an introduction to TRIPP is possible without them, it pays to find out about their usage :-)

The following is an ultrashort overview of what to expect. Each of these routines (and a few more!) are described in the following chapter, and additional tips for their successful usage may be found there.

tripp_write_zero_log, "zerologfile"
tripp_zero, "zerologfile"

tripp_write_flat_log, "flatlogfile"
tripp_flat, "flatlogfile"

tripp_write_image_log,"imagelogfile"
tripp_reduction, "imagelogfile"
tripp_show_pos, "imagelogfile"
tripp_define_mask, "imagelogfile"
tripp_extract_flux, "imagelogfile"
tripp_show_raw, "imagelogfile"
tripp_calc_relflux, "imagelogfile"
tripp_show_relflux, "imagelogfile"
tripp_write_relflux, "imagelogfile"

tripp_write_final, "imagelogfile"
tripp_write_error, "imagelogfile"
tripp_show_final, "imagelogfile"

Skip to the first "yellow" routine: tripp_write_image_log

A tip for beginners
One usage of this list could go like this: Copy it into your editor, then copy and paste the calls to the ILD command line instead of having to type them; but before all, keep adding the keywords and/or parameters you use for the treatment of a particular data set. Like this, you will have a record of what exactly you have done and will be able to reproduce it anytime. You could even use this as an ILD procedure itself; this may be annoying when the routines that demand interaction are not commented out but can come in very useful for the number crunching parts.


next up previous contents
Next: During the observations Up: Top of page Previous: General remarks

Routines according to chronological usage



next up previous contents
Next: tripp_monitor.pro Up: Routines chronological Previous: Routines chronological

During the observations


next up previous contents
Next: Creating median bias Up: During the observations Previous: During the observations

tripp_monitor.pro

What does it do?

Displays the images as they come in, or displays a sequence of already existing images. Good for online quality control! May also alert you about passing clouds or the dome obstructing the view during observations ... and it now has a quicklook option! This extracts a lightcurve practically on-line.

Calling sequence

IDL> tripp_monitor, "filename" [, dt=dt, /shade3, /reduced, zrange=zrange,$
                                    x=x, y=y (, and all tripp_tv keywords), /quicklook]

How do I use it?

"filename" can be a logfile (see tripp_write_image_log), but as one usually does not have a logfile at that stage yet, it can also simply be the name of the first image to display (the following filenames will be generated automatically). Set the parameter dt smaller than your cycle time if you are actually monitoring frames as they come in! Keyword /shade3: Uses surface display instead of tripp_tv; this allows for a better control of count rates and the PSF (and looks really cool!). Giving a zrange can be useful to adapt the display to the saturation level of the chip used.

The colortable parameter can be changed from the default 3 ("red temperature") to other values, the same goes for several other graphics keywords.

Finally, tripp_monitor can also automatically monitor name_xxxx_reduced.fits instead of name_xxxx.fits, for example to control the quality of the reduced images after a run of tripp_reduction. Again, give the name of the first image to display. Or, if you want to use a logfile, but view the reduced instead of the original images, switch between them by setting the /reduced keyword.

A related task is the merging of individual frames spaced in time into a running film even though the respective tool has not been made part of tripp_monitor yet.

The quicklook option can only be used with a logfile and an existing mask file. It rewrites the logfile and calls the minimal reduction procedures with the /recycle option.


next up previous contents SPEX LOGO Back to: SPEX
Next: tripp_write_zero_log.pro Up: Routines chronological Previous: tripp_monitor.pro

Creating a median bias image

Zero and Bias are used as synonyms in the following (a Bias has zero exposure time and measures the voltage offset applied to the chip). Darks have exposure time greater than zero, but are equally not exposed to light; they (in addition to the bias which is always present) measure the dark current (which is a function of temperature and exposure time). Correction for dark current at arbitrary temperatures and exposure times is not fully supported yet (and hence not documented).

next up previous contents SPEX LOGO Back to: SPEX
Next: tripp_zero.pro Up: Creating median bias Previous: Creating median bias

tripp_write_zero_log.pro

What does it do?

Evoques a GUI with fields you need to edit and saves the entries. These will guide the calculation of a median zero from several individual frames. Re-evoquing this procedure for the same logfile will show you the entries from the previous editing process and allows you to change them.

Calling sequence

IDL> tripp_write_zero_log,"zerologfile"

How do I use it?

Choose a name for your logfile, call the procedure and fill in the fields of the GUI that appears. You need to give the (common!) size of the frames, i.e. they may NOT differ in size! You can also use this program with a filelist of a chosen set of zero files. See the 'How do I use it?' section of tripp_write_image_log.pro to understand how it works.

Zero Gui - click to enlarge Zero GUI - click to enlarge



next up previous contents SPEX LOGO Back to: SPEX
Next: Creating median flat Up: Creating median bias Previous: tripp_write_zero_log.pro

tripp_zero.pro

What does it do?

Reads in the zero files, calculates their median image and saves it as a new zero.

Calling sequence

IDL> tripp_zero, "zerologfile" [, nr_subframes=nr_subframes, $
                                minInt=minInt, maxInt=maxInt ]

How do I use it?

Run to create the median zero.
If the memory required is not available, you can split the stack into individual sub-stacks by specifying their number as nr_subframes.
This routine only works for frames that are equal in size. The individual frames will be displayed both as an image and as x,y columns, and the program will prompt you for your choice: inclusion or exclusion of individual frames is done via mouse clicks on the image display panel. Once you have gone through all images, the median image of the chosen frames will be calculated, displayed and, if you accept it, saved to the file specfied in the zerologfile.
minInt and maxInt may be used to change the yrange for the column display.


next up previous contents SPEX LOGO Back to: SPEX
Next: tripp_write_flat_log.pro Up: Routines chronological Previous: tripp_zero.pro

Creating a median flatfield image

Flatfielding: the chip is exposed to homogeneous diffuse light from the twilight sky or a regular white area in the dome to determine the sensitivity of individual pixels and across the field. Science frames are calibrated such that the light from less sensitive pixels or pixel areas on the chip (in particular far from the optical axis) is amplified to match the response of the more sensitive pixels.

next up previous contents SPEX LOGO Back to: SPEX
Next: tripp_flat.pro Up: Creating median flat Previous: Creating median flat

tripp_write_flat_log.pro

What does it do?

Evoques a GUI with fields you need to edit and saves the entries. These will guide the calculation of a median zero-corrected flat from several individual frames. Re-evoquing this procedure for the same logfile will show you the entries from the previous editing process and allows you to change them.

Calling sequence

IDL> tripp_write_flat_log,"flatlogfile"

How do I use it?

You need to know your median bias' name to continue.   
Choose a name for your logfile, call the procedure and fill in the fields of the GUI that appears. You also need to give the (common!) size of the frames, i.e. they may NOT differ in size! You can also use this program with a filelist of a chosen set of flat files. See the 'How do I use it?' section of tripp_write_image_log.pro to understand how it works.

Flat Gui - click to enlarge Flat GUI - click to enlarge



next up previous contents SPEX LOGO Back to: SPEX
Next: Apply bias and flat Up: Creating median flat Previous: tripp_write_flat_log.pro

tripp_flat.pro

What does it do?

Reads the flatfield files and subtracts the median zero from each of them:
flat = flat_original - zero
Allows you to accept, modify or reject individual flats; then calculates the position dependent median of all accepted flats.
flat = position dependent median of all flats
The result is normalised to 1
flat = flat/median_flat
(unless the normalisation is explicitely turned off) and saved as median flat.

Calling sequence

Run to create the median flat: 
IDL> tripp_flat, "flatlogfile" [, nr_subframes=nr_subframes, $
                                minInt=minInt, maxInt=maxInt ]

How do I use it?

If the memory required is not available, you can split the stack into individual sub-stacks by specifying their number as nr_subframes.
This routine only works for frames that are equal in size. The individual frames will be displayed both as an image and as x,y columns, and the program will prompt you for your choice: inclusion or exclusion of individual frames is done via mouse clicks on the image display panel. Once you have gone through all images, the median image of the chosen frames will be calculated, displayed and, if you accept it, saved to the file specfied in the flatlogfile.
minInt and maxInt may be used to change the yrange used for the column display.


next up previous contents
Next: tripp_write_image_log.pro Up: Routines chronological Previous: tripp_flat.pro

Applying bias and flatfield correction to the images (if desired) and preparing the aperture photometry

All procedures in this section are called by
procedure, "imagelogfile"

next up previous contents
Next: tripp_reduction.pro Up: Apply bias and flat Previous: Apply bias and flat

tripp_write_image_log.pro

What does it do?

Subsequently evoques two GUIs with fields you need to edit and saves these entries which will guide the reduction process. Re-evoquing this procedure for the same imagelogfile will show you the entries from the previous editing process and allows you to change them.

Calling sequence

IDL> tripp_write_image_log, "imagelogfile"

How do I use it?

Choose a name for the logfile to be written now; it could be something like an identifier for the data set you are about to tackle, followed by the extension .log This call then evoques two GUIs. Fill in all fields as completely as you can and make sure that the observation block ID is meaningful!
Adjust tripp_log_type if you don't like the defaults (anywhere) and start over. Personalising tripp_log_type saves you a lot of typing if you have many similar data sets to work with and is probably quicker than coping previously created imagelogfiles.

Image Gui - click to enlarge First GUI     Second Image Gui - click to enlarge Second GUI

Remarks on the individual entry fields:
  • Left side (first GUI)
    • Instrument:First, try CA2.2; this should work if your FITS File Header conforms to the Y2K-compliant format. More about FITS and IDL
      Use filetime if you don't know anything about the entries in your FITS-Header: This reads the creation date of the original data file (accurate to ~minutes rather than seconds due to the shift caused by the time difference between the middle of the exposure and the end of the readout). Make sure your time marks look like they should; if the above solutions do not work for you, you should become familiar with the particular FITS header entries of your data set in question and adapt tripp_get_gjd to your self-defined instrument option (or find an instrument option in tripp_get_gjd that suits your relevant FITS Header entries. You may choose from the following list:) 
           CA1.2                     (Calar Alto, Spain, 1.2m, before 2000)
     CAN1.2                    (Calar Alto, Spain, 1.2m, after 2000)
     CA2.2                     (Calar Alto, Spain, 1.2m and 2.2m+CAFOS, after 2000)
     BUSCA                     (Calar Alto, Spain, 2.2m with BUSCA) 
     EFOSC                     (ESO; decomissioned?)
     ST7_E                     (AIT, 40 cm and 80cm Telescope)
     STL                       (IAG, 50cm Telescope / AIT, 80cm Telescope)
     MONET_NORTH_1kx1k         (MONET North, 1kx1k Camera, with MaximDL)
     MSSSO12                   (Mount Stromlo and Siding Springs Observatory)
     SA_CCD                    (SAAO, South Africa)
     SAAO                      (SAAO, South Africa)
     SALTICAM                  (SALT@SAAO, South Africa)
     SARA                      (Kitt Peak, Arizona, USA)
     PISZEKESTETOE             (Piszekestetoe, Hungary, 2001 only)
     Bohyunsan                 (Bohyunsan Optical Astronomy Observatory [BOAO], Korea)
     WISE                      (WISE Observatory, Isreal)
     GUNMA                     (Gunma Astronomical Observatory, Japan)
     WENDELSTEIN               (Wendelstein)
     NTT-SUSI2                 (ESO NTT telescope with SUSI2 instrument)
     MJD                       (read MJD keyword)
     HJD                       (read HJD keyword)
     JD                        (read  JD keyword)
     filetime                  (read file creation date, not accurate!!!)
    • first image (filename without path information) or the keyword 'filelist'. Choose the latter one, if you want to reduce a selection of images that is not consecutively numbered.
    • last image (filename without path information) or, if keyword 'filelist' was set before, name of file that contains the list of images (filelistname WITH path information). The names of the images in the list may NOT have path information!
    • path to original images: directory where all files from first to last image are stored
    • path to reduced images: directory where all results are to be stored, is empty at the beginning but must exist
    • name of the zero or dark image to subtract; entry contents is ignored if the following entry is no
    • Switch the zero or dark correction on or off: yes subtracts the zero or dark, no doesn't
    • name of the flatfield image to use; entry contents is ignored if the following entry is no
    • Switch the flatfield correction on or off: yes divides by the flat, no doesn't
    • Object Name: the name of the object will be used as title in plots etc
    • Observation block ID: this line will be used as a prefix for many output files; it should be distinct enough to avoid interference with other data sets (in addition to the object name, the date, filter or similar may be reasonable identifiers). It should definitely not be changed during the reduction process as intermediate data files are likely not to be available when needed because they still have the old names.
  • Right side (first GUI)
    • MASK: number of sources: Of all the submasks for the individual stars, you can later choose which one you really want to use as comparison stars without having to modify the mask. Maximum number of sources is 11, minimum number is 2. Also see the 'How do I use it?' section of tripp_define_mask.pro to understand how the sources are chosen.
    • MASK: Peak search radius: approximate FWHM of the object in pixels (to facilitate the position finding process, generally for user clicks).
    • MASK: Distance source - background: distance between the center of a source and the center of the rectangular background field where the sky value for this source will be measured
    • MASK: Background rectangle side length: Side length of these background fields in pixels
    • EXTRACT: Number aperture radii: The flux extraction is done for a whole set of different extraction radii from which you can choose one later. Choose the total number of extraction radii here.
    • EXTRACT: Minimum radius: Give the radius of the smallest aperture that you want to try out here.
    • EXTRACT: Maximum radius: Give the radius of the largest aperture that you want to try out here.
    • WRITE: Time shift: Sometimes, a time offset may be desired. Most of the time however you will want to put 0 in here.
    • RELFLUX: Selection radius: The entry in this field will be changed to the the extraction radius that is nearest to. The extraction radii are calculated from the minimum and maximum radius and the number of aperture radii given.
    • RELFLUX: Number of comparison stars: Choose how many comparison stars you want to use here. You may want to change this entry after you have seen the raw fluxes; you could set it equal to the number of sources in the mask then later drop the stars you don`t want to use without having to re-run the extraction itself.
    • SHOW_FT: Min frequency: Lower limit for a first-look periodogram
    • SHOW_FT: Max frequency: Upper limit for a first-look periodogram
  • The second GUI appears after you clicked OK on the first one:
    • First comparison star is Ref 2 or higher, as Ref 1 is the object itself
    • Set all fields that you do not need to zero.



next up previous contents
Next: tripp_show_pos.pro Up: Apply bias and flat Previous: tripp_write_image_log.pro

tripp_reduction.pro

What does it do?

reduced image = (original image - zero)/ flat
determines positional reference information for each image (find any suitable pivot point, not necessarily the object of interest)

Calling sequence

IDL> tripp_reduction, "imagelogfile" [,/mouse,csize=csize,search=search,$
                                       /debug,/silent,/no_intup,        $
                                       seeing=seeing, /recycle,maxshift=maxshift]

How do I use it?

One important part of what tripp_reduction does is the calibration of the raw images and the generation of reduced images. This however happens rather unnoticed by the user (unless the /debug keyword is set) as compared to the second part that tripp_reduction takes care of: it determines the shifts of the images relative to each other and saves this information for future use in the extraction process. The positioning information is also used to create a sum of all images, which will be used to define the extraction mask.
tripp_reduction needs a median zero (or set zero correction to no or to overscan in the imagelogfile) and median flat (or set flat correction to no in the imagelogfile) as specified in the imagelogfile. Also, you need to be able to identify a bright object as positional reference (it needs not to be the one you are interested in on the frame; this has changed with respect to former tripp versions). This object is called the "pivot point".
Try to run without any keywords or parameters first, and monitor the positioning process. If you have doubts about its success, switch on the /mouse keyword for an automatic quality control which will prompt you in case of significant trouble. If things are really bad, you should try a few more options before going through the whole interaction process with /mouse: Set the csize parameter to a different value (larger correlation area) and/or set the maxshift parameter to a value larger than 1. maxshift will allow maximum shifts maxshift times the selection radius (which is interpreted as a measure for the seeing). csize also often does change the chances for sucess significantly. search on the other hand only affects the tolerance for mouse clicks. If you wish more information to be printed out, i.e. prior to a possible error, try setting the /debug keyword; if you think you know what you're doing and want the program to work in silence, set the /silent keyword. This will not prevent the program from showing you all those frames where /mouse would provoque a stop if it were switched on. But even though tripp_reduction persists in warning you in those cases, it will continue the calculations and terminate without prompting for an interaction.
An interaction is always required when the sizes of the frames change; the (pivot point!) object has to be re-identified whenever this happens.
Be aware of the following bug: 5 digit numbers can only seemingly be handeled; in reality, there will be problems whenever the first digit changes within a single data set! A warning is issued by tripp_write_image_log when this is likely to happen.

next up previous contents
Next: Flux extraction Up: Apply bias and flat Previous: tripp_reduction.pro

tripp_show_pos.pro

What does it do?

Calling sequence

IDL> tripp_show_pos, "imagelogfile" [,/stop]

How do I use it?

Optional; shows you the pixel positions where tripp_reduction has found the object to be. Allows interactive changes to these positions and !overwrites! the respective position reference file - use with care. The /stop keyword makes possible truly hand-made changes; use with caution!


next up previous contents
Next: tripp_define_mask.pro Up: Routines chronological Previous: tripp_show_pos.pro

Flux extraction, relative fluxes, lightcurve

All procedures in this section are called by
procedure, "imagelogfile"

next up previous contents
Next: tripp_extract_flux.pro Up: Flux extraction Previous: Flux extraction

tripp_define_mask.pro

What does it do?

Automatically defines a mask containing fields for target and reference stars and sky fields that will be used later to extract the flux contained therein OR allows you to define the mask in a more interactive fashion (as in earlier versions, see below).

Calling sequence

IDL> tripp_define_mask, "imagelogfile" [, /no_cntrd,/no_intup, /mouse, /silent]

How do I use it?

If no keyword is set tripp_define_mask will automatically define a mask containing fields for target and reference stars and sky fields that will be used later to extract the flux contained therein. The 'Number of sources' from the logfile will be used to define an upper limit for target/reference stars. If the amount of objects found in the image is smaller than the 'Number of sources' in the logfile, tripp_define_mask will rescale the logfile entry. The pivot point is defined as target (Ref 1) if tripp_reduction has been run before. The rest of the mask objects are selected by brightness in a decreasing order until the 'Number of sources' from the logfile is reached. Sky fields are first positioned automatically; once all fields are set, tripp_define_mask allows you to move around the sky fields with your mouse. If you are not satisfied with the size of the extraction circles for the stars, the extraction fields for the sky or the total number of stars, re-run tripp_write_image_log to edit the respective entries, and run tripp_define_mask again. Iterate until you like the mask. Sometimes, changing the total number or minimum and maximum sizes for the extraction radii will result in an error where the "selected extraction radius does not match available radii". This is due to numerical problems when doing the comparison; in this case, the somewhat extreme measure of throwing away all existing reduction product files (except the log file which had better be in a different directory anyways) and starting over should help.
Setting the keyword /mouse will allow the user to manually select target/reference stars (otherwise the target/reference stars and extraction areas are defined automatically). The first object you click on has to be the object you're interested in; the following objects represent the pool of possible reference stars to choose from later. The object you`re interested in is proposed as Ref 1. In contrast to earlier versions, it needs not to be the one you selected in tripp_reduction as the pivot point.
If the keyword /silent is set no user interaction is possible. In contrast to a setup without the /mouse keyword set, the suggested background fields cannot be moved. /silent allows tripp_define_mask to run without any interaction. It is completely ignrored, however, if /mouse is also set.

next up previous contents
Next: tripp_show_raw.pro Up: Flux extraction Previous: tripp_define_mask.pro

tripp_extract_flux.pro

What does it do?

Determines the flux and area in which the flux is extracted for all extraction radii for all objects (stars) and for the 6 background fields assigned to each of them. Furthermore, the time stamp for each image is extracted. The results are saved in the .flx binary file.

Calling sequence

IDL> tripp_extract_flux, "imagelogfile" [,/silent, /no_cntrd, $
                                                   /intup, /recycle,    $
                        framenumbers=framenumbers, frameshift=frameshift]

How do I use it?

This is the most time consuming step. It is at the same time the procedure where the time marks are extracted from the fits file headers (or from the file attributes). As mentioned in the description for the writing of the imagelogfile (tripp_write_image_log), the subroutine tripp_get_gjd may have to be customized for this to work properly.

The /silent keyword will prevent the appearance of plots (they somewhat slow down the running of the process); it is nevertheless recommended to monitor the extraction process. tripp_extract_flux tries to re-center the aperture onto the star it is working with; should you prefer to prevent this for some reason, please set the /no_cntrd keyword.

As an additional feature, tripp_extract_flux can again output the sum of all images , correctly shifted onto each other, as a new fits file, as already done before by tripp_reduction. Set the /intup keyword to do this again with the very final positioning information. This will slow down tripp_extract_flux even more, but it's worth watching ...! In fact, this is more than just "for fun": The intup image is the ultimate test for the quality of the positioning process, and it can alert you about background stars that are usually exactly where you thought there is only sky background ... of course in such a case you have to start over all the way from tripp_define_mask on.

Images taken with the frame shift method can be extracted when the framenumbers and frameshift parameters are set appropriately: framenumbers is basically the number of images of a single star after readout, frameshift is the number of pixels by which the images are shifted. Last image is shifted twice that distance; mask has to be made for the opposite, i.e first star image in time! Time marks are not reliable yet, this needs further attention. (Optimized for BUSCA).

Recent tests concerning the sky measurement revealed that using the median from the individual backgrouds yields better results than using the bottom level that a gauss fit to the stellar image finds which is closer to the mean. (/skyfit keyword, only informational so far and no changes planned at the moment, due to the above test results).



next up previous contents
Next: tripp_calc_relflux.pro Up: Flux extraction Previous: tripp_extract_flux.pro

tripp_show_raw.pro

What does it do?

Plot lightcurves of raw counts (stars and background) to check quality (for the predefined selection radius only): Reads the .flx file and produces a postscipt file from it. The shown background fluxes are scaled to the expected number of counts in the extraction areas for the sources.
Panel 1 "Raw counts star": fluxs[k,*,rad_ind]: flux of object k
Panel 2 "Raw counts background": fluxb[k,*]*areas[k,*,rad_ind]/areab[k,*]
Panel 3 "Raw counts star - background": fluxs[k,*,rad_ind]-fluxb[k,*]*areas[k,*,rad_ind]/areab[k,*]

Calling sequence

IDL> tripp_show_raw, "imagelogfile" [, y_max=y_max, y_min=y_min, $
                                          x_max=x_max, x_min=x_min]

How do I use it?

Optional; allows you to look at the sky conditions, check for variability of comparison stars etc. The defaults for the plotting ranges should work well in most cases; however if they don't you can force them to different values by setting the appropriate parameters.

next up previous contents
Next: tripp_show_relflux.pro Up: Flux extraction Previous: tripp_show_raw.pro

tripp_calc_relflux.pro

What does it do?

Reads the *.flx file and outputs an *.rms file for each extraction radius.

First, the background contribution is scaled to match the area from which the source counts were extracted and is then subtracted from the source flux (for all sources): 
   reducedcounts = sourcecounts - (scaled backgroundcounts)
These background corrected counts are now converted to counts per second: 
   reducedflux = reducedcounts/exposuretime
Build a super reference star by adding up the fluxes of all requested reference stars:
(The noise can usually be reduced by using more than one reference star. It is advisable, however, to actually test several combinations, and in particular to test the reference stars one against the other(s) in order to get the most stable result.) 
   superrefstarflux = sum(all requested reducedfluxes)
   objectflux       = reducedflux[0]
Calibrate the object by comparing it to the super reference star: 
   relativeflux = objectflux   / superrefstarflux 
              ( = objectcounts / superrefstarcounts )
or calibrate the object by correcting fluctuations without changing the average of the object counts: 
   relativeflux = objectflux / superrefstarflux*mean(superrefstarflux) 
                = objectflux / ~1.

Calling sequence

IDL> tripp_calc_relflux, "imagelogfile" [,/rectify]

How do I use it?

The maximal number x of stars to be included in the formation of the Super - Reference star has been specified in the image log (first GUI). The stars used are the first x of those given as comparison stars in the second GUI. Edit the image log and re-run tripp_calc_relflux if, for example after having looked at the output of tripp_show_raw, you want to exclude some of the stars used, or if you want to use more of the stars, provided they are available from the definition of the aperture mask. It is helpful to not only change the number of comparison stars in the first GUI, but to also include only the stars that are really being used in the end in the second GUI, for consistency when reading the logfile and to tell you at a glance which stars are used as references.

The /rectify keyword has the effect that the mean of the super reference star is set to one before the relative flux is determined; thus the average counts per second of the object remain unaltered, but are still being corrected for changes in transparency etc.

next up previous contents
Next: tripp_write_relflux.pro Up: Flux extraction Previous: tripp_calc_relflux.pro

tripp_show_relflux.pro

What does it do?

Displays the results of tripp_calc_relflux.pro in a series of postscript files: fclean = fneu[k,idx] for all objects k (consecutive pages of a file), and every second extraction radius (individual files).

Shown is either the relative flux alone 
   
   relativeflux = (objectcounts/exptime) / (superrefstarcounts/exptime) 
                = objectflux / superrefstarflux
or the transparency-corrected counts per second for the object (in case the /rectify keyword was set in tripp_calc_relflux) 
   
   shownflux    = (objectcounts/exptime) / (superrefstarcounts/exptime) 
                                   * mean((superrefstarcounts/exptime)) 
                = (objectcounts/exptime) / ~1.

Calling sequence

IDL> tripp_show_relflux, "imagelogfile" [,/mouse]

How do I use it?

Optional; allows you take a first look at the lightcurves (and their periodograms) at all extraction radii. Choosing the final extraction radius can also be facilitated in the following way: Setting the /mouse keyword displays more quantitative information about the quality of the individual lightcurves at different extraction radii, and allows interactive changes to the selected extraction radius. This saves you from having to re-edit the logfile separately if you have changed your mind about the ideal extraction radius.


next up previous contents
Next: Final lightcurve Up: Flux extraction Previous: tripp_show_relflux.pro

tripp_write_relflux.pro

What does it do?

Write IDL-saved flux data (*.rms-file) from photometrical time series to ASCII file '*.DAT' containing reduced data as x,y- table: x corresponds to time in reduced Julian date, y corresponds to relative flux

Calling sequence

IDL> tripp_write_relflux, "imagelogfile" [,/norm]

How do I use it?



next up previous contents
Next: tripp_write_final.pro Up: Routines chronological Previous: tripp_write_relflux.pro

Final lightcurve of a dataset

All procedures in this section are called by
procedure, "imagelogfile"

next up previous contents
Next: tripp_write_error.pro Up: Final lightcurve Previous: Final lightcurve

tripp_write_final.pro

What does it do?

Clean IDL-saved flux data (*.rms-file) from photometrical time series and write to ASCII-file '*.FIN' containing reduced data as x,y- table: x corresponds to time in reduced Julian date, y corresponds to relative flux IDL SAVE File '*_idl.FIN' containing same data

Calling sequence

IDL> tripp_write_final, "imagelogfile" [,/norm, /mouse]

How do I use it?

Manipulation of the data curve can most easily be done by setting the /mouse keyword which has the effect that you will be prompted to edit the data interactively. The main purposes are to throw away funny data points and to correct for longterm trends (as can be induced by differental diffraction: Trends at dawn or dusk may be due to different colors of object and comparison stars).
You could also check the other possibilities you have in the procedure header: parameters may be given to make the cleaning process an automatic one.
Instead of a logfile name, this routine also accepts datafile names if they have one of the extensions *.dat, *.fin or *.all. (This is similar for tripp_show_all, but it does not work for tripp_show_final).

next up previous contents
Next: tripp_show_final.pro Up: Final lightcurve Previous: tripp_write_final.pro

tripp_write_error.pro

What does it do?

Calculate error for photometrical time series in '*.FIN' and write to ASCII file '*.ERR' containing time, relative flux and flux error as three-column table. Same data is stored in the IDL SAVE file '*_idl.ERR'.

Calling sequence

IDL> tripp_write_error, "imagelogfile" [,/silent]

How do I use it?

Relies on the output of tripp_write_final which has to be run before the use of tripp_write_error. Flux errors are calculated for each data point of the object, based on the weighted errors of object and reference stars. You may check the source fluxes displayed to decide whether a modification of the reference star selection via tripp_write_image_log is advisable.

next up previous contents
Next: Analyse combined data Up: Final lightcurve Previous: tripp_write_error.pro

tripp_show_final.pro

What does it do?

Calling sequence

IDL> tripp_show_final, "imagelogfile" [,/onepage]

How do I use it?

This is the last procedure to stricly follow the "logfile" scheme, as, beyond this point, it is quite probable that one might want to work with combined data sets. Changes (especially towards simplification of use) are to be expected for the following applications, and brief descriptions should then come on-line, too. One exception where the logfile is being used but where format changes should be expected is tripp_write_wetstandard. The principle idea for the rest of the routines is that they should in the future be usable both with logfiles or with datafiles directly (as in tripp_write_final).



next up previous contents
Next: tripp_calc_scargle.pro Up: Routines chronological Previous: tripp_show_final.pro

Analysis of combined datasets

Those final lightcurves from individual datasets which shall be combined for the subsequent analysis need to be catenuated by hand. You can thus easily choose which datasets you actually want to include. Check the file headers for the minimum requirements of an individual call to a routine, also for all following sections.

No detailed explanations are given here because there will be major changes. However, the documentation has been structured as if these changes had already taken place. This should simplify the transition. Short hints towards the current implementation are given, but do not expect compatibility of future versions beyond this point.

next up previous contents
Next: tripp_show_scargle.pro Up: Analyse combined data Previous: Analyse combined data

tripp_calc_scargle.pro

What does it do?

Periodogram analysis. Default settigs choose the frequency grid so that all the information that may theoretically be contained in the dataset will show up (i.e. all Fourier frequencies plus oversampling). Use period=period and psd=psd to recover the psd information; it is recommended to save these values if the periodogram calculation becomes time consuming due to a high sampling rate or a large time basis.

Calling sequence

At the moment only tripp_show_all.pro exists, but is to be replaced.

How do I use it?

DO NOT USE!


next up previous contents
Next: tripp_calc_epoc.pro Up: Analyse combined data Previous: tripp_calc_scargle.pro

tripp_show_scargle.pro

What does it do?

Calling sequence

At the moment only tripp_show_all.pro exists, but is to be replaced.

How do I use it?

DO NOT USE!


next up previous contents
Next: tripp_show_epoc.pro Up: Analyse combined data Previous: tripp_show_scargle.pro

tripp_calc_epoc.pro

What does it do?

Epoch folding, advantage: No sinusoidal signal assumed. Also returns the puls profile found.

Calling sequence

At the moment only tripp_show_epoc.pro exists, but is to be replaced.

How do I use it?

DO NOT USE!


next up previous contents
Next: Significance of periodogram Up: Analyse combined data Previous: tripp_calc_epoc.pro

tripp_show_epoc.pro

What does it do?

Calling sequence

At the moment only tripp_show_epoc.pro exists, but is to be replaced.

How do I use it?

DO NOT USE!


next up previous contents
Next: tripp_simfast.pro Up: Routines chronological Previous: tripp_show_epoc.pro

Statistical significance of periodogram peaks



next up previous contents
Next: Sinus fitting Up: Significance of periodogram Previous: Significance of periodogram

tripp_simfast.pro

What does it do?

Functionality is to be incorporated in tripp_calc_scargle.pro (and tripp_calc_epoc.pro?).

Calling sequence

How do I use it?

DO NOT USE!
Now run tripp_show_all again, but make sure the frequency grids are still the same!


next up previous contents
Next: tripp_write_sinfitpar.pro Up: Routines chronological Previous: tripp_simfast.pro

Sinus fitting

You need to write a parameter file first.

next up previous contents
Next: tripp_sinfit.pro Up: Sinus fitting Previous: Sinus fitting

tripp_write_sinfitpar.pro

What does it do?

Reads an existing par file or creates an empty one (to control tripp_sinfitt) and allows manipulation via a GUI (very similar to logfiles). Checks bounds, saves updated version(s) of parameter file (currently parfile_nosort, parfile_persort and parfile_ampsort; - including reduced or increased total number of periods considered), and outputs a tex table and a plot showing the same information.

Calling sequence

IDL> tripp_write_sinfitpar, "parfile"

How do I use it?

DO NOT USE!




next up previous contents
Next: Simulation of lightcurves Up: Sinus fitting Previous: tripp_write_sinfitpar.pro

tripp_sinfit.pro

What does it do?

Fits fourth-degree polynomial and multi-periodic sine fit to data in datafile, using constraints, start values and bounds given in parfile.

Calling sequence

IDL> tripp_sinfit,"datafile",wc,"parfile"

How do I use it?

DO NOT USE!
Wants a datafile and a parameter file. If you want to use tripp_sinfit, this is what the parameter file may look like. If available in your version, try the experimental tripp_write_sinfitpar.pro to produce or edit it.



next up previous contents
Next: tripp_simulate.pro Up: Routines chronological Previous: tripp_sinfit.pro

Simulation of lightcurves



next up previous contents
Next: Helpers Up: Simulation of lightcurves Previous: Simulation of lightcurves

tripp_simulate.pro

What does it do?

Calling sequence

How do I use it?

You may analyse this theoretical lightcurve just like the real one: use tripp_show_all to look at the periodogram, tripp_simfast to find the significance levels, tripp_sinfit to recover the periods used etc. /profile keyword: Uses puls profile from epoch folding instead of sinusoidal puls profile.



next up previous contents
Next: tripp_get_magamp.pro Up: Routines chronological Previous: tripp_simulate.pro

Helpers



next up previous contents
Next: tripp_write_wetstandard.pro Up: Helpers Previous: Helpers

tripp_get_magamp.pro

What does it do?

Converts intensity variation to magnitude and vice versa (wait for prompt).

Calling sequence

How do I use it?



next up previous contents
Next: tripp_plot_period.pro Up: Helpers Previous: tripp_get_magamp.pro

tripp_write_wetstandard.pro

What does it do?

Calling sequence

How do I use it?

DO NOT USE!


next up previous contents
Next: tripp_deltat Up: Helpers Previous: tripp_write_wetstandard.pro

tripp_plot_period.pro

What does it do?

Calling sequence

How do I use it?



next up previous contents
Next: tripp_gc Up: Helpers Previous: tripp_plot_period.pro

tripp_deltat.pro

What does it do?

Calling sequence

How do I use it?



next up previous contents
Next: Subroutines Up: Helpers Previous: tripp_deltat.pro

tripp_gc.pro

What does it do?

Calling sequence

How do I use it?



next up previous contents
Next: Logfiles handling Up: Routines chronological Previous: tripp_gc.pro

Subroutines called by above programs



next up previous contents
Next: Data Reduction Up: Subroutines Previous: Subroutines

Logfiles handling

tripp_zerolog_type.pro
tripp_zerolog_gui.pro
tripp_read_zero_log.pro

tripp_flatlog_type.pro
tripp_flatlog_gui.pro
tripp_read_flat_log.pro

tripp_log_type.pro
tripp_log_gui.pro
tripp_log_gui2.pro
tripp_log_combine.pro
tripp_checklog.pro
tripp_read_image_log.pro


next up previous contents
Next: Periodogram analysis Up: Subroutines Previous: Logfiles handling

Data Reduction

tripp_read_frames.pro
tripp_display_frames.pro
tripp_tv.pro
tripp_quad.pro
tripp_new_image_size.pro
tripp_flux.pro
tripp_get_gjd.pro
tripp_write_pos.pro
tripp_read_pos.pro
tripp_recycle_flux.pro
tripp_rad_plot.pro


next up previous contents
Next: Fitting routines Up: Subroutines Previous: Data Reduction

Periodogram analysis and significance levels

tripp_smooth.pro
tripp_setsimpar.pro
scargle.pro

next up previous contents
Next: Others Up: Subroutines Previous: Periodogram analysis

Fitting routines

tripp_curvefit.pro
tripp_fit_sinus.pro
tripp_plot_periodogram


next up previous contents
Next: Bottom of page Up: Subroutines Previous: Fitting routines

Others

tripp_shade3.pro
tripp_exist.pro
tripp_write_list.pro
ccd/
timing/
astrolib/


Difference Imaging

This branch is under development. It is currently not publicly available. The procedures are, however, availabe to local TRIPP developers from the Göttingen subversion repository: look for the subtraction branch.


tripp_write_image_log,"imagelogfile"
tripp_reduction, "imagelogfile"
tripp_prepare_subtraction, "imagelogfile"
tripp_subtraction, "imagelogfile"
tripp_stack, "imagelogfile", /diffim
tripp_define_mask, "imagelogfile"
tripp_extract_flux, "imagelogfile"


tripp_write_image_log.pro

What does it do?

This is an adaptation of tripp_write_image_log to the log file format used for difference imaging. The parameters of difference imaging are controlled via a third, optional, GUI.

Calling sequence

IDL> tripp_write_image_log, "imagelogfile"

How do I use it?

In this manual, only those features are explained which deviate from the trunk routines.

Difference imaging is switched on by setting the additional button subtraction photometry in the first GUI to yes. Then, after clicking OK on the second GUI, a third one is evoked. In the current version of the subtraction branch, selection of a filelist is mandatory. The uppermost filelist entry will be chosen as Optimal Image Subtraction reference frame. Therefore, the best seeing image should be placed on top of the list. For selection of the reference is further explained in the section on the reference file list below. Most important for the success of difference imaging are the parameter whose values are specified using the third GUI.

Image Gui - click to enlarge Third GUI    

Remarks on the individual entry fields:
  • Left side (short fields)
    • Degree Gaussian #g: For g=1...4, these are the maximal degrees of polynomial variation used with the principal Gaussian components of the PSF fitting kernel. With a value of zero, only the unmodified Gaussian is fitted. A component is deactivated by setting a negative value. Components at higher g are then deactivated, as well.
      For the maximal degrees, even numbers which do not increase with g should be chosen. The default is one of the most efficient sets of maximal degrees. Increasing maximal degrees to values d>4 improves reductions, but is inefficient due to prolonged runtime of tripp_subtraction.
    • Background Degree: The degree up to which background differences between reference and data images are fitted. The meanings of zero and negative values are the same as for the maximal degrees. A background degree in the interval 0≤dbg≤3 should be chosen. With small image segments (see below), smaller values are appropriate.
  • Right side:
    • x width #g, y width #g: For g=1...4, these are the widths of the Gaussian kernel basis function, as given by their x- and y-components. Together with the maximal degrees, the kernel widths are the main parameters to Optimal Image Subtraction, as they determine which convolution kernels can be formed.
      In principle, kernel widths can be chosen independently. Distinction between x- and y-components should only be made for fine-tuning, though. Geometrical series of kernel widths have proven to be convenient. The detailed relation between sampling of reference and data frames and the choice of kernel widths will be explained in an upcoming paper. The defaults should provide satisfactory first guesses in many situations.
  • Left side (long fields):
    • Kernel Size x/y: Dimension of the IDL array used for the representation of the kernel and its basis functions. Should be an odd number, and the same in x and y. If possible, use the defaults.
    • Partitions along x/y: Number of subdivisions on the image along its axes in which it is processed for the sake of a shorter runtime. The segments defined here are also used for the computation of local convolution kernels. Therefore, partitions numbers should be set such that resulting segments will be larger, but noch much larger, than the convolution kernel.
    • Saturation Limit: Pixels showing values above this limit will be considered saturated resp. having a nonlinear response. They will be precluded from the determination of fit parameters by a saturation mask also including contamination from these pixels due to the convolution.
    • Reference Image List: Path to the filelist of images selected to contribute to a "super-reference" frame. Using tripp_subtraction, images will be matched in PSF and background to the image given as uppermost item of the reference file list. If this field remains empty, that single image will be used as reference frame. The number of images in the reference list should be small compared to the data file list. No images with more than 1.2 times the best seeing value should be selected.
    • Singular Value Thresh.: TRIPP uses Singular Value Decomposition for the solution of the linear problem of Optimal Image Subtraction. Dimensions with small singular values do not contribute significantly to the solution but introduce additional errors. If the ratio of a singular value to the largest singular value is smaller than the threshold defined here, it will be edited to zero and disappear from the solution. The threshold should be set to the machine precision times the number of pixels in an image.
    • Var. Detection Thresh.: Determines the level above the background noise in the images "Variables" at which a source is considered for automatic detection. The parameter multiplied with the "background" in the variables image is passed to the keyword hmin in find (as a subroutine of tripp_define_mask).


    tripp_reduction.pro

    What does it do?

    The purpose is the same as in the trunk version from which it differs in the details of the positioning process.

    Calling sequence

    tripp_reduction, "imagelogfile" [, csize=csize, maxshift=maxshift, clen=clen, /medflt, ... ]

    How do I use it?

    The important keyword is csize which should be set to the largest image dimension. Then, entire images will be correlated, preventing erroneous identification of the pivot star which is common for dense fields and low values of csize. If image alignments continues to fail at sensible settings of csize and maxshift, using the trunk version will probably be the easiest alternative.

    tripp_prepare_subtraction.pro

    What does it do?

    The effects of this procedure are threefold:
    • Interpolation of all frames to the coordinate frame of the uppermost image in the stack by applying the appropriate shifts from tripp_reduction using bicubic splines.
    • Identification and tracking of saturated and edge pixels by the means of a saturation mask. Removal of cosmics.
    • Stacking of preselected images from the reference file list to form a super-reference image. For this purpose, tripp_subtraction and tripp_stack are called internally. If no reference file list is specified, the uppermost image from the data list will be used as reference.

    Note that this is currently a quite time-consuming step.
    This procedure calls (or rather, can call, if the reference filelist is not empty) tripp_subtraction and tripp_stack, leading to somewhat complicated dependencies.

    Calling sequence

    tripp_prepare_subtraction, "imagelogfile" [, n_sigma=n_sigma, rsize=rsize, lim=lim, /abspos, /silent ]

    How do I use it?

    Generally, the parameters in tripp_prepare_subtraction do not need to be edited. Their properties in brief:
    • n_sigma: Threshold, given in standard deviations of the images histogram, above which a positive deviation is regarded as a cosmic and filtered. Passed to sigma_filter from astrolib.
    • rsize: Half-size of the square input array centered on the query point for spline interpolation.
    • lim: With query points in less than the specified distance to an original grid point, the original point's value is used, bypassing interpolation.
    • abspos: If this keyword is set, input position will be interpreted as absolute coordinates rather than relative shifts. Enables the use of .pos-files obtained with the trunk version of tripp_reduction.

    In the long run, the subroutine tripp_spline_shift, doing the interpolation, is going to be replaced by some C code, thus reducing runtime. A preliminary version of this already exists.

    tripp_subtraction.pro

    What does it do?

    The actual Optimal Image Subtraction algorithm is applied here: Basis images are formed by convolving the reference frame with the selected basis functions. In a least squares fit, the convolution kernel and differential background correction are determined for each data image.

    Calling sequence

    tripp_subtraction, "imagelogfile" [, output, segments=segments, lorentz=lorentz, /ref_construct, /silent ]

    How do I use it?

    Having a glimpse on the difference images provides valuable information whether image subtraction has been successful. Residuals of "constant" stars should be at a low level such that they are indistinguishable from random noise. Important quantities like the chi-square-estimator and reduction parameters are tabulated in the .sub-file. Calling tripp_subtraction with two variables is equivalent to the "debug" keyword in other TRIPP routine. While there is more screen output, the additional parameter contains IDL arrays helpful for debugging.

    The use of local convolution kernels: As default, a single, global convolution kernel is applied to the entire image. Images are processed in segments; borders and numbers of this segments are displayed when running tripp_subtraction. In a subsequent re-run of tripp_subtraction - but no other routines! - image subtraction in sections of interest can be improved by the computation of a local convolution kernel obtained from and valid for these sections. The global kernel still valid for the remaining sections won't be changed by that.
    The indices of segments to be computed locally are supplied by the segments vector. Negative elements will evoke the computation of local kernels for each segment, while for elements exceeding the range of segment indices, as in the default, only the global kernel will be determined.
    Local computation of convolution kernel is a means to cope with spatial PSF variation. This is not the variable convolution kernel from Alard, A&AS 144, 363, (2000), but an alternative method! It is also useful in less-crowded fields such that stars can in principle be matched individually.

    tripp_stack.pro

    What does it do?

    From a stack of input frames, an averaged image is formed from the values found at the same pixel position in the different images of the stack.

    Calling sequence

    tripp_stack, "imagelogfile" [, /diffimg, /simple, /nosmooth, /silent]

    How do I use it?

    This procedure is used twice during a reduction.

    For the construction of the super-reference frame, it is called automatically by tripp_prepare_subtraction on the interpolated images using the nosmooth option. The subroutine tripp_comp_stack is called for the averaging which includes an additional cosmic correction. There is nothing that needs to be done in this call.

    The second call to tripp_stack is after tripp_subtraction, where difference images are averaged for obtaining an enhanced signal/noise for source detection. Both the arithmetic mean and the intensity-weighted arithmetic mean are computed, while only the latter is used for the actual detection process. The two images are useful for visual inspection of the outcome of image subtraction. You must turn on the diffimg keyword for this to work. Use of the simple keyword which switches out tripp_comp_stack in favour of the arithmetic mean is strongly recommended as well.

    tripp_define_mask.pro

    What does it do?

    This is a version of tripp_define_mask from trunk which has been adopted to difference imaging, with the significant changes in tripp_define_mask_autohelp, i.e. the automated source detection. It is used for detecting variable sources in the amplitude-weighted "Variables" image from tripp_stack.

    Calling sequence

    IDL> tripp_define_mask, "imagelogfile" 
[, /no_cntrd,/no_intup, /mouse, /silent]

    How do I use it?

    The same way as in the trunk version. If the signal/noise in your sources is low, you should use the no_cntrd keyword.

    tripp_extract_flux.pro

    What does it do?

    This is a version of tripp_extract_flux from trunk which has been adopted to difference imaging. In addition to the features of the trunk procedure, it brings the lightcurve data for output into chronological order.

    Calling sequence

    IDL> tripp_extract_flux, "imagelogfile" [,/silent, /no_cntrd, $
                                                   /intup, /recycle,    $
                        framenumbers=framenumbers, frameshift=frameshift]

    How do I use it?

    The same way as in the trunk version. Because of the low signal/noise in the individual difference images this version processes, use of the no_cntrd keyword is recommended.

    Beyond this point,

    restore the flux file and ... deal with it.




You might find additional useful information on the developer's pages.