Documentation / User's manual in C++ :

An example of import of the data file "geyser.dat" (available in the Uranie-macros folder) is shown below leading to a 2D scatterplot of the variable x2 versus the variable x1

using namespace URANIE::DataServer; 

TDataServer * tdsGeyser = new TDataServer("tdsgeyser", "Geyser database"); 
tdsGeyser->fileDataRead("geyser.dat");
tdsGeyser->draw("x2:x1");      

The obtained graph is the following:

Figure II.36. Import data from an ASCII file

Various examples of macros loading data in a TDataServer with different treatment applied on, are provided in the use-case chapter of this user manual, between Section XIV.2.3 and Section XIV.2.7.

From a TTree object (or any of its derived-object) contained in a ROOT-file, it is possible to import data, with or without selection of a variable and addition of other ones through formula then deletions of patterns ensuring a criterion

using namespace URANIE::DataServer; 

TDataServer * tds = new TDataServer(); 
tds->ntupleDataRead("hsimple.root","ntuple","px*px:*:py*py","px*px+py*py<2.0"); 
tds->draw("py:px");      

In this case, tds is constructed from the TTree ntuple contained in the file hsimple.root where all initial variables are kept (* character). Figure II.37 shows the content of the ntuple. Two new variables are then added on top, defined by the equations "px*py" and "py*px" on both side of the "*" string. A cut is finally done, to exclude all data that would satisfy the following equation

Figure II.37. Content of the ntuple tree contained in "hsimple.root" file.

The obtained graph is as follow:

Figure II.38. Data importation from a TNtuple

Attributes can always be added to an existing TDataServer object, whether it is empty (just after its constructor) or not (after the data loading from either an ASCII file, or a TTree or a database of type SQL). A simple example is provided and decomposed in Section XIV.2.1.

First of all, let us consider the case of an empty TDataServer. We add attributes using the method addAttribute( TAttribute *att).

TDataServer * tds = new TDataServer("tds", "new TDataServer");
tds->addAttribute( new TAttribute("x1"));           
tds->addAttribute( new TAttribute("x2", 2.5, 5.));  
tds->addAttribute( "x3" );                          
tds->addAttribute( "x4", 2.5, 5.);                        

The difference between the methods with new in it and the others, is basically arising from the way one handles the memory. The last ones (3 and 4) allow the user not to worry about anything, while, in the case of implementation 1 and 2, one should be aware that every new should imply at some point a delete. For most user, this is not of utmost importance as usual scripts would contain very few new command and no loop. If this is not the case (for instance if one does have loop and many object creation in it) do not hesitate to contact the Uranie-team to prevent any slowing down of the code.

The specification of a TAttribute is further detailed in Section II.2.

We can define new attributes using mathematical expressions with respect to other existing attributes. The name and the mathematical expression are the only mandatory arguments; its title and unit can also be precised, but both arguments are optional.

TDataServer * tdsGeyser = new TDataServer("tdsgeyser", "Geyser DataSet");
tdsGeyser->fileDataRead("geyser.dat");
tdsGeyser->addAttribute("cd1","sqrt(x2) * x1");    
tdsGeyser->addAttribute("cd2","sqrt(x2*x1)","#Delta p_{#sigma}","sec^{-1}");  

tdsGeyser->draw("cd2:cd1");          

Description attribute adding to a TDataServer from formulas

	Adding a new attribute cd1 to the TDataServer defined by a mathematical expression as a function of x1 and x2 attributes:
	Adding a new attribute cd2 to the TDataServer with a mathematical formula, precising its title and unit:
	Plots the scatterplot of the variable cd2 versus the variable cd1

The obtained graph is:

Figure II.39. Scatterplot of added attributes

This operation is available with vector-type attribute as well. The results depends on the nature of the attributes involved in the formula, their content and the nature of the operation. As an example, a simple dataserver is created from the dummy file tdstest.dat:

