Introduction

For the current implementation of the STAR Data Model, all data is collected in tables for each event. To provide a hierarchy for the data, these tables are collected into datasets which represent a subsystem or particular physics analysis. Just like these tables are members of datasets, each of these datasets is then a member of a larger event dataset.

                        event dataset
            _________________|___________..._______
            |           |           |             |
       sub-dataset sub-dataset    table      sub_dataset
       _____|__...__
       |    |      |
    table table   table

Similarly, each dataset is an instance of STAR's St_DataSet class. An associated class, the St_DataSetIter class, provides the functionality of dataset navigation. For instance, you would use an St_DataSetIter to find the tpc dataset within an event, and then you would use another St_DataSetIter to find the particular table in the tpc dataset you want.

Follow along below to learn how these datasets and tables work. To use STAR datasets, you will need to load the St_base shared library. For tables you will additonally need St_Tables:

      gSystem->Load("St_base");
      gSystem->Load("St_Tables");

Using Datasets:

• Dataset names: Every dataset is a named object. This name is stored in a character string inside the object and can be retrieved or set with the GetName() and SetName() member functions respectively. This name is important for finding the dataset.

• Getting an event dataset from an XDF File:

        St_XDFFile xdf_file("file_name","r");     // the "r" is for "read"
        St_DataSet *event = xdf.NextEventGet();
  

  The pointer event now points to the dataset for the first event. This allows you to loop over the events in a file sequentially:

        while (event = xdf_file.NextEventGet()) {
           ...  //Do something with the event
        }
  

• Getting an event dataset from a TFile (Root file): In a TFile, events become datasets with keys. These keys are identified by cycle numbers (which are really just indices starting with cycle number 1 for the first event). This allows you two read events in two ways, shown below. TFile's also have the added feature of being random access: you can read the (n+1)th event without having to read through the n events before it. In a TFile, the event datasets will actually have a name, and you will need to know the name of the event dataset to get it. You can see the events in a TFile by using ls():

        TFile root_file("file_name");
        root_file.ls();
  

  1. You can use the keys to get the event datasets:

           TKey *eventKey = root_file.GetKey("event_set_name",i);
                                            // i = cycle number
           St_DataSet *event = (St_DataSet *) eventKey->ReadObj();
             

     Here, eventKey is a pointer to the key for event number i. The ReadObj() member function of TKey retrieves a pointer to the event dataset. Looping through the events on file is then simple:

           for (Int_t i=1; i<root_file.GetNKeys(); i++) {
              St_DataSet *event = (St_DataSet *) root_file.GetKey("event_set_name",i)->ReadObj();
              ...  //Do something with the event
           }
             

  2. You could just get the event dataset with the TFile's Get() member function, but this means knowing the cycle number of the event you want to get.

           St_DataSet *event = root_file.Get("event_set_name;i");
                                            // i = cycle number
             

• Getting a sub-dataset from a dataset: Now it's time to use iterators, specifically, St_DataSetIter. This iteterator can be used to "find" a child dataset within a parent dataset. As you can see here, it's really rather easy to use an iterator:

        St_DataSetIter iter_name(parent_set);
        St_DataSet *child_set = iter_name("child_set_name");
  

  Here, parent_set is a pointer to the parent dataset, and "child_set_name" is the actual name associated with the child dataset.

• Adding a sub-dataset to a dataset: This is really easy:

        parent_set->Add(child_set);
  

  parent_set is a pointer to the dataset which you want to make the parent of the sub-dataset pointed to by child_set.

Using Tables:

• Understanding the structure of a table: Tables in Root for STAR are all derived from the base class St_Table. You should be aware that a table is essentially a form of a dataset in Root for STAR (more technically, St_DataSet is a base class of the derived class St_Table). This means that tables inherit the same functionality as datasets. In particular, they are found in the same manner, and can be placed on the data tree in the same manner.

  Tables store their rows as array elements (with the first row being array element zero) - notice I said rows, not columns. Each individual row of the St_Table-derived class is an instance of the StAF table class. The first row can be reached with the St_Table's GetTable() member function, and the number of rows can be found with GetNRows(). Nomenclature is as follows: for a table of type St_table_type_name which is an St_Table-derived table class, its rows are instances of the StAF table class table_type_name_st. In the examples below, I will associate aaa with an St_Table-derived table, and bbb with the associated StAF table.

