Skip to main content

VStar User Manual Project

22 posts / 0 new
Last post
David Benn
David Benn's picture
VStar User Manual Project

Hi all

As you all know, the current VStar help (Help -> Help Contents...) is pretty minimal and I've been meaning to do something about this for quite awhile. I could say that my focus has been more on functionality and bug fixes than anything else, but that's really just an excuse.  I've written a fair amount about VStar here and in other places, such as my blog, newsletters, and an eJAAVSO paper (see the links in the Help! section at the end of or, given talks at Citizen Sky, NACAA and a couple of astronomical societies.

Let's face it, what's needed, more than anything else, is a da da daaaa... user manual!

So I'd like to propose a community-based user manual project for VStar to which anyone can contribute upon request. It would be:

  • Google Docs based.
    • A VStar Docs folder has been created and I will start to populate it soon.
    • I will share the document to anyone wishing to contribute a section or chapter or be a reviewer or proof reader. Options are to share the document URL to whoever asks. Another is to require Google login before the document can be updated. I recently wrote a paper with several other authors who had to be logged in. I think that worked well because we could see who was working on the doc, who was adding review comments, could chat to other authors etc.
  • Split into separate documents per major section.

When "complete", it would be exported as Word/PDF for distribution. Whether it stays in Google Docs for future revisions or moves to SourceForge+Subversion is an open question. That's where the plugin development document currently is (

My role would be to:

  • Coordinate the overall structure of the document.
  • Contribute some of the content.
  • Act as "lead author", looking at coverage and consistency.

One of the benefits of others writing sections of such a document other than spreading the work around, is that it will generate questions about how things work that I take for granted. It may also find bugs.

Please let me know what you think.

No matter how many people show interest, I will almost certainly start taking this approach to creating a user manual anyway. I would welcome input and contributions from the VStar user community.

The next post will propose an initial table of contents.


David Benn
David Benn's picture
Proposed Table of Content

Okay, so now that everyone's all fired up about writing a section of the VStar user manual :P, here's my suggestion for an initial table of contents:

  1. Introduction
    1. Brief overview
    2. Introduction to main window, tabbed panes, menus and toolbar, raw vs phase plot mode.
    3. Further reading: links, books
  2. Observation Sources
    1. AID
    2. Download and simple format files.
    3. Plug-ins: give one or two examples and point to plug-in library page.
  3. Info dialog
    1. Name, type, ...
    2. Bands
    3. Period
    4. ANOVA
    5. Confidence Interval
  4. Saving and printing
  5. Panning and zooming
  6. Plot Control Dialog
  7. Observation details and discrepant reporting
  8. Filters
    1. Creating
    2. Managing
  9. Working with the observation list
    1. Sorting
    2. Searching
    3. Selection filters
  10. Undoable edits
    1. Observation exclusion
  11. Creating and managing phase plots.
  12. Polynomial fit
    1. Band and degree selection.
    2. The model and residuals panes.
  13. Phase plots
    1. Creating
    2. Managing
  14. Period analysis
    1. DCDFT
    2. Creating and managing models
    3. Finding harmonics
    4. CLEANest
  15. Time-frequency analysis
    1. WWZ
  16. Scripting VStar
    1. API
    2. Examples
  17. Plug-ins
    1. Types: observation source, filter, period analysis, tool, ...
    2. AAVSO plug-in library.
    3. How to develop: point to existing document or incorporate it.
  18. Preferences
  19. Authentication
    1. When is it required: some plug-ins, discrepant reporting.
  20. License information
  21. Index

Initially, I intend to create a document in a Google Docs folder for each top-level item.

Feedback please!


Matthew Templeton


This is great, and I wholeheartedly encourage it -- VStar is a phenomenal resource.  I'm happy to help add material on time-series analysis where needed.

Thank you for taking the lead on this, and VStar itself!


David Benn
David Benn's picture
Thanks Matt! I know you're

Thanks Matt!

I know you're a very busy person, but I will appreciate whatever contribution you can make, whether review or content.


mqe's picture
VStar Manual

 Hi David and Everyone:


I'm working on the VPHOT manual.  I have several hundred pages so has not been edited by Geir yet for content and HQ for format, etc...but if you would like to see what I have from a format point of view, I would be happy to share what I have so far in Google Docs with anyone.


You might want to look at whether what I chose to do with highlighting things with images will work for you.  If so, I can give you some pointers on how to get the effect.


One of the disadvantages I found using Google docs was that, if you choose to write what you are doing first in Word or cannot simply copy and paste what you have done into Google docs if you have images mixed in with the text.  You can only do 2 MB at a time, and there is a trick to getting the images to transfer (basically you have to use "control C" not "paste"--assuming you are working from a PC like me...not sure what happens on a MAC).


There are of course advantages to editing directly into Google docs...but I did lose a lot of stuff twice, so if you go that sure to back up what you do in Google Docs.  Then you can reload if you lose stuff 2 MB at a time.  I eventually found it easier to just copy and paste into Google docs.




Ken Mogul (MQE)

David Benn
David Benn's picture
Hi Ken! Long time no

Hi Ken!

Long time no key. ;)

I would appreciate seeing what you've done with the VPHOT manual and with the image effects.

I was planning to do it all in Google Docs from the start. That's a useful caution re: loss of data. The only time I used Google Docs, I used the drag and drop or file chooser approach to image insertion.

I thought that a separate document per chapter / major section might help guard against loss and prevent the document from becoming unmanageably large.



David Benn
David Benn's picture
I heard from a couple of

I heard from a couple of people that the recent Citizen Sky DSLR photometry tutorial writing workshop made use of Google Docs (GD) also.

It would be interesting to hear more about that group's impressions of GD.