#COLUMN_NAMES: x| y| a| v
#COLUMN_TYPES: V|V|D|V

1,2,3 4,5,6 2 1,2,3
7,8,9 1,2   4 4,5,6
1,4,8 2,5,4 5 7,8,9 

It contains two vectors whose size are not constant and a double. The four usual operations have been performed (addition, subtraction, multiplication and division) using the double and a vector but also using the two vectors. The code is shown here:

{
  TDataServer *tdsop =new TDataServer("foo","poet");
  tdsop->fileDataRead("tdstest.dat");
    
  tdsop->addAttribute("x*y","x*y"); // Multiply two vectors
  tdsop->addAttribute("xovy","x/y"); // Divide two vectors
  tdsop->addAttribute("x-y","x-y"); // Subtract two vectors
  tdsop->addAttribute("x+y","x+y"); // Add two vectors
  
  tdsop->addAttribute("x*a","x*a"); // Multiply a vector and a double
  tdsop->addAttribute("xova","x/a"); // Divide a vector and a double
  tdsop->addAttribute("x-a","x-a"); // Subtract a vector and a double
  tdsop->addAttribute("x+a","x+a"); // Add a vector and a double

  tdsop->scan("x:y:a:x*y:xovy:x+y:x-y:x*a:xova:x+a:x-a","","colsize=3 col=1:1:1::4::::4:");
  } 

and it gives as a results:

*************************************************************************************
*    Row   * Instance * x * y * a * x*y * xovy * x+y * x-y * x*a * xova * x+a * x-a *
*************************************************************************************
*        0 *        0 * 1 * 4 * 2 *   4 * 0.25 *   5 *  -3 *   2 *  0.5 *   3 *  -1 *
*        0 *        1 * 2 * 5 * 2 *  10 *  0.4 *   7 *  -3 *   4 *    1 *   4 *   0 *
*        0 *        2 * 3 * 6 * 2 *  18 *  0.5 *   9 *  -3 *   6 *  1.5 *   5 *   1 *
*        1 *        0 * 7 * 1 * 4 *   7 *    7 *   8 *   6 *  28 * 1.75 *  11 *   3 *
*        1 *        1 * 8 * 2 * 4 *  16 *    4 *  10 *   6 *  32 *    2 *  12 *   4 *
*        1 *        2 * 9 *   * 4 *   0 *      *   0 *   0 *  36 * 2.25 *  13 *   5 *
*        2 *        0 * 1 * 2 * 5 *   2 *  0.5 *   3 *  -1 *   5 *  0.2 *   6 *  -4 *
*        2 *        1 * 4 * 5 * 5 *  20 *  0.8 *   9 *  -1 *  20 *  0.8 *   9 *  -1 *
*        2 *        2 * 8 * 4 * 5 *  32 *    2 *  12 *   4 *  40 *  1.6 *  13 *   3 *
*************************************************************************************
 

It is sometimes necessary to merge two TDataServer to form a single one. Since the merging is done line by line, one has to check that both objects contain the same number of patterns. In Uranie-version older than 3.10.0 it was assumed that the patterns were exactly stored in the same order. Now the method is looking for the iterator of both TDataServer objects and it checks that both iterators contain the same value all along (not necessary in the same order, for instance when dealing with distributed computations). If the iterators are not found or if some iterator's values are found in one iterator but not the other (possible in some rare cases such as OAT sampling), the merging is done line-by-line and a warning is displayed.

This operation is common when you want to build a surface response between output variables Y and predictors X and these data are located in two different files.

Let's take a simple example. Assuming that we have 2 TDataServer tds1 and tds2 respectively located in the ASCII files tds1.dat and tds2.dat. Another example is also provided in Section XIV.2.2.

Data file tds1.dat

#COLUMN_NAMES: x| dy| z| theta
#COLUMN_TITLES: x_{n}| "#delta y"| ""| #theta
#COLUMN_UNITS: N| Sec| KM/Sec| M^{2}