• Getting a pointer to an existing table: Tables are found in the same manner as datasets (described above): you need to know the table's name and its parent dataset. First, make an iterator over the dataset, then call the iterator to find the table:

        St_DataSetIter iter_name(gStChain->DataSet("set_name");
        St_aaa *aaa_name = (St_aaa *) iter_name["table_name"];

  Here, "set_name" is the name of the dataset where the table is located, "table_name" is the name of the table, St_aaa is the St_Table-derived class of the table, and aaa_name is the new pointer to the table. This example shows one aspect of using chains: each dataset associated with a particular maker can be located with the gStChain->DataSet() method. The first line could have been separated into two, getting a pointer to the dataset first (St_DataSet *set = gStChain->DataSet("set_name");), followed by the iterator definition. The pointer which the dataset iterator returns is a St_DataSet pointer, so it must be cast to the table class pointer.

  One more point here is that you will notice I used square brackets when finding the table with the iterator. Both () and [] can be used in place of the Find() member function of St_DataSetIter. However, [] finds only tables. If you feed in a name which is actually a sub-dataset, it will return zero. The moral is to use () when using the iterator to find a sub-dataset, and [] to find a table.

• Reading values from a table: The table values must be accessed from the StAF table class which is associated with an St_Table-derived table class:

        bbb_st *bbb_name = aaa_name->GetTable();
        for (Int_t i=0; i<aaa_name->GetNRows(); i++) {
           hist->Fill(bbb_name[i].value1);
           printf("Value 2: %d\n",bbb_name[i].value2);
        }
  

  In this example, bbb_st is the StAF table class associated with the aaa_name St_Table-derived class, hist is a pointer to a previously define one dimensional histogram (inserted only for example purposes), and value1,value2 are table entries. C++ does provide an alternative method, because the pointer bbb_name can be incremented over the rows (this is standard C++ for using a pointer with an array):

        bbb_st *bbb_name = aaa_name->GetTable();
        for (Int_t i=0; i<aaa_name->GetNRows(); i++) {
           hist->Fill(bbb_name->value1);
           printf("Value 2: %d\n",bbb_name->value2);
           bbb_name++;
        }
  

• Creating a new table: A new table is usually allocated like this:

        St_aaa *aaa_name = new St_aaa("name",rows)

  where St_aaa is a St_Table-derived table class, "name" is the name the table will have, and rows is the number of rows allocated.

• Adding values to a table: If you want to add values to a table yourself, then you have two choices:
  1. Instantiate the actual StAF table class, enter the values, and add this instance to the St_Table-derived class:

           bbb_st bbb_name;
           bbb_name.value1 = 100.;
           bbb_name.value2 = 3.14159;
           aaa_name->AddAt(&bbb_name,n);

     n is the row of the aaa_name table where these values will be inserted (zero is the first row!). If you want to add another row, you do not need to re-instantiate the StAF table class - just reassign the values and add at the next row number you want. This time, bbb_name was actually used as the name of the StAF table object. It could have been used as a pointer if it were defined with:

           bbb_st *bbb_name = new bbb_st();
     

  2. Get a pointer to the StAF table inside the St_Table-derived class, enter values directly, and increment the pointer to change rows:

           bbb_st *bbb_name = aaa_name->GetTable();
           for (Int_t i=0;i<n;i++) {
             bbb_name->value1 = 100.;
             bbb_name->value2 = 3.14159;
             bbb_name++;
           }

     This time, bbb_name is a pointer and is assigned to point to the first row of the table upon its declaration. In this example, values for the first n rows of the table are entered.

• Adding tables to datasets: See the example for adding a sub-dataset to a dataset in Using Datasets above, simply substituting the table for the sub-dataset.