From: <ro...@us...> - 2003-10-28 13:54:30
|
Update of /cvsroot/nsclspectcl/SpecTcl/doc/Programming In directory sc8-pr-cvs1:/tmp/cvs-serv15919 Added Files: filterread.htm Log Message: Added version 2.1 documentation --- NEW FILE: filterread.htm --- <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <meta name="ProgId" content="FrontPage.Editor.Document"> <title>New Page 1</title> </head> <body> <table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <th width="9%" nowrap><a href="http://www.nscl.msu.edu"><img src="../images/nscl_logo_small.gif" alt="nscl_logo_small.gif (2463 bytes)" width="63" height="52"></a></th> <td width="79%"> <h1> Reading Filtered Data</h1> </td> <td width="12%"><a href="index.htm"><img src="../images/HH00706_.jpg" alt="HH00706_.jpg (6530 bytes)" width="192" height="84"></a></td> </tr> </table> <p><a href="index.htm" name="Top">SpecTcl Home</a> <a href="general_information.htm">General Information</a> <a href="users_guide.htm">User Guide</a> <a href="programmers_guide.htm">Programmer's Guide</a> <a href="obtaining_and_installing.htm">Obtaining and Installing</a></p> <p>Filtered data files are stored in a self-describing, system independent manner. This page describes:</p> <ul> <li>How to recover the raw parameters recorded in a filtered data file.</li> <li>In general terms the structure of a filtered data file.</li> <li>How the filtered event decode software works.</li> </ul> <h2><a name="reading"></a>Recovering raw parameters in a filtered data file</h2> <p>Filtered data are not stored in NSCL event buffer format. Instead a self describing, system independent representation is used based on the eXternal Data Representation (XDR) standard. XDR is a mature specification for representing binary data in a system independent manner.</p> <p>To read back event data from a filter file you must:</p> <table border="0" width="100%"> <tr> <td width="5%" valign="top"><img border="0" src="../images/BD21301_.GIF" width="13" height="13"></td> <td width="95%">Create a tailored version of SpecTcl which uses a CFilterEventProcessor as the first element of the analysis pipeline.</td> </tr> <tr> <td width="5%"><img border="0" src="../images/BD21301_.GIF" width="13" height="13"></td> <td width="95%">When attaching to the event file specify that the event file is in filter format.</td> </tr> </table> <p><a href="#Top">Top</a></p> <h3>Tailoring MySpecTclApp.cpp:</h3> <p><a href="../tailoring/tailoring.htm">Follow the instructions for tailoring SpecTcl</a>, however when you edit MySpecTclApp.cpp, you must specify that the first element of the event processing pipeline is an object of type CFilterEventProcessor. To do this:</p> <ul> <li>Add an include for the filter event processor type:</li> </ul> <pre>#include <FilterEventProcessor.h></pre> <ul> <li>Create an instance of the filter event processor:</li> </ul> <pre>static CFilterEventProcessor FilterProcessor;</pre> <ul> <li>Register this filter processor as the first element of the event processing pipeline:</li> </ul> <pre>void CMySpecTclApp::CreateAnalysisPipeline(CAnalyzer& rAnalyzer) { RegisterEventProcessor(FilterProcessor); </pre> <pre> // Register any additional event processors here. </pre> <pre> ...</pre> <pre>}</pre> <p>Use the <b>make<i> </i></b>command to build your tailored SpecTcl. This SpecTcl will only be able to read filtered event data.</p> <p><a href="#Top">Top</a></p> <h3>Attaching filtered event data</h3> <p>When attaching a filtered data source, you must specify that it is in filter format. For example:</p> <pre>attach -file -format filter myfilteredfile.flt</pre> <pre><a href="#Top">Top</a></pre> <h2><a name="structure"></a>Structure of a Filtered event file.</h2> <p>Filtered event files contain XDR encoded binary data. Each event file is written in fixed length blocks. All data described below have been XDR encoded. Each buffer is a self-contained XDR input stream. Buffers have a single long header that is the value of the offset into the stream past the last data item inserted.</p> <p>Filtered files contain a single event description record followed by an arbitrary number of event records. The event description record describes the set of parameters that have been recorded in the filtered data set. Since it is possible and perhaps usual to combine the filtering of several runs of data into a single event output file, filtered data sets do not have any concept of a run number or title. The event description record contains a string header, an integer and a set of strings. The string header contains the text "header" and distinguishes this data record from event data. The integer is the number of parameters in the filtered data set, the strings are the names of the parameters as they were specified to the filter command.</p> <p>Event data consists of a string header, an array of integer bit masks and a set of floating point parameter values. The header contains the string "event" to distinguish this record as an event record. The bit masks are an array of long words containing one bit for each parameter in the list of parameters in the filtered data set. Bits are packed from low order bit to high order bit. Each bit the bit mask will have the corresponding parameter present in the event. The bit masks should be processed from first long word to last long word from bottom set bit to top set bit.</p> <h2><a name="theory">How the filter event decode software works</a></h2> <p>The filtered event decode software consists of two components. A specialized buffer decoder, selected by the -format filter qualifier on the attach command, and a filter event decoder attached by the programmer in CMySpecTclApp::CreateAnalysisPipeline().</p> <p>The buffer decoder decodes the top level XDR buffers into internal representation. When it encounters a header record, it invokes the analyzer's OnOther callback. It groups physics events into contiguous runs which are passed to the analyzer's OnPhysics callback.</p> <p>The event decoder implements both the OnOther and operator() entry points of a CEventProcessor class. For OnOther, the parameter names are matched against currently defined SpecTcl parameter names and a mapping is made between parameters in the filtered event streams and the parameters that have been defined to SpecTcl. Null mappings (cases where there is no SpecTcl parameter corresponding to a Filter parameter) are allowed.</p> <p>For each event, the bit mask is decoded to determine the set of filtered parameters that are actually present in the event. Each parameter present is then pulled out of the event. Two cases then apply:</p> <ul> <li>If there is a non-null mapping between the parameter and a SpecTcl parameter (there exists a SpecTcl parameter with the same name as the filter parameter), SpecTcl will copy the value in the raw event to the appropriate rEvent element.</li> <li>If there is a null mapping between the parameter and SpecTcl parameters (SpecTcl does not have a parameter with the same name as the filter parameter), SpecTcl will ignore that parameter.</li> </ul> <hr> <p>Last Modified: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%B %d, %Y" startspan -->October 28, 2003<!--webbot bot="Timestamp" endspan i-checksum="30351" --> by: <a href="mailto:fo...@ns...">fo...@ns...</a><br> <font size="2">© Copyright NSCL 1999, All rights reserved</font></p> </body> </html> |