AAVSO Visual File Format

Version: 1.0
Release Date: January 15, 2008

This is one of two plain text (ASCII) formats that the AAVSO accepts for variable star observations. Observations in this format may be submitted using the WebObs File Upload Tool. The other format is intended for CCD, DSLR, PEP, and VISDIG (visual observations made from digital images) observers and is called the AAVSO Extended File Format.

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

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

The format is not case sensitive. The only acceptable file extensions are .txt, .csv, and .tsv.

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=Visual
#OBSCODE=
#SOFTWARE=
#DELIM=
#DATE=
#OBSTYPE=

The six parameters explained:

  • TYPE: Should always say Visual 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=Excel Spreadsheet by Gary Poyner." Limit: 255 characters.
  • DELIM: The delimiter used to separate fields in the report. Any ASCII character or ASCII code 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(;), or exclamation point(!). The only characters that cannot be used are the pipe(|), the pound/hash (#) or 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. Convert all times from UT to one of the following formats (in order of preference):
    • JD: Julian Date (Ex: 2454101.7653)
    • HJD: Heliocentric Julian Date
    • EXCEL: The format created by Excel's NOW() function (Ex: 12/31/2007 12:59:59 a.m - seconds are optional)
  • OBSTYPE: The type of observation in the data file. It can be Visual or PTG (for Photographic); DSLR observations should be submitted using the Extended File format. If absent, it is assumed to be Visual. If PTG, place a description of your film response and any filter(s) used in the notes field of each observation.

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.)

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. Do not include an extra delimiter at the end of the line. The list of fields are:

  • NAME: The star's identifier. It can be the AAVSO Designation, the AAVSO Name, or the AAVSO Unique Identifier 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. It should have a decimal point (ex: 10 should be 10.0). Limit: 8 characters.
  • COMMENTCODE: A list of one-character comment codes. (If no comments, use "na".) Possible codes are:
    • B: Sky is bright, moon, twilight, light pollution, aurorae.
    • U: Clouds, dust, smoke, haze, etc.
    • W: Poor seeing.
    • L: Low in the sky, near horizon, in trees, obstructed view.
    • D: Unusual Activity (fading, flare, bizarre behavior, etc.)
    • Y: Outburst.
    • K: Non-AAVSO chart.
    • S: Comparison sequence problem.
    • Z: Magnitude of star uncertain.
    • I: Identification of star uncertain.
    • V: Faint star, near observing limit, only glimpsed.

Multiple comment codes should be separated by spaces or not separated at all. (Ex: "A Z Y" or "AZY"). Limit: 20 characters.

  • COMP1: The label of the first comparison star used. Could be the magnitude label on the chart, and auid, or something else. Limit: 20 characters.
  • COMP2: The label of the second comparison star used. Could be the magnitude label on the chart, an auid, etc. (if none, use "na".) Limit: 20 characters.
  • CHART: This should be the "Chart ID" located in a box at the upper righthand corner of the chart (usually, "NNNNLL" where N is a series of numbers and L is a series of letters). If the chart has no Chart ID, use the latest date you see anywhere on the chart, entered as YYMMDD. If you do not see a date, use the first day of the copyright year (Ex: "Copyright 2007" would be 070101). If you used your own comparison stars (e.g. in the case of time-sensitive alerts when the Sequence Team had no time to create a sequence), do not give a chart ID, even if you plotted the chart using VSP. Use the comment code K (non-AAVSO chart) and give a proper chart name like "APASS DR10". Then add information on the comp stars in the notes. Limit: 20 characters.
  • NOTES: Comments or notes about your observation. This field has a maximum length of several thousand characters (but please be succinct!). If you used your own comparison star sequence, identify your comp stars. E.g.: "Comp stars 123 = GSC 01234-56789 and 127 = GSC 01234-67890."
     

Examples

1. Simple Example

#TYPE=VISUAL
#OBSCODE=TST01
#SOFTWARE=WORD
#DELIM=,
#DATE=JD
SS CYG,2450702.1234,<11.1,na,110,113,070613,This is a test

2. Simple Example with a twist... (not really, we just added a comment line)

#TYPE=VISUAL
#OBSCODE=TST01
#SOFTWARE=WORD
#DELIM=,
#DATE=JD
#NAME,DATE,MAG,COMMENTCODE,COMP1,COMP2,CHART,NOTES
SS CYG,2450702.1234,<11.1,na,110,113,070613,This is a test
 

Note the existence of the #NAME,DATE,MAG,COMMENTCODE,COMP1... line in the above format. Since it is prepended with a pound sign and doesn't start with any of our special parameter keywords, it will be ignored by our software as a comment. Feel free to do this if it makes writing and reading the format easier for you.

3. Kicking it up a notch...

#TYPE=VISUAL
#OBSCODE=TST01
#SOFTWARE=WORD
#DELIM=,
#DATE=JD
#OBSTYPE=Visual
SS CYG,2450702.1234,<11.1,na,111,na,070613,na
SS CYG,2450703.2341,<11.1,na,111,na,070613,na
SS CYG,2450704.1567,<11.1,IZ,111,na,070613,NO CHART--FROM MEMORY
SS CYG,2450706.1890,<11.1,na,111,na,070613,na
SS CYG,2450707.1001,9.3,Y,93,95,070613,OUTBURST!
SS CYG,2450709.1501,9.1,na,90,93,070613,na
SS CYG,2450710.1781,9.1,na,90,93,070613,na
#OBSCODE=TST02
#DATE=EXCEL
SS CYG,1/1/2007 4:15 a.m,9.3,na,90,95,070613,FIRST TST02 OBS!
SS CYG,1/2/2007 4:15 a.m,9.3,na,90,95,070613,NEXT TST02 OBS!
#OBSCODE=TST01
#DATE=JD
SS CYG,2450709.1900,9.3,na,90,95,070613,TST01 AGAIN
SS CYG,2450719.1,<11.1,na,111,na,070613,na

In this example, the observer changes the observer code and the date format in the middle of the report and then changes it back.


If you have specific questions about the format, please email aavso@aavso.org.