VStar User Manual Project

Affiliation
Astronomical Society of South Australia (ASSAU)
Tue, 04/02/2013 - 13:49

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  http://www.aavso.org/vstar-overview or https://sourceforge.net/p/vstar/wiki/Home), 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 (https://sourceforge.net/p/vstar/code/960/tree/trunk/plugin/doc).

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

Affiliation
Astronomical Society of South Australia (ASSAU)
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!

David

Great!

David,

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!

Matt

Affiliation
American Association of Variable Star Observers (AAVSO)
VStar Manual

 Hi David and Everyone:

 

I'm working on the VPHOT manual.  I have several hundred pages so far..it 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 PPDF..you 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 route...be 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.

 

Cheers,

 

Ken Mogul (MQE)

Affiliation
Astronomical Society of South Australia (ASSAU)
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.

Thanks.

David

Affiliation
Astronomical Society of South Australia (ASSAU)
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.

David

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.

Matt

Affiliation
Astronomical Society of South Australia (ASSAU)
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

Affiliation
Astronomical Society of South Australia (ASSAU)
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.

David

Affiliation
Astronomical Society of South Australia (ASSAU)
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.

David

Affiliation
Astronomical Society of South Australia (ASSAU)
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: http://www.aavso.org/vstar-user-manual

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.

Enjoy!

David 

Affiliation
American Association of Variable Star Observers (AAVSO)
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

Affiliation
American Association of Variable Star Observers (AAVSO)
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!
Sara

Affiliation
American Association of Variable Star Observers (AAVSO)
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

Affiliation
American Association of Variable Star Observers (AAVSO)
VStar current status

David,

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.

daveh

HDHA

Affiliation
American Association of Variable Star Observers (AAVSO)
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 www.aavso.org/webobs/file, I can upload this observation file without any problem. So why can't VStar open the same file? What am I missing?

David

Affiliation
American Association of Variable Star Observers (AAVSO)
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.

-Sara

Affiliation
American Association of Variable Star Observers (AAVSO)
Flavors of JD in plugins.

Hi all,

I think it is worth to make a clear statement in descriptions of plugins somewhere about the flavor of JD they use. Probably for an experienced user it is obvious that APASS and other surveys use dates (mostly) in HJD, however, using VStar, it is very unclear (because of VStar labels date column "Julian Date" for APASS data. At the same time, when it loads data from AID it shows HJD column along with "Julian date" if HJD exists for a record).

An ideal situation would be proper labeling a date column in a table of observations presented by VStar (and proper axis labeling). I'm aware that it could require many unsafe small changes, so if it is too hard would it be possible to include additional text somewhere at the top of a table with a message about JD flavor?

Best regards,

Max

Affiliation
Astronomical Society of South Australia (ASSAU)
Flavors of JD in plugins

Hi Max

It's true that the observation table has a column that is shown potentially confusingly as "Julian Day", the observation details dialog and the plot pane show HJD when in use in an observation source.

The documentation for each plugin will normally mention whether HJD is being used as well I think, but I'd need to go back and check each.

There are one or two plugins that use BJD also for example.

The AID does have a separate HJD column yes, but it's not often used. I understand how this could be confusing.

So, where does this leave us. Should I create a ticket for a change to the observation list pane "time" column to show whether it's HJD, JD etc? 

David

Affiliation
Astronomical Society of South Australia (ASSAU)
Time column

Okay, cool. Thanks Maksym. Mulling this over with Sara and others too. Think it makes sense though.

David