\documentclass[twoside,10pt]{article} % \usepackage[latin1]{inputenc} % \usepackage[T1]{fontenc} \usepackage[francais]{babel} \usepackage{graphicx} \usepackage{amsmath} \usepackage{amssymb} \usepackage{latexsym} \usepackage{palatino} % Definition pour Docs Sophya \usepackage{defsophya} \usepackage{makeidx} \usepackage[ps2pdf,bookmarks,bookmarksnumbered,% urlcolor=blue,citecolor=blue,linkcolor=blue,% pagecolor=blue,%hyperindex,% colorlinks=true,hyperfigures=true,hyperindex=true ]{hyperref} \setlength{\textwidth}{17cm} \setlength{\textheight}{21.5cm} \setlength{\topmargin}{0.5cm} \setlength{\oddsidemargin}{0.cm} \setlength{\evensidemargin}{0.cm} \setlength{\unitlength}{1mm} % \newcommand{\piacommand}[1]{ % \framebox{\bf \Large #1 } \index{#1} % (Command) %} % \newcommand{\piahelpitem}[1]{ % \framebox{\bf \Large #1 } \index{#1} (Help item) %} \newcommand{\rond}{$\bullet \ $} \newcommand{\etoile}{$\star \ $} \newcommand{\cercle}{$\circ \ $} \newcommand{\carre}{$\Box \ $} %%%% Definition des commandes pour l'aide en ligne \newcommand{\piacommand}[1]{ $\blacksquare$ \hspace{3mm} {\bf \Large #1 } \index{#1} % (Command) } \newcommand{\piahelpitem}[1]{ $\square$ \hspace{3mm} {\bf \Large #1 } \index{#1} (Help item) } \newcommand{\menubar}[1]{\hspace{1mm} \framebox{\it MenuBar::#1} \hspace{1mm}} \newcommand{\myppageref}[1]{ (p. \pageref{#1} ) } \makeindex % Constitution d'index \begin{document} \begin{titlepage} % The title page - top of the page with the title of the paper \titrehp{piapp \\ An interactive data analysis tool} % Authors list \auteurs{ R. Ansari & ansari@lal.in2p3.fr \\ E. Aubourg & aubourg@hep.saclay.cea.fr \\ C. Magneville & cmv@hep.saclay.cea.fr \\ O. Perdereau & perderos@lal.in2p3.fr \\ } % \author{R. Ansari {\tt ansari@lal.in2p3.fr} \\ % E. Aubourg {\tt aubourg@hep.saclay.cea.fr} \\ % C. Magneville {\tt cmv@hep.saclay.cea.fr} % } \vspace{1cm} \begin{center} {\bf \Large piapp Version: 4.0 (V\_Sep2006) } \end{center} \titrebp{5} \end{titlepage} \newpage \tableofcontents \newpage \section{Introduction} \index{piapp} {\bf piapp} (or {\bf spiapp}) is an interactive data analysis and visualization program. It is based on the {\bf PI} GUI library and the {\bf SOPHYA} \footnote{see http://www.sophya.org} (or {\bf PEIDA++} \footnote{PEIDA++ has been used in EROS software. (http://eros.in2p3.fr). It is not maintained anymore.}) C++ data analysis class library. \par {\bf piapp} is a powerful command oriented tool for visualising and analysing data. Its main features are summarised below: \begin{itemize} \item[\rond] Image, multiple 2D and few 3D representations \item[\rond] Highly interactive graphics, with postscript as export format \item[\rond] Capability to handle large data sets. Data can be imported and exported in different formats: ASCII, PPF and FITS. \item[\rond] Interactive analysis: 2D/3D distributions, histograms, FFT \ldots \item[\rond] Flexible c-shell inspired command interpreter. \item[\rond] Possibility to perform more complex operations in C++, on objects managed by the application through the on-the-fly compilation and execution of c++ code fragments in piapp. \item[\rond] piapp is a multi-threaded program with separate threads for graphics and command execution, ensuring interactive response, even while heavy computation is being performed. In addition, thread safe commands can be executed in separate threads, for taking advantage of multi CPU (or CPU-cores) workstations. \item[\rond] The application can be easily extended through modules which can be loaded at run time. \end{itemize} %%% \vspace*{5mm} \par {\bf piapp} can simply be started on the command line in a terminal window once the SOPHYA/piapp environment has been initialised. The environment variables {\tt SOPHYABASE} should contain the directory where SOPHYA/piapp has been installed. the shared library path {\tt LD\_LIBRARY\_PATH} must contain {\tt \$SOPHYABASE /slb} and the current directory {\tt .} and the executable search path {\tt PATH} must contain {\tt \$SOPHYABASE /exe}. Refer to the SOPHYA overview manual for more information on SOPHYA directory structure. \\ It might also be necessary to define the environment variable {\bf PIXKBMOMASK}, used by the libPI.a to map correctly the {\tt } key with some X servers (in particular with X11 on MacOS X). \\ {\tt csh> setenv PIXKBMODMASK 2 } \par {\tt (s)piapp -h} provides a brief help of the command line arguments. Xtoolkit options can also be specified as command line arguments. {\bf spiapp} is the name of SOPHYA/piapp executable, in order to distinguish it from PEIDA/piapp. \begin{verbatim} csh> spiapp -h SophyaInitiator::SophyaInitiator() BaseTools Init PIOPersist::Initialize() Starting Sophya Persistence management service SOPHYA Version 2.0 Revision 0 (V_Jul2006) -- Jul 18 2006 12:35:58 gcc 3.3 20030304 (Apple Computer, Inc. build 1495) piapp: Interactive data analysis and visualisation program Usage: piapp [-nored] [-termread] [-term] [-hidezswin] [-small] [-nosig] [-nosigfpe] [-nosigsegv] [-tmpdir TmpDirectory] [-help2tex] [-exec file [args]] -nored : Don't redirect stdout/stderr to piapp console -termread : Read commands on terminal (stdin) -term : equivalent to -nored -termread -small -hidezswin : Hide Zoom/Stat/ColMap window -small : Create small size main piapp window -nosig : Don't catch SigFPE, SigSEGV -nosigfpe -nosigsegv: Don t catch SigFPE / SigSEGV -tmpdir TmpDirectory: defines TMDIR for temporary files -help2tex: Create a LaTeX help file (piahelp.tex) -exec file [args] : Execute command file (last option) \end{verbatim} Once {\bf piapp} is started, the main piapp window appears. It contains the menu bar, an upper part with the zoom and colormap widgets for image displays, memory and CPU usage and a terminal like widget (piapp console, see {\bf PIConsole} \myppageref{PIConsole}) in the lower part. The figure \ref{figmainwin} shows an image of the piapp main window. {\tt stdout/cout, stderr/cerr} are redirected to the piapp console and commands can be entered in this widget. It is also possible to keep the terminal where piapp was started for {\tt stdout/stderr} (flag {\tt -nored}). It is also possible to have a command reader on the terminal ({\tt stdin}), using the flag {\tt -term}. \\[1mm] % {\bf Warning:} The output redirection uses unix pipes. On Linux, with commands producing long outputs, the application may block because of incorrect management of pipes. If this happens, use piapp with {\tt -nored} flag. \par In section 2, we present a quick tour of {\bf piapp}. a brief overview of piapp graphics, supported data formats, interactive analysis possibilities, the command interpreter and c++ execution are presented in the following sections. Section \ref{piappcmdref} contains a brief description of all piapp commands and help items. Various interactive control windows are described in appendix. \vspace*{10mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=16cm]{piapp_mainwin.eps} \caption{piapp main window} \label{figmainwin} \end{center} \end{figure} \newpage \section{A Tour of piapp} \subsection{Interacting with piapp, getting help} Users interact with piapp through commands entered in the piapp-console (or the unix terminal), and through the different menus. Some of the possibilities of the piapp-console are described in {\bf PIConsole} help item, in the command reference section \myppageref{PIConsole}. The description of the commands in available online using the help command. An online help window can be displayed by \menubar{File / Help}. Commands and help items are grouped in categories which can be selected using the OptionMenu in the Help window. \begin{verbatim} Cmd> help func Displays a function y=f(x) (Fills a vector with function values) Usage: func f(x) xmin xmax [npt graphic_attributes] Related commands: funcff func2d func2dff Cmd> func sin(x)/x 0.1 10 100 'red line=solid,2' ---> Graphic display of the function \end{verbatim} The directory {\tt DemoPIApp} contains a number of example command script and sample data files. \subsection{the Object Manager (NamedObjMgr)} The {\bf piapp} application is built around an object manager (class {\tt NamedObjMgr}) and a graphic application (class {\tt PIStdImgApp}). Objects inheriting from the class {\tt AnyDataObj} can be managed through adapter classes (classes inheriting from {\tt NObjMgrAdapter}) by the object manager. \par User sees the objects (such as Sophya objects Histo, NTuple, Arrays, Images, SkyMaps, \ldots) kept in memory, organized in a single level tree structure. Four memory directories are automatically created and can not be removed: \\ \centerline{\bf /home \hspace{10mm} /old \hspace{10mm} /tmp \hspace{10mm} /autoc} The default working directory (in memory) is {\bf /home}. Other directories can be created by the user. \begin{center} {\bf Warning:} These are only the directory structure managed by the piapp application and do not correspond to the file system directories \end{center} The window {\bf ObjMgr} shown in figure \ref{figobjmgrw} can be used to navigate in the memory directories and execute simple operations on objects. \\ This window can be displayed using the menu command \menubar{Objects / ObjectManager}. The button \framebox{\small \bf SetCurObj} can be used to set the value of the interpreter's variable {\tt cobj} to the selected object name. Refer to the commands in group {\bf Object Management} for more information. \vspace*{5mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=10cm]{piapp_objmgr.eps} \caption{The interactive object management window} \label{figobjmgrw} \end{center} \end{figure} \subsection{command language} A basic command interpreter ({\bf PIACmd/Commander}) is included in {\bf piapp} and other command interpreters can be inserted in the application framework. This interpreter ({\bf Commander} \myppageref{Commander}) synthax is close to the c-shell (csh) shell script. It is possible to define and use variables ({\tt set} command, {\tt \$varname}), and execute loops ({\tt foreach,for}), as well as simple tests ({\tt if test then ... else ... endif}). Commands from a file (default extension .pic) can be executed using the {\tt exec} command. Long commands can be put on several lines, by ending a line by the backslash \\ caracter, to signal that the command continues on the next line. The command macro below shows a sample piapp session, where data from the file {\tt demo.ppf} are displayed. \begin{verbatim} # Trace mode -> On traceon # Deleting all objects in the current directory delobjs * # Opening the PPF file demo.ppf openppf demo.ppf # Various displays in a graphic window, divided into 2x2 zones zone 2 2 # 1D histogram display disp h1d blue # 2D histogram display disp h2d # Function display func sin(x)/x 0.1 10. 200 gold # Surface representation of a matrix surf mtx1 colbr32 # Contour representation of a matrix contour mtx1 'colrj32 normalline ncont=7' # 3D representation of points using a PAW like command n/plot nt31.z%y%x ! ! win # 3D points superimposed on the previous display nt3d nt32 x y z ex ey ez - - 'same fcirclemarker7 red' \end{verbatim} \subsection{NTuple vue / PAW like commands} It is possible to plot various expressions of objects, seen as a 2D table, with named columns. This possibility exist not only for NTuples, but also for most objects (from SOPHYA) handled by piapp. See command groups {\bf Expr.Plotting} and {\bf pawCmd} \subsection{C++ execution inside piapp} For more complex processings, where the full power of C++ and the class libraries are necessary, {\bf piapp} provide the possibility of executing C++ code, without the burden of having to write a complete program. The objects present in the current directory are automatically declared. The communication with the piapp application is done by the {\bf NamedObjMgr} class. Two macros {\tt KeepObj()} and {\tt DisplayObj()} simplify the task of keeping newly created objects. In the example below, we first create a noisy signal in a vector, and we keep it in the application (Notice the use of multiline command) : \begin{verbatim} Cmd> c++exec c++exec Vector in(1024); \ ...? in = RandomSequence(RandomSequence::Gaussian, 0., 1.); \ ...? for(int kk=0; kk disp in \end{verbatim} And, at a subsequent stage, make a low pass filter on the vector in: \begin{verbatim} Cmd> c++exec Vector out(1024); \ ...? int w = 2; \ ...? for(int k=w; k disp out 'red same' \end{verbatim} See command group {\bf CxxExecutorCmd} for more information, and the option window activated by the menu: {\bf Special/CxxExecOption}. \subsection{Extending the application} The {\bf piapp} application can easily be extended by the user. This is done through shared libraries which can be opened and used by the application. Two main methods can be used (see command group {\bf ExternalModules}) : \begin{itemize} \item Creation of user functions. A shared library containing at least one user function with the following prototype should be created: \begin{verbatim} extern "C" { void myfonction(vector& args); } \end{verbatim} The class {\bf NameObjMgr} should be used to communicate with the application. The {\tt link} \myppageref{link} and {\tt call} \myppageref{call} should be used to load and execute user functions. An example of user function can be found in DemoPIApp/user.cc exlink.pic. \item Creation of loadable modules: Loadable modules can be used to extend the application possibilities in a way totally transparent to the user. It is possible to define new commands, handling of new object types, additional graphic functionalities in a loadable module. The class {\bf CmdExecutor} is the base class for extending piapp. A shared library should be built, containing two functions,for the activation and deactivation of the module, with the following prototype (where {\tt mymodule} is the module's name. \begin{verbatim} extern "C" { void mymodule_init(); void mymodule_end(); } \end{verbatim} \end{itemize} %%%%%%%%%% Section 3: Graphiques \newpage \section{Interactive graphics} %%% \subsection{Display commands} Many objects managed by piapp have a default graphic representation. The {\bf disp} command \myppageref{disp} can be used to display the object, while other commands like {\bf surf} \myppageref{surf} , {\bf imag} or {\bf contour} \myppageref{contour} will try to force a given graphic representation. \\ Data from table like objects can be plotted using commands like {\bf nt2d} \myppageref{nt2d} or {\bf nt3d} \myppageref{nt3d}. Most objects in piapp can also be manipulated like table for plotting purposes, using commands like {\bf plot2d} \myppageref{plot2d} , {\bf plot3d} \myppageref{plot3d} or {\bf n/plot} \myppageref{nZplot}. These commands are described in section \ref{tableplot}. \\ Commands producing a graphic output have usually an optional argument called {\tt graphic\_attributes} or {\tt gr\_att}. This argument provide a flexible and easy way to change and customise the output graphic, as discussed in the paragraph below. The piapp graphics can be exported in postscript (.ps) or encapsulated postscript (.eps) format. The commands {\bf w2ps} \myppageref{w2ps} and {\bf w2eps} \myppageref{w2eps} as well the menu \menubar{PostScript} can be used to export graphics. \\[1mm] The examples below illustrates the usage of some piapp graphic commands. \begin{enumerate} \item Image display \begin{verbatim} # Open a PPF file containing topographic data for france # as a TMatrix 1332x1548 openppf francetopo.ppf # Display the matrix, whit a zoom factor, lut and color map disp francetopo 'zoom/3 lut=lin,-700,800 colbr128 win' w2eps francetopo.eps \end{verbatim} \begin{center} \includegraphics[width=13cm]{francetopo.eps} \end{center} \item Simple 2D graphics with vector displays \begin{verbatim} # Create and initialize two vectors - prevent display : nodisp Cmd> newvec vva 100 sin(x/10.+0.7)+cos(x/7.+1.4)*1.26 nodisp Cmd> newvec vvb 100 sin(x/10.)+cos(x/7.)*1.34 nodisp # Set axe drawing options Cmd> setaxesatt 'font=times,bold,16 minorticks tickslen=0.02,0.012' # Display the two vectors, with different graphic attributes Cmd> disp vva 'red line=solid,2 notitle' # Define a title for the graphic Cmd> settitle 'Example-1: 2 vectors' ' ' 'font=times,bolditalic,18' Cmd> disp vvb 'blue marker=box,7 same' # Save the graphic into an eps file Cmd> w2eps gr2vec.eps \end{verbatim} % \begin{figure}[ht!] \begin{center} \includegraphics[width=12cm]{gr2vec.eps} % \label{g22vec} \end{center} %%% \item Creating a comparison chart using {\bf bargraph} \begin{verbatim} # Representation du PNB (en $, 2003) pour quelques pays set pays ( Allemagne Espagne France Italie Pays-Bas Suisse UK USA ) set pnbh ( 22670 14430 22010 18960 23960 37930 25250 35060 ) setaxesatt 'font=times,bold,16' bargraph pnbh pays - 'blue horizontalbars nofill packfrac=0.65 font=helvetica,bold,14' setaxelabels 'PNB / Hab , $ 2003' ' ' 'font=times,bold,16' w2eps pnbargraph.eps \end{verbatim} \begin{center} \includegraphics[width=12cm]{pnbbargraph.eps} \end{center} %%% \item Displaying a matrix as a surface \begin{verbatim} openppf demo.ppf mtx1 setaxesatt 'font=time,bold,16' surf mtx1 'colbr128 line=solid,1 grey' w2eps surfcol.eps \end{verbatim} \begin{center} \includegraphics[width=13cm]{surfcol.eps} \end{center} \end{enumerate} %%%%%%%%%% \subsection{Graphic objects in piapp} The piapp graphics is handled by the {\bf PI} \footnote {http://www.sophya.org/PI} library, which provide a large variety of 2D representations, few 3D graphics and powerful image display. \\ Currently, all graphic representations, except for image displays, are handled through {\bf PIDrawers} which are managed by a viewer. A viewer can manage several {\bf PIDrawers} objects which correspond then to a multilayer graphic display. The viewers are also responsible for managing user interactions. \\ Image displays are handled through a specific viewer {\bf PIImage} which is also capable of managing PIDrawer objects for multi-layer 2D overlay vector graphics. \\[2mm] %% Main piapp/PI graphic viewers, windows and drawer objects: \begin{itemize} \item[\bul] The {\bf PIScDrawWdg} handles a set of of 2-D drawers, managing the 2D coordinate system and interactive zoom. The axes drawing is handled by a specialised drawer, number 0, which also manages various added graphic elements (text \ldots). The list of various mouse and keyboard actions is described in the reference section, under {\bf PIScDrawWdg} \myppageref{PIScDrawWdg} title. In particular, mouse-button-2 can be used to zoom on a particular part, {\tt $<$Alt$>$A} activates the coordinates and axes manipulation window ({\bf PIAxesTools}) and {\tt $<$Alt$>$G} activates the PIDrawer graphic attributes control window ({\bf PIDrawerTools}). %%% \item[\bul] The {\bf PIDraw3DWdg} handles a set of of 3-D drawers, managing interactive camera/object rotation (mouse-button-2) and zoom (mouse-button-2). {\tt $<$Alt$>$G} to display/activate the PIDrawer graphic attributes control window ({\bf PIDrawerTools}). See {\bf PIDraw3DWdg} \myppageref{PIDraw3DWdg} for a complete list of mouse and keyboard actions. Drawer 0 handles axes drawing and graphic elements. %%% \item[\bul] The display of 2-D arrays $A(i,j)$ as an image is managed by the {\bf PIImage} viewer/widget. The PI library interface {\bf P2DArrayAdapter} is used to represent a generic 2-D array. The array values are converted into an index, converted itself into a color by the use of a color-map or color-table {\bf PIColorMap}. $$ \mathrm{LUT:} A(i,j) \longrightarrow idx(i,j) \hspace{5mm} \mathrm{ColorMap:} idx(i,j) \longrightarrow col(i,j) $$ Currently index range is 0...255 with color-map having 32 or 128 distinct colors. PIImage viewers controls a zoom widget, as well as a global image view widget, and a color map view widget. A specific image control window can be activated using {\tt $<$Alt$>$O}. See {\bf PIImage} \myppageref{PIImage} for a complete list of mouse and keyboard actions. A base drawer (number 0) can handle axes drawing and added graphic elements. %%% \item[\bul] {\bf Windows} The viewers described above are displayed in differnt kind of windows. The graphic option {\tt next,win,same,stack} can be used to control the way the type of windows used. Graphic windows can be divided into several zones (Command {\bf zone} \myppageref{zone}). Refer to the command reference section on windows ({\bf Windows} \myppageref{Windows}) for information on the different type of windows used by piapp and their properties. %%% \item[\bul] {\bf PIDrawer} Graphical representation of most objects in piapp is handled through objects inheriting from the PIDrawer class. A base drawer (PIElDrawer, number 0) associated to all three above viewers manages the axes drawing as well as the added graphic elements (text, arrow, \ldots). A drawer management menu can be activated using {\tt $<$Alt$>$D}. This menu can be used to move and resize drawers, or to display a window for changing drawers graphic attributes. \end{itemize} \par In addition, a number of control windows can be used to examine and change view properties of differents viewers and drawers. \begin{itemize} \item[] {\bf PIDrawerTools} activated using {\tt $<$Alt$>$G} or \menubar{Tools/Show DrawerTools} on any viewer (see page \myppageref{secdrwtools}) \item[] {\bf PIAxesTools} activated using {\tt $<$Alt$>$A} or \menubar{Tools/Show AxeTools} on PIScDrawWdg (see page \myppageref{secaxestools}) \item[] {\bf PIImageTools} activated using {\tt $<$Alt$>$O} or \menubar{Tools/Show ImageTools} on PIImage (see page \myppageref{secimagetools}) \item[] {\bf PIHisto2DTools} activated using {\tt $<$Alt$>$O} or through the PIDrawerTools for an active PIHisto2D drawer. (see page \myppageref{sech2dtools}) \item[] {\bf PIContourTools} activated using {\tt $<$Alt$>$O} or through the PIDrawerTools for an active PIContourDrawer drawer. (see page \myppageref{secconttools}) \end{itemize} These control tools are briefly described in appendix. %%%%%%%%%% \subsection{Graphic attributes} Graphic attributes are specified as a set of space separated strings. Use quotes to group them into a single argument parsed by the command interpreter. The options are decoded by the different objects handling the graphic (viewer widget, drawer, axe drawer). \\ The complex decoding scheme is usually transparent for piapp users. However, there is an ambiguity when specifying some of the axes attributes, such as color or the font used for drawing the axes. The command {\bf setaxesatt} (\myppageref{setaxesatt}) should thus be used to specify generic graphic attributes (color, font, line type). \\ for axes. \begin{itemize} \item[\bul] The {\bf PIScDrawWdg} viewer options: \\ \begin{verbatim} >> To define the 2D axes limits (in user coordinates) xylimits=xmin,xmax,ymin,ymax >> To define the default drawing rectangle, in fraction of widget size defdrrect=x1,x2,y1,y2 (default: x1=y1=0.1 x2=y2=0.9) >> Axes flags : linx logx liny logy >> To change the background color (default=white) wbgcol=colname \end{verbatim} %%% \item[\bul] The {\bf PIDraw3DWdg} viewer options: \\ \begin{verbatim} >> To define the 3D box limits : xyzlimits=xmin,xmax,ymin,ymax,zmin,zmax limit3dbox=xmin,xmax,ymin,ymax,zmin,zmax >> Autoscaling flags (rescaling of X/Y or X/Y/Z axes) autoscale3dbox / noautoscale3dbox autoscalexy3dbox / noautoscalexy3dbox autoscalez3dbox / noautoscalez3dbox >> To change the background color (default=white) wbgcol=colname \end{verbatim} %%% \item[\bul] The {\bf PIImage} viewer options: \\ \begin{verbatim} >> Define display zoomfactor zoomxFact (zoomx2 zoomx3 ... zoomx9 ...) zoom/Fact (zoom/2 zoom/3 ... ) >> LUT (look-up table) definition (pixel value to index conversion) lut=type,min,max (type=lin/log/sqrt/square) >> Define color table and reversing color indexing flag ColTableName revcmap ==> Standard tables with 32 distinct colors: grey32 invgrey32 colrj32 colbr32 colrv32 ==> Standard tables with 128 distinct colors: grey128 invgrey128 colrj128 colbr128 ==> Shades of red/green/blue ... red32cm green32cm blue32cm yellow32cm orange32cm cyan32cm violet32cm ==> Some of MIDAS color tables : midas_pastel midas_heat midas_rainbow3 midas_bluered midas_bluewhite midas_stairs8 midas_stairs9 midas_staircase midas_color midas_manycol midas_idl14 midas_idl15 ==> Other tables multicol16 multicol64 >> Viewed center position (image/array coordinates) imagecenter=xc,yc >> Array axes to window axes mapping flags invx invy exchxy >> To change the background color (default=black) wbgcol=colname \end{verbatim} %%% \item[\bul] The {\bf PIGraphicAtt} Generic graphic attributes (color/font/line \ldots) decoded by all drawers: \\ \begin{verbatim} >>> color=ColorName - fgcolor=ColorName - bgcolor=ColorName ColorName: black white grey red blue green yellow magenta cyan turquoise navyblue orange siennared purple limegreen gold violet violetred blueviolet darkviolet skyblue royalblue forestgreen orangered brown >>> line=DashType,LineWidth DashType: solid, dash, dotted, dashdotted Width: 1,2,... >>> font=FontName,FontAtt,FontSize FontName: courier, helvetica, times, symbol FontAtt: roman, bold, italic, bolditalic FontSize: 6,8,10,12... (pts) - integer >>> marker=MarkerType,MarkerSize (MarkerSize: integer 3,5,7... MarkerType: dot, plus, cross, circle, fcircle, box, fbox triangle, ftriangle, star, fstar >>> arrow=ArrowType,ArrowSize (ArrowSize: integer 3,5,7... ArrowType: basic, triangle, ftriangle, arrowshaped, farrowshaped >>> ColorTables: defcmap grey32 invgrey32 colrj32 colbr32 grey128 invgrey128 colrj128 colbr128 red32cm green32cm blue32cm yellow32cm orange32cm cyan32cm violet32cm midas_pastel midas_heat midas_rainbow3 midas_bluered midas_bluewhite midas_redwhite multicol16 multicol64 > revcmap : This flag reverses ColorMap indexing ------- Old style graphic att ---------- >> Lines: defline normalline thinline thickline dashedline thindashedline thickdashedline dottedline thindottedline thickdottedline >> Font Att: deffontatt normalfont boldfont italicfont bolditalicfont smallfont smallboldfont smallitalicfont smallbolditalicfont bigfont bigboldfont bigitalicfont bigbolditalicfont hugefont hugeboldfont hugeitalicfont hugebolditalicfont >> Font Names: deffont courierfont helveticafont timesfont symbolfont >> Marker: dotmarker plusmarker crossmarker circlemarker fcirclemarker boxmarker fboxmarker trianglemarker ftrianglemarker starmarker fstarmarker with = 1 3 5 7 9 , Example fboxmarker5 , plusmarker9 ... \end{verbatim} %%%% \item[\bul] The {\bf PIElDrawer} decodes axe drawing attributes: \\ \begin{verbatim} >> Axe and grid configuration flags: axesnone stdaxes defaxes boxaxes boxaxesgrid fineaxes fineaxesgrid centeredaxes finecenteredaxes centeredaxesgrid finecenteredaxesgrid grid/nogrid >> Centered axes position: axescenter=xc,yc >> Axe ticks/labels (h=horizontal/x, v=vertical/y): labels/nolabels hlabels/nohlabels vlabels/novlabels ticks/noticks minorticks/nominorticks extticks/intticks/extintticks nbticks=X_NbTicks,Y_NbTicks tickslen=MajorTickLenFrac,MinorTickLenFraC >> Axe label font size: autofontsize=FontSizeFrac fixedfontsize >> Up/Down title: title tit notitle notit ... Color/Font/line attributes : \end{verbatim} \item[\bul] The {\bf PINTuple} handles most 2D plotting : \\ \begin{verbatim} sta,stat,stats: activate statistic display nsta,nstat,nostat,nostats: deactivate statistic display statposoff=OffsetX,OffsetY : Position offset for Stats drawing as a fraction of total size connectpoints: The points are connected by a line noconnectpoints (this is the default) colorscale/nocolorscale (Use color scale for weight) sizescale/sizescale=nbins/nosizescale (Use marker size for weight) (and usual color/line/marker/... attribute decoding) \end{verbatim} %%% \item[\bul] {\bf PIHisto} and {\bf PIHisto2D} handle1D and 2D histograms display. \\ The following options are recognised by PIHisto: \\ \begin{verbatim} sta,stat,stats: activate statistic display nsta,nstat,nostat,nostats: deactivate statistic display err / noerr,nerr : draw, do not draw error bars autoerr : draw error bars if Marker drawing requested OR Profile histo fill / nofill,nfill : fill, do not fill bars with selected color statposoff=OffsetX,OffsetY : Position offset for Stats drawing as a fraction of total size \end{verbatim} The following options are recognised by PIHisto2D: \\ \begin{verbatim} - sta,stat,stats: activate statistic display nsta,nstat,nostat,nostats: deactivate statistic display - h2disp=typ[,fracpts]: choose display type typ=var: variable size boxes typ=hbk: "a la hbook2" typ=img: image like (use "h2col" for color map) typ=pts: point clouds (fracpts=max possible fraction of used pixels per bin [0,1]) - h2scale=lin/log[,logscale]: choose linear or logarithmic scale - h2dyn=[hmin][,hmax]: choose histogramme range for display - use general key to define color table (ex: grey32,midas_heat,...) (see general graphicatt description) - use key "revcmap" to reverse color table - h2frac=[fmin][,fmax]: choose sub-range display [0,1] \end{verbatim} %%%% \item[\bul] The {\bf PINTuple3D} and {\bf PISurfaceDrawer} handles basic 3D plotting and can decode the common 3D box options: \\ \begin{verbatim} X/Y,Z axis rescaling option (-> cubic 3D box) rescale=autoscale/ norescale=noautoscale : X/Y and Z axis rescalexy=autoscalexy / norescalexy=noautoscalexy : X/Y axis rescalexy=autoscalexy / norescalexy=noautoscalexy : Z axis \end{verbatim} The PINTuple3D decodes in addition the following options: \begin{verbatim} connectpoints: The points are connected by a line noconnectpoints (this is the default) colorscale/nocolorscale (Use color scale for weight) sizescale/sizescale=nbins/nosizescale (Use marker size for weight) \end{verbatim} \item[\bul] {\bf PIBarGraph} options : \\ \begin{verbatim} ---- PIBarGraph options help info : fill/nofill: set bar fill option horizontalbars/verticalbars: set bar orientation packfrac=value : set bar packing fraction (0..1) barvaluelabel/nobarvaluelabel: Use/Don't use bar value as labels --- + Usual colr/line/font attribute decoding ... \end{verbatim} \end{itemize} %%%%%%%%%%%%%%% Section 4 : I/O \newpage \section{Data formats and I/O} \begin{itemize} \item[\bul] ASCII files (see {\tt ntfrascii} \myppageref{ntfrascii} and {\tt newnt} \myppageref{newnt} command) \item[\bul] FITS format files, through \menubar{File/Open-Fits}. (see also (see {\tt openfits} \myppageref{openfits}) command. \item[\bul] PPF (Portable Persistence file Format) files through menu \menubar{File/Open-PPF}. PPF files are the native persistence format in Sophya (or PEIDA++). \end{itemize} %%%%%%%%%%%%%%% Section 5 : analyse a la paw \newpage \section{Tables and interactive analysis} \label{tableplot} %%%%%%%%%%%%%%% Section 6 : command interpreter \newpage \section{Command interpreter} piapp uses the class {\bf PIACmd} which extends slightly the SOPHYA class {\bf Commander} as the command interpreter. {\bf Commander} is a c-shell inspired, string oriented command interpreter. Although it has many limitations compared to c-shell, or Tcl , it provides some interesting possibilities: \begin{itemize} \item Extended arithmetic operations (c-like and RPN) \item Simple and vector variables \item Script definition \item Command execution in separate threads \item Dynamic Load \end{itemize} We describe below the {\bf Commander} possibilities, as well as the few {\bf PIACmd} extensions. \subsection{Variables} The SOPHYA::Commander interpreter manages non typed set of variables. Environment variables are also accessible through the usual {\tt \$varenvname}, unless shadowed by a Commander variable. All Commander variables are vector of strings, and are extended as necessary. {\tt \$varname} is the string formed by all the vector elements. Except when performing arithmetic operations, variables are treated as strings. \par An application level set of variables is also managed by Commander, through redefinition of \\ {\tt Commander::GetVarApp() / GetVarApp() \ldots } methods. \\ The {\bf PIACmd} in piapp redefines the {\tt GetVarApp() } in order to provide an easy access to some of objects attributes or methods, managed by {\bf NamedObjMgr} (See below). \begin{itemize} \item[\rond] {\bf Definition and initialisation of variables } \begin{verbatim} # Notice that the set command has no = sign Cmd> set sv StringValue # Clearing/removing of a variable : unset or clearvar Cmd> unset sv # Definition of a multi element variable (vector type) # Notice that spaces before / after '(' and ')' are mandatory Cmd> set vecv ( mot1 mot2 mot3 mot4 mot5 ) # Arithmetic expression : C language syntax - spaces before/after '=' are mandatory Cmd> a = 2+3*sqrt(4) # The '=' operator can also be used to initialize a variable with a string Cmd> a = 'Bonjour Madame' # A vector element can be specified in the left hand side Cmd> vecv[2] = 'coucou' # Or using an interpreter variable as index : Cmd> i = 3 Cmd> vecv[i] = 'Ooohhh' \end{verbatim} On the right hand side, the value of a variable should be accessed using the \$ character. \\ A string can be parsed into words using {\tt var2words} \begin{verbatim} Cmd> var2words varname wordvarname [separateur] \end{verbatim} \item[\rond] {\bf Accessing variable contents } \\ The \$ character is used to access the content of a variable {\tt \$varname} . Substitution rules : The {\tt \$xxx} is replaced by the value of variable xxx. No substitution is performed for strings enclosed in simple quotes {\tt ' ... \$xxx '}, but substitution is done in strings enclosed in double quotes. Parenthesis or brackets can be used to specify the variable name, inside a string without white space: {\tt \${vname} } ou {\tt \$(vname)}. \begin{verbatim} Cmd> x = 'Hello' Cmd> echo $x # Size of a vector variable : $#vname Cmd> set vx ( 111 2222 3333 444444 ) Cmd> echo $#vx # Accessing vector elements Cmd> echo $vx[0] $vx[1] # or using an interpreter variable as index : Cmd> i = 2 Cmd> echo $vx[i] # Special syntax: $[vname] is replaced by the content # of a variable whose name is $vname Cmd> zzz = 'Commander' Cmd> xxx = 'zzz' Cmd> echo '---> $[xxx]= ' $[xxx] ---> $[xxx]= Commander \end{verbatim} \par \item[\rond] {\bf Special variables } \begin{itemize} \item {\tt \$retval} ou {\tt \$retstr} : the string specified in the last {\bf return} statement \item {\tt \$status} : Return code from the last executed command. Arguments of scripts (see below) or file executed through {\bf exec} command. \item {\tt \$\# } : number of arguments, except \$0 \item {\tt \$0} : Script or file name \item {\tt \$1 \$2 \$3} .... : Arguments (for scripts and .pic files (exec)) \end{itemize} \item[\rond] {\bf Objects/Application level variables} \\ For some classes managed by NamedObjMgr, PIACmd provide acces to some of the attributes of the object by {\tt \${objname.attname} }. This mechanism has been implemented in particular for TArrays, TMatrix/TVector, Histograms, NTuples and DataTables. In addition, when brackets are used ($\${vname}$), the priority level between interpreter variables and application level variable is changed. If {\tt vname} exist at the application level, {\tt \${vname} } is replaced by its value, even if an interpreter variable with the same name has been defined. \begin{verbatim} # -------- Example with a Vector piapp[1] newvec va 12 piapp[2] echo $va TVector(12) (nr=12, nc=1) # ------- An undefined attribute, such as ? might be # used to get list of valid attributes piapp[3] echo ${va.?} TMatrix.Att: rank size/nelts nrow/nrows ncol/ncols sum # Compound names, in the form name.att must be inclosed in braces {name.att} piapp[4] echo ${va.size} 12 # -------- Example with an histogram piapp[8] newh1d his 0. 20. 40 piapp[10] echo ${his.?} Histo1D: nbin binw mean sigma over under nentries ndata xmin xmax vmin vmax imin imax piapp[11] echo ${his.nbin} 40 \end{verbatim} \item[\rond] {\bf Environment variables} can simply be accessed by {\tt \$varenvname}. However, the environment variables have the lowest priority during substitution. Interpreter's variables have the highest priority, followed by the application level variables. \end{itemize} \subsection{Control structures} \begin{itemize} \item[\rond] Enumerated loop: \begin{verbatim} foreach f ( w1 w2 w3 ... ) ... echo $f end \end{verbatim} Note that spaces before/after '(' et and ')' are mandatory. An alternative form uses a vector variable name : \begin{verbatim} foreach v vecname ... echo $v end \end{verbatim} \item[\rond] Integer type loop: \begin{verbatim} for i startInt:endInt[:stepInt] .... echo $i end \end{verbatim} \item[\rond] Integer type loop: \begin{verbatim} for f startFloat:endFloat[:stepFloat] .... echo $f end \end{verbatim} \item[\rond] Loop over lines of a file \begin{verbatim} forinfile line FileName ... echo $line end \end{verbatim} \item[\rond] The {\tt break} instruction can be used to exit from a loop \item[\rond] {\bf if then else} Conditional execution: \begin{verbatim} if ( test ) then endif if ( test ) then .... else .... endif \end{verbatim} Note that spaces before/after '(' et and ')' are mandatory. test is in the form {\tt a == b} OR {\tt a != b} OR {\tt a < b} OR {\tt a > b} OR {\tt a <= b} OR {\tt a >= b}. Comparison operators should be delimited by spaces. {\tt ==} et {\tt !=} make a string comparison, while {\tt < , > , <= , >=} compare the values obtained after string to double conversion. \end{itemize} \subsection{Script definition} A script is a sequence of commands. It is very similar to the execution of commands from a file ({\bf exec filename}). Once a script has been defined, it can be called specifying specifying the script name followed by its arguments. \begin{verbatim} # Script definition : defscript scriptname [description ] .... endscript # Executing the script Cmd> scriptname arg1 arg2 arg3 .... \end{verbatim} The {\tt return} instruction stops the execution and returns from a script, or from a command file called through {\bf exec}. \\ The commands {\bf listscript } and {\bf clearscript scriptname} can be used to obtain the list of already defined script, or to clear a script definition. \subsection{Other built-in commands} \begin{itemize} \item[\rond] Instruction {\bf echo } to write the line to cout/stdout \item[\rond] Instruction {\bf echo2file} to write (append) the line to file ({\tt echo2file filename ....}) \item[\rond] Instruction {\bf sleep nsec} wait for {\tt nsec} seconds \item[\rond] Instructions {\bf timingon , timingoff , traceon , traceoff } \\ % \item[\rond] {\bf exec filename [arg1 arg2 ... ] } to execute command from the file named {\tt filename}. {\tt .pic} is the default extension for the interpreter command files. \item[\rond] {\bf help} and {help keyword/commandname } \item[\rond] {\bf listvars , listcommands } to print the list of defined variables and known commands \item[\rond] An alias for a command by {\bf alias aliasname 'string ' }. Alias substitution occurs for the first word in a command line. {\bf listalias} prints the list of all defined aliases. \item[\rond] Execution control (piapp/PIACmd extension): It is possible to stop the interpreter execution in a loop, a script or a command file by the {\bf stop} command, or using {\tt } in the piapp console (PIConsole) \\ \end{itemize} \subsection {Command execution in separate threads} It is possible to create new threads to execute commands ( for non built-in interpreter commands). The syntax is similar to unix shell background tasks: an {\&} should be added at the end of the command line. A new thread is then created for the execution of the command, if declared as thread safe \\ (see {\tt CmdExecutor::IsThreadable() }. \par Thread management commands: \begin{itemize} \item[\rond] {\bf thrlist }Print current list of threads, with the associated command the thread identifier (integer ThrId) and its status. \item[\rond] {\bf cleanthrlist } Removes all finished threads from the list. An automatic cleanup is performed periodically. \item[\rond] {\bf cancelthr ThId } / {\bf killthr ThId } Stops/kills the thread with the identifier ThId. Avoid using theses commands as the cleanup does not release some resources associated with the thread (memory, mutex \ldots). \end{itemize} %%%%%%%%%%%%%%% Section 7 : c++ execution \newpage \section{On the fly C++ execution} %%%%%%%%%%%%%%% Section 8 : command reference \newpage \section{piapp command reference} \label{piappcmdref} This section contains the description of piapp commands. This information is available on-line, through the help command, or through a graphic window, accessible by \menubar{File / Help}. The help items and command are divided into different sections, where related commands are grouped. \\[10mm] % \include{piahelp} \input{piahelp.tex} % La partie des appendix \appendix \newpage \section{Interactive control windows} \subsection{DrawerTools} \index{DrawerTools} \label{secdrwtools} The {\bf PIDrawerTools}, shown in the figure \ref{figdrwtools} can be used to change the graphic attributes (color, font, marker, \ldots) of the Drawers displayed in 2D displays ({\bf PIScDrawWdg} \myppageref{PIScDrawWdg}) or 3D displays ({\bf PIDraw3DWdg} \myppageref{PIDraw3DWdg}), as well in image displays {\bf PIImage} (\myppageref{PIImage}). The PIDrawerTools can be activated either using {\tt Alt} on a PIScDrawWdg,PIDraw3DWdg,PIImage, or through the \menubar{Tools/Show DrawerTools}. A given drawer can be selected through the DrawerId selector (+ / - buttons) \vspace*{5mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=8cm]{piapp_drwtools.eps} \caption{PIDrawerTools} \label{figdrwtools} \end{center} \end{figure} %%%% \subsection{AxesTools} \index{AxesTools} \label{secaxestools} The {\bf PIAxesTools}, shown in the figure \ref{figaxestools} can be used to control and change the setting of axes on 2D displays ({\bf PIScDrawWdg} \myppageref{PIScDrawWdg}). The PIAxesTools can be activated either using {\tt Alt} on a PIScDrawWdg or through the \menubar{Tools/Show AxesTools}. \vspace*{5mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=8cm]{piapp_axestools.eps} \caption{PIAxesTools} \label{figaxestools} \end{center} \end{figure} %%%%% \subsection{ImageTools} \index{ImageTools} \label{secimagetools} The {\bf PIImageTools}, shown in the figure \ref{figimgtools} can be used to manipulate a display of type image. Image display are handled by the {\bf PIImage} (\myppageref{PIImage}). The PIImageTools can be activated either using {\tt Alt} on a PIImage, or through the \menubar{Tools/Show ImageTools}. \vspace*{5mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=8cm]{piapp_imgtools.eps} \caption{PIImageTools} \label{figimgtools} \end{center} \end{figure} \subsection{Histo2DTools} \index{Histo2DTools} \label{sech2dtools} The {\bf PIHisto2DTools}, shown in the figure \ref{figh2dtools} can be used to control and change the display caracteristics of 2D histograms. PIHisto2DTools can be activated either using {\tt Alt} on a PIScDrawWdg, when the active drawer is a PIHisto2DDrawer, or through the generic drawer tool PIDrawerTools. \vspace*{5mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=8cm]{piapp_h2dtools.eps} \caption{PIHisto2DTools} \label{figh2dtools} \end{center} \end{figure} \subsection{ContourTools} \index{ContourTools} \label{secconttools} The {\bf PIContourTools}, shown in the figure \ref{figconttools} can be used to control and change the caracteristics of contour displays. PIContourTools can be activated either using {\tt Alt} on a PIScDrawWdg, when the active drawer is a PIContDrawer, or through the generic drawer tool PIDrawerTools. \vspace*{10mm} \begin{figure}[ht!] \begin{center} \includegraphics[width=11cm]{piapp_conttools.eps} \caption{PIContourTools} \label{figconttools} \end{center} \end{figure} Both drawing options (e.g. color, line type, fonts...) and contour determination parameters (e.g. contour number and levels) are controlled by {\bf PIContourTools}. \subsubsection{Drawing options} The top choices in {\bf PIContourTools} concern the color map (left choice) or color (right choice) of the contours. If a color map has been chosen, it is used to give each contour a color (according to its level). If no color map has been chosen, contours may be given a color using the left choice box. Contour are by default traced by lines. Alternatively (or in addition) the user may ask to trace them by markers or to put numeric labels (with the contour's level) aside the contour. These options are enabled/disabled by the {\tt LineON}, {\tt MarkerON} and {\tt LabelON} buttons from {\bf PIContourTools}. Options may be recovered ({\tt GetAtt}) or set ({\tt SetAtt}) from/to a drawer. Setting an option which adds to the screen will be immediately visible whereas unsetting it requires a {\tt Refresh} to be visible. \subsubsection{Contour options} The contouring routines in {\tt spiapp} are based on a hack of the {\tt GNUPlot} routines. Contours are determined from a grid of values using an interpolation scheme. Three schemes may be used (selected by the left menu) : \begin{enumerate} \item Linear interpolation (default), selected by the {\tt Int. Lin.} option \item A cubic spline algorithm, selected by the {\tt CubicSpl} option \item A 2d BSpline algorihm, selected by the {\tt B-Spline} option \end{enumerate} Contour levels and number are automatically determined by the program. They may be specified differently, through command-line options (see section \ref{piappcmdref} for the help of the contour/ntcont commands) or the lower part of the {\bf PIContourTools} window. The user may specify one of the following alternatives : \begin{enumerate} \item the number of contour (their level beeing automatically set). To do this, select {\tt LevelNum} in the right menu and enter the contour number in the left box below. \item the levels of the contours, through an array of numerical values (e.g. 1,4,6,9,27,4.5 will result in 6 contour lines being drawn, if possible and necessary). To do this, select {\tt LevelDisc} and enter the contour number (left box) and the values (right box) separated by ``{\tt ,}''. \item the levels of the contours through an initial (lower) value and an increment. For this, select {\tt LevelInc} and enter the contour number (left box) and the initial value and increment in the right box, as above. \item come back to the default situation, by choosing {\tt LevelAuto} \end{enumerate} Once these options are set, it is necessary the the program recomputes the contour lines. This is commanded by the {\tt SetParm} button. \newpage \addcontentsline{toc}{section}{Index} \printindex \end{document}