h1. Getting the most out of your plots

h2. Outline

* Introduction
** Terminology
* Creating plots in org.lcsim


Here is a possible outline for this section:

* usage of the static AIDA defaultInstance 
* explanations of basic types: clouds 1D/2D, histograms 1D/2D, tuples, etc.
** defining each type (e.g. bin sizes for histograms, etc.)
** filling each type
* creating plots from a sample Driver (use Analysis101 or some other template)
* plotting on new window
* adding plot to existing window
* changing axis label: text value, font, size, etc.
* changing axis range min/max
* changing to log scale
* overlaying plots
* changing filled/unfilled and colors for value bars, error bars
* modifying fields that show in statistics box
* saving and reloading plots using .aida files
* discussion of various graphics formats (which is best for what purpose)
* importing into a Powerpoint presentation
* basic fitting (would keep this pretty simple)

It would probably be best done with more than one page.

--Jeremy M.

h2. Introduction{anchor
For plotting and fitting, org.lcsim provides an implementation of [AIDA|http://aida.freehep.org].
This tutorial will assume that you are working in JAS3 and have either loaded an existing AIDA file or created objects in AIDA with the [org.lcsim] plugin.

If you have executed some of the examples in JAS3, you have already used AIDA in lines like these:
{code}AIDA aida = AIDA.defaultInstance();
...
aida.cloud1D("nTracks").fill(tracks.size());
{code}

These lines create and fill an unbinned one-dimensional histogram named {color:green}nTracks{color} with the return value of {{tracks.size()}}

h3. Teminology
AIDA provides two different kinds of histograms: binned and unbinned.
Binned histograms are called {color:darkgreen}{{IHistogram1D, IHistogram2D, IHistogram3D}}{color} for one, two and three-dimensional histograms.
Similarly, unbinned histograms are called {color:darkgreen}{{ICloud1D, ICloud2D, ICloud3D}}{color}

h2. Getting started
h3. Viewing and Loading Plots
Lets start with viewing AIDA objects. You can either create them with the AIDA examples, the org.lcsim examples or you can load an existing AIDA file with {color:blue}{{File->Open File...}}{color} in the menu.
All AIDA objects are arranged in _trees_. You can have many trees open at the same time; they are represented as Folders, !ClosedFolder.gif!. Trees can contain, e.g. Clouds !Cloud.gif! and/or Histograms !Histogram.gif!, with the name of the object appearing next to it. If a folder is closed, double-clicking will open it and display its contents. Similarly, double-clicking on an open folder will close it, so that the contents are hidden. 
{info}Trees that are created by the org.lsim examples will have non-descriptive names like {color:green}{{aida5312aida}}{color}.{info}

A double-click on a Cloud or a Histogram will cause JAS3 to plot the contents.
{info}Clouds are automatically displayed with 50 bins over the range of the data.{info}

{note}If the active _page_ shows source code or the examples, double clicking on an item in the tree will create a new plot page and display the item.
If, however, the active page *is* already a plot page, double-clicking on an item will cause the displayed plot to be *overwritten*, and all your modifications (like changing the binning, the color or the text) to be lost !{note}
{tip}If you want to display more than one plot on a page, you have to use the context menu.
# _Right_ click on the item you want to plot to open its context menu
# Select {color:blue}{{Show in New Plot}}{color}
{tip}

In order to display an item *together* with an already displayed item, select {{Overlay on Current Plot}} from the context menu

h3. Saving in various graphics formats (e.g. PNG, EMF, JPG, etc.)
JAS3 supports various graphics formats, for both bitmap and vector graphics.
{info}Bitmap graphics are *not scalable*. JAS3 saves all Plots in their current size. Please make sure to draw the window to the desired width before saving in a bitmap format.{info}

The following list gives a brief description of the most often used formats
{panel:title=Graphics Formats}
|PNG|Portable Network Graphics|We recommend this format as the default bitmap format. PNG files are compressed and can be used for inclusion in presentations.|
|EPS|Encapsulated PostScript|For inclusion in printed documents, the EPS format is preferred. This is an uncompressed format, so EPS files are usually much larger than their compressed counterparts. (Up to a factor of 10 or more)|
|PS|PostScript|Select this format if you want a document-quality printout of your plot. Uncompressed. This option should be used with care, because the PS format contains information about the page layout. The JAS3 PS format is letter-height and A4-width.|
|SVG|Scalable Vector Graphics|Like the EPS format, SVG is a vector graphics format. Unlike EPS, however, it is compressed. You can use this format for high-quality graphics output.|
{panel} 

Saving Plots is a trivial task in JAS3:
* You want to save the whole page:
** Select {color:blue}{{File->Save As...}}{color}
* You want to save only one plot in the current page
** Right click on the plot and select {color:blue}{{Save Plot As...}}{color}

{section}
{column:width=40%}{note:title=The Blue Frame Bug}Sometimes one of the plots shows an undesired (blue) frame. *This blue frame will appear in the image*. You need to make sure that none of the plots has this frame before saving the image. You can do that by clicking on an area outside of the frame.
Please note that if you try to save the plot by selecting the entry {color:blue}{{Save Plot As...}}{color} from the context menu, it will *always* have the blue frame !{note}
{warning}Don't try to remove the frame by hitting the {{delete}} key !
Hitting {{delete}} on a selected plot can result in {color:red}*data loss*{color} !{warning}{column}{column:width=40%}!jasBlueFrame.png!{column}
{section}

h3. Changing Layout/Style/Properties with the Mouse
Thanks to the close integration of JAS3 and AIDA, a plethora of manipulations is availabe via menus and dialogs. This tutorial can merely give an overview over the most commonly used ones.



h2. Advanced Topics
For this section, you will want to take a look at
PAIDA and AIDA API
h3. Changing Layout/Style/Properties with a Script
While it is convenient to be able to manipulate your data with the mouse, in many cases you will want to apply the same modifications to a set of similar data, or perform more complicated modifications that are quite possible to do with AIDA, but not (yet) implemented in JAS3. This is where a script comes in handy

h3. Advanced Manipulations of Histograms
h2. Adding and subtracting histograms

h3. Fitting
h4. Using predefined functions
h4. Writing your own function

h3. Tuples
h2. Flat Tuples
h2. Nested Tuples