Matthew Templeton
DSLR workshop & Google Docs

Hi David,

I worked on the equipment chapter at the workshop and I think we mostly found it pretty useful.  The only real issue was figuring out permissions issues and ownership at the very start, but once we were all logged in and working it went ok.  As far as word processing, it's about as feature-rich as it needs to be, and can produce a decent PDF on demand.  I liked it.


David Benn
David Benn's picture
Update on user manual

I've written a first cut of the following sections in Google Docs:

  • Introduction
  • Observation sources
  • Licensing
  • References and Further Reading

With VStar 2.15.1 released, I plan to keep chipping away at this.

However, if you would like to pick up a section to write, please let me know! I will make the document available to you via Google Docs sharing.

If you use VStar, you could write a section based upon your hands-on experience. I could post a sample section here if that would help.


David Benn
David Benn's picture
Sample user manual sections

Hi all

I've attached some sample first-cut user manual sections.

Feel like writing a section? This is a parallelisable task.

Want to add review comments to a section like the one attached?

Just let me know and I'll provide you with access to the Google Docs area.

Comments welcome.


LKR's picture

Awesome! I will definitely give you feedback on these 4 pieces.



David Benn
David Benn's picture
Thanks Kristine. If you want

Thanks Kristine. If you want me to provide access to the Google docs, let me know. Direct feedback is also welcome.


LKR's picture
looking good

Thanks for the access. I'm glad I was able to provide useful feedback so far and will get to work on the glossary and annotated references ASAP.



David Benn
David Benn's picture
First VStar User Manual Release

Hi all

It gives me great pleasure to announce that the first release of the VStar User Manual is now available.

You can download it via the Big Yellow Button on the VStar Overview page, where Sara has made it available.

See also Sara Beck's post on the AAVSO page:

This has been a long time coming. I started this thread in April and have been writing the manual on and off since then, but I've had this manual on my mind for a long time. Just as VStar evolves, so will the manual.

For much of that time, Kristine Larsen has been reading and re-reading what I've written, providing feedback and corrections and making suggestions for additions, and challenging the content and its ease of understanding. In addition, she wrote most of the Glossary and annotated my bare bones references and further reading sections. Thank you Kristine! Having someone to bounce ideas off has been invaluable.

Thanks to Matthew Templeton for providing feedback on an early draft of the Period Analysis section.

Thanks to Sara Beck for providing feedback on the latest couple of drafts, for making the document available on the AAVSO web and for her omnipresent support.



LKR's picture
Major Squee!!!

It's here! it's here!  (wild Muppet flail)

So glad to have this see first light!!!!! Thanks for all your hard work, David. All AAVSO members (and others who use VStar) owe you a huge THANK YOU!

Kris Larsen

BSJ's picture
VStar User Manual

Congratulations David!

This was a major undertaking and something that has been on our minds for a very long time.

I can't wait to use the Manual to help me make some of those neat plots you show in the Time-Frequency Analysis section. T UMi's period really is changing fast! Now when I see a light curve that looks like something funny is going on, I can use VStar to help me figure out what is happening.

Thank you!

TDW's picture
VStar current status?

I have been trying to use VStar to make sense of my observations of del Cep and eta Aql but I am encountering a number of issues related to inconsistencies between the VStar User Manual and the program, and the behavior of the program itself. Is VStar still under active development? To whom should I address my questions and issues?

David Trowbridge

Tinyblue Observatory

daveh's picture
VStar current status


VStar is is undergoing an upgrade as we speak. David Benn is the main contact for this but there are a couple of us that are working with him to upgrade the software as well as add new capabilities. In particular, there are additional plugins being added such as Gaia observation data. Also, work is being done to improve the file download time for stars with a large number of observations. The manual is also being updated and corrected as part of the new effort. We have also been testing all of the functions of VStar as shown in the user's manual. In general, things look pretty good but there are some corrections that need to be done. There are some inconsistancies between the software and the manual, but these are fairly minor and will be corrected.

David Benn is in a conference all week so he might not be able to answer you right away. If you indicate specifically what your problem is on this forum, perhaps one of us can help until he gets back. Hope this helps.



TDW's picture
New Star from File - "No observations for the specified period"?

I am running VStar 2.20.0 and using VStarUserManual.pdf. I would like to use VStar to plot a few of my own observations of del Cep from a local file. I select File | New Star from File.

When I select the file Del-Cep_1s_1010.txt, I get an Observation Read Error, "No observations for the specified period." I have no idea how to specify a period. I have a file with multiple observations, but this gives the same error.

Using, I can upload this observation file without any problem. So why can't VStar open the same file? What am I missing?


File upload: 
BSJ's picture
New star from file

Hi David,

I think that the issue is that you are trying to open an AAVSO Extended File report using the "New Star from File" method which is only for opening files in "AAVSO Download Format" or "Simple Format" as described on page 9 of the VStar User Manual. Unfortunately, AAVSO upload and download format are not the same!

What you need is to install the plugin called "New Star from AAVSO Upload Format file...". You can get this plugin by going to VStar's menu bar and clicking Tool > Plug-in Manager... then selecting "AAVSO upload file (Visual and Extended) Format reader" and clicking "Install".

It is important to know that once you install this (or any plugin) that you must first close VStar then reopen it again. If you do this, the next time you click "File" in the menu bar, you will see the plugin listed there.

If you have further questions, please don't hesitate to ask.


TDW's picture
Very clear explanation, Sara.

Very clear explanation, Sara. It works as you describe.

Thank you so much!


David Benn
David Benn's picture

Thanks Sara, Dave for helping David in my absence last week.


Log in to post comments
AAVSO 49 Bay State Rd. Cambridge, MA 02138 617-354-0484