1 1 11 11
1 2 12 21
1 3 13 31
2 1 21 12
2 2 22 22
2 3 23 32
3 1 31 13
3 2 32 23
3 3 33 33 

Data file tds2.dat

#COLUMN_NAMES: x2| y| u| ua

1 1 102 11
1 2 104 12
1 3 106 13
2 1 202 21
2 2 204 22
2 3 206 23
3 1 302 31
3 2 304 32
3 3 306 33 

Both TDataServer incorporate 9 patterns.

These 2 ASCII files must be loaded in 2 TDataServer (cf Section II.3.2), the merging being done by calling the merge method of the first TDataServer

{
  TDataServer * tds1 = new TDataServer();
  tds1->fileDataRead("tds1.dat");

  TDataServer * tds2 = new TDataServer();
  tds2->fileDataRead("tds2.dat");

  tds1->merge(tds2);
  }

Thus, the object tds1 also contains the attributes of the second TDataServer tds2

**************************************************************
*    Row   * tds * x. * dy * z. * theta * x2 * y. * u.u * ua *
**************************************************************
*        0 *   1 *  1 *  1 * 11 *    11 *  1 *  1 * 102 * 11 *
*        1 *   2 *  1 *  2 * 12 *    21 *  1 *  2 * 104 * 12 *
*        2 *   3 *  1 *  3 * 13 *    31 *  1 *  3 * 106 * 13 *
*        3 *   4 *  2 *  1 * 21 *    12 *  2 *  1 * 202 * 21 *
*        4 *   5 *  2 *  2 * 22 *    22 *  2 *  2 * 204 * 22 *
*        5 *   6 *  2 *  3 * 23 *    32 *  2 *  3 * 206 * 23 *
*        6 *   7 *  3 *  1 * 31 *    13 *  3 *  1 * 302 * 31 *
*        7 *   8 *  3 *  2 * 32 *    23 *  3 *  2 * 304 * 32 *
*        8 *   9 *  3 *  3 * 33 *    33 *  3 *  3 * 306 * 33 *
**************************************************************

It can be necessary during a study to apply filters on the patterns; i.e. to include or to exclude patterns depending on criterion. For example, to select the patterns with x1 lower than 3.0 and x2 lower than 55.0 from the geyser database, Uranie code is as follows:

tdsGeyser->setSelect("( x1<3.0 ) && ( x2<55.)");
tdsGeyser->draw("x2:x1");      

The obtained figure is:

Figure II.40. Graph with a selection definition

The result of the scan method applied on this TDataServer object yields:

************************************************
*    Row   *        x1 *        x2 * n__iter__ *
************************************************
*        1 *       1.8 *        54 *         2 *
*        8 *      1.95 *        51 *         9 *
*       10 *     1.833 *        54 *        11 *
*       13 *      1.75 *        47 *        14 *
*       15 *     2.167 *        52 *        16 *
...
*      268 *      2.15 *        46 *       269 *
*      270 *     1.817 *        46 *       271 *
************************************************
==> 53 selected entries

We have obtained 53 patterns among 278 respecting the given criterion without having to specify this criterion for the draw and scan calls. To get the same result, we could have executed the following command as well:

tdsGeyser->draw("x2:x1", "( x1<3.0 ) && ( x2<55.)");
//tdsGeyser->scan("*", "( x1<3.0 )  && ( x2<55.)");      

However, in this case, we have to repeat the criterion for each command.

It is also possible to exclude patterns coming from TDataServer with the setCut method.

tdsGeyser->setCut(TString("x1 >= 3."));
tdsGeyser->draw("x2:x1");      

The obtained figure is as follows:

Figure II.41. Graph with a definition of Cut

It can be noticed in the title of Figure II.41, that it simply corresponds to the opposite of criterion's meaning with respect to the one given by the setCut method with the ! ( ) character. Thus, the setCut method consists in passing on the negation of the criterion to the setSelect command.

