1. Home

AAVSO Extended File Format

Version: 1.2
Release Date: July 27, 2011 (latest update: June 13, 2017)

This is one of two plain text (ASCII) formats that the AAVSO accepts for uploading a file of variable star observations. Please use the WebObs File Upload page to upload your file in the AAVSO Extended Format. The other format, which is intended for visual observers, is called the AAVSO Visual File Format.

Visit the Software that exports to AAVSO format page to help format your observations.

The extended format has two components: parameters and data. Each component is discussed in detail below.

The format is not case sensitive.

Parameters

The Parameters are specified at the top of the file and are used to describe the data that follows. Parameters must begin with a pound sign (#) at the start of the line. There are six specific parameters that we require to exist at the top of the file. Personal comments may also be added as long as they follow a pound sign (#). These comments will be ignored by the software and not loaded into the database. However, they will be retained when the complete file is stored in the AAVSO permanent archives.

The six parameters that we require are:

#TYPE=Extended
#OBSCODE=
#SOFTWARE=
#DELIM=
#DATE=
#OBSTYPE=

The six parameters explained:

  • TYPE: Should always say Extended for this format.
  • OBSCODE: The official AAVSO Observer Code for the observer which was previously assigned by the AAVSO.
  • SOFTWARE: Name and version of software used to create the format. If it is private software, put some type of description here. For example: "#SOFTWARE=AIP4Win Version 2.2". Limit: 255 characters.
  • DELIM: The delimiter used to separate fields in the report. Any ASCII character or UNICODE number that corresponds to ascii code 32-126 is acceptable as long as it is not used in any field. Suggested delimiters are: comma (,) semi-colon(;), exclamation point(!), and pipe(|). The only character that cannot be used is the pound (#) and the " " (space). If you want to use a tab, use the word "tab" instead of an actual tab character. Note: Excel users who want to use a comma will have to type "comma" here instead of a ",". Otherwise Excel will export the field incorrectly.
  • DATE: The format of the date used in the report. Times are midpoint of the observation. Convert all times from UT to one of the following formats:
    • JD: Julian Day (Ex: 2454101.7563)
    • HJD: Heliocentric Julian Day
    • EXCEL: the format created by Excel's NOW() function (Ex: 12/31/2007 12:59:59 a.m )
  • OBSTYPE: The type of observation in the data file. It can be CCD, DSLR, PEP (for Photoelectric Photometry), or VISDIG (for VISual observations made from DIGital images). If absent, it is assumed to be CCD.  [If you are submitting photographic/photovisual observations, please use the Visual File Format instead of the Extended File Format. See the Visual File Format explanation for details.]

The OBSCODE and DATE parameters may also be included elsewhere in the data. Our data processing software will read these parameters and will expect all following data to adhere to them. (For example, you can add "#OBSCODE=TST01" to the report and all subsequent observations will be attributed to observer TST01.)

If you want to put a blank line between your parameter records and your data records, be sure to comment the line out with the pound sign (#). WebObs will not accept a file with blank lines that are not commented out.

Data

After the parameters comes the actual variable star observations. There should be one observation per line and the fields should be separated by the same character that is defined in the DELIM parameter field. If you do not have data for one of the optional fields, you must put "na" as a place holder. The list of fields are:

  • STARID: The star's identifier. It can be the AAVSO Designation, the AAVSO Name, or the AAVSO Unique Identifier, but NOT more than one of these. Limit: 30 characters.
  • DATE: The date of the observation, in the format specified in the DATE parameter. Limit: 16 characters.
  • MAGNITUDE: The magnitude of the observation. Prepend with < if a fainter-than.  A dot is required (e.g. "9.0" rather than "9"). Limit: 8 characters.
  • MAGERR: Photometric uncertainty associated with the variable star magnitude. If not available put "na". Limit: 6 characters.
  • FILTER: The filter used for the observation. This can be one of the following letters (in bold):
    • U: Johnson U
    • B: Johnson B
    • V: Johnson V
    • R: Cousins R
    • I: Cousins I
    • J: NIR 1.2 micron
    • H: NIR 1.6 micron
    • K: NIR 2.2 micron
    • TG: Green Filter (or Tri-color green). This is commonly the "green-channel" in a DSLR or color CCD camera. These observations use V-band comp star magnitudes.
    • TB: Blue Filter (or Tri-color blue). This is commonly the "blue-channel" in a DSLR or color CCD camera. These observations use B-band comp star magnitudes.
    • TR: Red Filter (or Tri-color red). This is commonly the "red-channel" in a DSLR or color CCD camera. These observations use R-band comp star magnitudes.
    • CV: Clear (unfiltered) using V-band comp star magnitudes (this is more common than CR)
    • CR: Clear (unfiltered) using R-band comp star magnitudes
    • CBB: Clear with blue-blocking (used for exoplanet observations).
    • SZ: Sloan z
    • SU: Sloan u
    • SG: Sloan g
    • SR: Sloan r
    • SI: Sloan i
    • STU: Stromgren u
    • STV: Stromgren v
    • STB: Stromgren b
    • STY: Stromgren y
    • STHBW: Stromgren Hbw
    • STHBN: Stromgren Hbn
    • MA: Optec Wing A
    • MB: Optec Wing B
    • MI: Optec Wing C
    • ZS: PanSTARRS z-short (APASS)
    • Y: PanSTARRS y (APASS)
    • HA: H-alpha
    • HAC: H-alpha continuum
    • O: Other filter not listed above, must describe in Comments. Please Note: Due to a problem in WebObs, this filter choice is currently unavailable. Please consider removing your filter and using CV or TB/TV/TR instead.
  • TRANS: YES if transformed using the Landolt Standards or those fields that contain secondary standards, or NO if not. Document the method used to transform in the "NOTES" section.
  • MTYPE: Magnitude type. STD if standardized (Click here for definition of standardized) or DIF if differential (very rare). If you are currently using ABS for 'absolute' we will still accept it. Differential requires the use of CNAME.
  • CNAME: Comparison star name or label such as the AUID (much preferred) or the chart label for the comparison star used. If not present, use "na". Limit: 20 characters.
  • CMAG: Instrumental magnitude of the comparison star. If "ensemble" see example below. If not present, use "na". Limit: 8 characters.
  • KNAME: Check star name or label such as the AUID (much preferred) or the chart label for the check star. If not present, use "na". Limit: 20 characters.
  • KMAG: Instrumental magnitude of the check star. If "ensemble" see example below. If not present, use "na".Limit: 8 characters.
  • AIRMASS: Airmass of observation Limit 7 characters - entry will be truncated if longer than that. If not present, use "na".
  • GROUP: Grouping identifier (maximum 5 characters). It is used for grouping multiple observations together, usually an observation set that was taken through multiple filters. It makes it easier to retrieve all magnitudes from a given set in the database, say, if someone wanted to form color indices such as (B-V) with them. If you are just doing time series, or using the same filter for multiple stars, etc., just set GROUP to "na." For cases where you want to group observations, GROUP should be an integer, identical for all observations in a group, and unique for a given observer for a given star on a given Julian Date. Limit: 5 characters.
  • CHART: Please use the sequence ID you will find written in Bold print near the top of the photometry table in a sentence that reads "Report this sequence as [ID] in the chart field of your observation report." If a non–AAVSO sequence was used, please describe it as clearly as possible. Limit: 20 characters.
  • NOTES: Comments or notes about the observation. If no comments, use "na". This field has a maximum length of several thousand characters, so you can be as descriptive as necessary. One convention for including a lot of information as concisely as possible is to use subfields in the format |A=B; the '|' character is the separator, A is a keyvalue name and B is its value. If you need an alternative delimiter from '|', use it but preceed the first instance with "DELIM=". Using this mechanismnyou can document your transform process in more detail. Here is an example as used by TransformApplier: 
    5 records aggregated|VMAGINS=-7.244|VERR=0.006|CREFMAG=13.793|CREFERR=0.026|
KREFMAG=14.448|KREFERR=0.021|VX=1.1501|CX=1.1505|KX=1.1500|Tv_bv=0.0090|Tv_bvErr=0.0100|
TAver=2.47

Examples

1. A simple example:
#TYPE=EXTENDED
#OBSCODE=TST01
#SOFTWARE=IRAF 12.4
#DELIM=,
#DATE=JD
#NAME,DATE,MAG,MERR,FILT,TRANS,MTYPE,CNAME,CMAG,KNAME,KMAG,AMASS,GROUP,CHART,NOTES
SS CYG,2450702.1234,11.135,0.003,V,NO,STD,105,na,na,na,na,na,X16382L,This is a test

 

Note the existence of the #NAME,DATE... line in the above format. Since it is prepended with a #, it will be ignored by our software. Feel free to do this if it makes writing and reading the format easier for you.

2. A little more information:
#TYPE=EXTENDED
#OBSCODE=TST01
#SOFTWARE=GCX 2.0
#DELIM=,
#DATE=JD
#OBSTYPE=CCD
#NAME,DATE,MAG,MERR,FILT,TRANS,MTYPE,CNAME,CMAG,KNAME,KMAG,AMASS,GROUP,CHART,NOTES
SS CYG,2450702.1234,11.235,0.003,B,NO,STD,105,10.593,110,11.090,1.561,1,X16382L,na 
SS CYG,2450702.1254,11.135,0.003,V,NO,STD,105,10.594,110,10.994,1.563,1,X16382L,na 
SS CYG,2450702.1274,11.035,0.003,R,NO,STD,105,10.594,110,10.896,1.564,1,X16382L,na 
SS CYG,2450702.1294,10.935,0.003,I,NO,STD,105,10.592,110,10.793,1.567,1,X16382L,na

Note the existence of the #NAME,DATE... line in the above format. Since it is prepended with a #, it will be ignored by our software. Feel free to do this if it makes writing and reading the format easier for you.

3. Ensemble photometry example:

Ensemble photometry is permitted under this format. You need to pick one star (the check star) in addition to the target to be measured by the technique. The check star should not be included in the comparison-star ensemble. This star's calculated magnitude should be put in the KMAG field, so that if the true magnitude of the check star is found to be different at a later date, a simple zeropoint offset can be added to your ensemble value. If ensemble is used, CNAME should be set to ENSEMBLE and CMAG should be set to "na", as shown below.

#TYPE=EXTENDED
#OBSCODE=TST01
#SOFTWARE=GCX 2.0
#DELIM=,
#DATE=JD
#NAME,DATE,MAG,MERR,FILT,TRANS,MTYPE,CNAME,CMAG,KNAME,KMAG,AMASS,GROUP,CHART,NOTES
SS CYG,2450702.1234,11.235,0.003,B,NO,STD,ENSEMBLE,na,105,10.593,1.561,1,X16382L,na 
SS CYG,2450702.1254,11.135,0.003,V,NO,STD,ENSEMBLE,na,105,10.492,1.563,1,X16382L,na 
SS CYG,2450702.1274,11.035,0.003,R,NO,STD,ENSEMBLE,na,105,10.398,1.564,1,X16382L,na 
SS CYG,2450702.1294,10.935,0.003,I,NO,STD,ENSEMBLE,na,105,10.295,1.567,1,X16382L,na 
SS CYG,2450702.2234,11.244,0.003,B,NO,STD,ENSEMBLE,na,105,10.590,1.661,2,X16382L,na 
SS CYG,2450702.2254,11.166,0.003,V,NO,STD,ENSEMBLE,na,105,10.497,1.663,2,X16382L,na 
SS CYG,2450702.2274,11.030,0.003,R,NO,STD,ENSEMBLE,na,105,10.402,1.664,2,X16382L,na 
SS CYG,2450702.2294,10.927,0.003,I,NO,STD,ENSEMBLE,na,105,10.292,1.667,2,X16382L,na

This means your ensemble solution gave 11.235, 11.135, 11.035 and 10.935 for the B,V,Rc, and Ic (respectively) magnitudes of SS Cyg for the first group, and 11.244, 11.116, 11.030 and 10.927 for the second group. Your ensemble solution also gave 10.593, 10.492, 10.398, and 10.295 for the BVRcIc magnitudes of the check star for the first group.

4. Differential photometry example (not recommended):

Differential photometry is permitted under this format. CNAME should be the name of the comparison star (chart label, GSC number, etc.), CMAG should be its instrumental magnitude, KNAME should be the name of the check star and KMAG should be the instrumental magnitude of the check star. In this manner, HQ can calculate (K-C) to determine a time-series error, and HQ can also adjust the MAG field if at some later date the true standard magnitude of the comparison star becomes known. We highly recommend that you use "STD" (standardized) instead of DIF (differential) as your data will not appear on the light curve generator, nor be properly validated otherwise. Here is an example of the differential format:

#TYPE=EXTENDED
#OBSCODE=TST01
#SOFTWARE=GCX 2.0
#DELIM=,
#DATE=JD
#NAME,DATE,MAG,MERR,FILT,TRANS,MTYPE,CNAME,CMAG,KNAME,KMAG,AMASS,GROUP,CHART,NOTES
SS CYG,2450702.1234,1.065,0.003,B,NO,DIF,105,10.170,110,11.090,1.561,1,X16382L,na 
SS CYG,2450702.1254,1.114,0.003,V,NO,DIF,105,10.021,110,10.994,1.563,1,X16382L,na 
SS CYG,2450702.1274,1.001,0.003,R,NO,DIF,105,10.034,110,10.896,1.564,1,X16382L,na 
SS CYG,2450702.1294,.988,0.003,I,NO,DIF,105,9.947,110,10.793,1.567,1,X16382L,na
Tags
observing
extended format