VStar Help

Introduction

VStar is a multi-platform, easy-to-use variable star data visualization and analysis tool.

Its current capabilities are:

Plots have magnitude on the Y axis and Julian Date or phase on the X axis.

In its default configuration, VStar allows data to be loaded from one of two file formats or from the AAVSO International Database (AID).

Loading Observation Data from a File

Selecting New Star from File... from the File menu or clicking the equivalent toolbar icon opens a file dialog from which a file of one of two formats can be loaded:

  1. AAVSO download format (CSV and TSV formats only currently, not VOTable)
  2. Lines of the form: Julian Date,Magnitude,[Uncertainty],[Observer Code],[Validation Flag] or simply: Julian Date,Magnitude

where [] indicates that a field is optional. In each case, a file may contain lines of tab or comma-delimited form. The fields of the second simple format have the same meaning as in the AAVSO Download Format. VStar does not support the AAVSO Space Delimited download format.

Once loaded, you will notice that when the Observation List tab is selected, any observation lines VStar deems to have failed validation will appear in a separate split pane. Such invalid observations will not appear on any plot.

VStar detects the file's format from its content.

Loading Observation Data from AID

Selecting New Star from AAVSO Database... from the File menu or clicking the equivalent toolbar icon opens a dialog that allows one of the stars from the 10 star tutorial to be selected from a drop-down menu. Alternatively, a star name from a user-defined star group may selected. The 10 star tutorial star group is the only default (see also Setting Preferences section). Instead, a star's AAVSO unique ID or alias may be entered.

After selecting the star for which you want to retrieve observation data and the Julian Date range (or all data; take care: this may result in a lot of data being retrieved), the data for the star's observations within that range are loaded, and charts and tables for the data, including means, are created.

Observation Details

By selecting an observation datapoint in a plot with the mouse and clicking the Observation Details... toolbar button or View menu item, a dialog is opened with details regarding the observation. This dialog also allows an observation to be marked as discrepant and optionally to send a report to AAVSO. See the Zapper link below for more information about discrepant observations.

Plot Zoom

Apart from zooming by selecting a bounding box in a plot, or via a chart's pop-up menu items, simple zoom in/out View menu items and toolbar buttons are provided. In order to use the latter, you must first select a point on the plot with the mouse. This point becomes the focus of subsequent zoom operations.

Plot Panning

Selecting Pan Left, Pan Right, Pan Up, or Pan Down from the View menu (or more likely, using the corresponding toolbar buttons) will cause the domain (JD, phase) or range (magnitude) axis to pan appropriately. This is particularly useful when zooming has been applied to a plot and you want to view surrounding data points.

When panning left or right to the limit of the available data, selecting Pan Left or Pan Right, accordingly, currently has no further effect.

Phase Plots

Selecting Phase Plot... from the Analysis menu or clicking the corresponding button from the toolbar opens a dialog box into which you can enter the period and epoch for a dataset. Period and epoch values from the AAVSO International Variable Star Index (VSX) are used as the default, if the dataset was loaded from the AID. If unknown or the dataset was loaded from a file, the epoch defaults to the mid-point of the dataset's time range. VStar will fold the data over the specified period and display a Phase Plot of magnitude versus phase.

After the first phase plot has been created for a dataset, selecting Phase Plot... will switch from raw data (light curve) mode to phase plot mode, affecting both plots and tables. Selecting Raw Data from the Analysis menu will switch back to raw data (light curve) mode. To create a new phase plot, see the Plot Control section.

Plot Control

Selecting the Plot Control... toolbar button or View menu item opens a dialog that permits features of the light curve or phase plots to be changed:

In phase plot mode, a New Phase Plot button is included in the dialog to change the period or epoch and generate a new phase plot.

Observation Filtering

Selecting the View menu's Filter... item or the corresponding toolbar button opens an observation filter dialog that permits one or more "matchers" to be specified, each of which must match for a given observation to be included in the set of filtered observations.

Only raw observations are filtered, not mean values. Observation list rows (for raw light curve and phase plot lists) are reduced in number according to the filter, and raw light curve plots (not phase plots yet) have a "Filtered" series added. This new series can be treated in the same way as any other series, including being selected/deselected, and used as the source for a mean curve.

If the "Use selected observation?" checkbox is selected, when a matcher is chosen, its test value field will be taken from the currently selected observation, if one has been selected with the cross-hairs.

Selecting No Filter... from the View menu removes the effect of filtering.

See also the Create your own plug-in! section.

Period Search

Selecting an item from the Analysis->Period Search sub-menu performs a period analysis on the loaded dataset. The series on which to perform the analysis must be selected for each.

The period analysis dialog that opens after a delay contains plots of amplitude against frequency and period, a table of all results, and a table of top hits ranked by amplitude. The latter is a good starting point for testing candidate periods. Clicking an entry in this table highlights the corresponding table entry or data-point in the other views. You can test different candidate periods by creating phase plots with those periods.

Currently implemented: Date Compensated Discrete Fourier Transform (DCDFT) and Weighted Wavelet Z-Transform (WWZ). Other possibilities in future are: AoV (analysis of variance), Fast Chi Square.

See also the Create your own plug-in! section.

Polynomial Fit

By selecting Analysis->Polynomial Fit, a polynomial of a particular degree will be created in an attempt to fit (i.e. model) the currently loaded observation data. The series on which to perform the analysis must be selected.

A polynomial fit series will be added to the light curve plot and made visible. In addition, a Residuals series (dataset with polynomial removed) is added but not initially made visible. See also the Change Series button in the light curve pane.

A more complete integration of polynomial fit, including the option of saving residuals and fit coefficients will be added in future.

Saving Plots and Tables

Any chart can be saved as a PNG file via the File menu's Save... item or the equivalent toolbar icon.

Tables in the Observation List tab can be saved as TSV files, but Mean List table saving is yet to be implemented. For the latter, what may also be needed is to save not just the data, but also the parameters that lead to it.

Printing Plots and Tables

Any chart or data table can be printed via the File menu's Print... item or the equivalent toolbar icon.

Setting Preferences

Preferences can be set via the File menu's Preferences... item or the equivalent toolbar icon.

Per-band colors can be changed and star groups can be created, deleted, and modified.

The precision of numeric output can also be specified via the preferences dialog.

Other preferences will be added over time.

Create your own plug-in!

VStar's functionality can be extended by developing Java plug-ins for:

among other things. For more information see the Citizen Sky or AAVSO VStar web pages (see Links section below).

Authentication

Note that as of version 2.10, authentication via login dialog only happens when reporting an observation as discrepant (to validate your AAVSO or Citizen Sky username and password) which is only possible if the currently loaded dataset is from the AID.

For a given run of VStar, you need to enter your Citizen Sky credentials only once.

A Citizen Sky account may be obtained for free from http://www.citizensky.org.

License and Source Code

VStar is licensed under the GNU Affero General Public License, version 3. The source code may be obtained from the VStar SourceForge repository at: http://vstar.svn.sourceforge.net

VStar uses the following external libraries. See the links for project info, source code and licensing.

Links