Finally, it is perfectly possible to delete the current filters with the methods clearSelect and clearCut, and retrieving the unfiltered results.

 <URANIE::INFO>  Selection is changing ==> clearing the TAttribute computed statistics and quantiles

In the same way as the data are imported from an ASCII file, we can also save the data of a TDataServer in an ASCII file. Currently, four methods of export are available in Uranie:

TDataServer * tdsGeyser = new TDataServer("tdsgeyser", "geyser database");
tdsGeyser->fileDataRead("geyser.dat");
tdsGeyser->addAttribute("y", "sqrt(x2) * x1");

tdsGeyser->exportData("newfile.dat"); 
tdsGeyser->exportDataHeader("newfile.C", "x1:x2:y"); 
tdsGeyser->exportDataNeMo("newfile.nemo", "x1:x2", "y", "x2<75.0"); 
tdsGeyser->exportDataJSon("newfile.json");       

#NAME: tdsgeyser
#TITLE: Database of the geyser
#DATE: Tue Oct  9 15:41:29 2007
#COLUMN_NAMES: x1| x2| y| n__iter__

3.600000000e+00 7.900000000e+01 3.199749990e+01 1
1.800000000e+00 5.400000000e+01 1.322724461e+01 2
3.333000000e+00 7.400000000e+01 2.867155012e+01 3
2.283000000e+00 6.200000000e+01 1.797635998e+01 4
4.533000000e+00 8.500000000e+01 4.179219502e+01 5
...
2.150000000e+00 4.600000000e+01 1.458200946e+01 269
4.417000000e+00 9.000000000e+01 4.190334127e+01 270
1.817000000e+00 4.600000000e+01 1.232349358e+01 271
4.467000000e+00 7.400000000e+01 3.842658697e+01 272

// File "newfile.C" generated by ROOT v5.17/04
// DateTime Tue Oct  9 15:41:30 2007
// DataServer: Name="tdsgeyser" Title="Database of the geyser" Select=""

#define essai_nPattern 272

//  Attribute Name="x1" Title=" x_{1}"
Double_t x1[essai_nPattern] = {
3.600000000e+00,
1.800000000e+00,
...
1.817000000e+00,
4.467000000e+00,
};
// End of attribute x1

//  Attribute Name="x2" Title=" #delta x_{2}"
Double_t x2[essai_nPattern] = {
7.900000000e+01,
5.400000000e+01,
...
1.232349358e+01,
3.842658697e+01,
};
// End of attribute y

// End of File newfile.C

#NombreExemples 126
#NombreEntrees 2
#NombreSorties 1

1.800000000e+00 5.400000000e+01 1.322724461e+01 
3.333000000e+00 7.400000000e+01 2.867155012e+01 
2.283000000e+00 6.200000000e+01 1.797635998e+01 
2.883000000e+00 5.500000000e+01 2.138090024e+01
...
2.150000000e+00 4.600000000e+01 1.458200946e+01 
1.817000000e+00 4.600000000e+01 1.232349358e+01 
4.467000000e+00 7.400000000e+01 3.842658697e+01 

{
  "_metadata" : 
  {
    "_comment" : "CurrentComment",
    "date" : "Fri Oct 28 10:41:44 2016",
    "short_names" : [ "x1", "x2", "geyser__n__iter__" ],
    "table_description" : "Les donnees du geyser",
    "table_name" : "geyser",
    "types" : [ "D", "D", "D" ],
    "units" : [ "Sec", "", "" ]
  },
  "items" : 
  [
    
    {
      "geyser__n__iter__" : 1.0,
      "x1" : 3.60,
      "x2" : 79.0
    },
    
    {
      "geyser__n__iter__" : 2.0,
      "x1" : 1.80,
      "x2" : 54.0
    },

      
      
    {
      "geyser__n__iter__" : 272.0,
      "x1" : 4.4670,
      "x2" : 74.0
    }
  ]
}