Tutorial 2 ( Creating the first database )

All tutorials assume that you have the HDS-Toolbox installed in Matlab

In this tutorial, we will create a database based on the example HDS-classes that are provided with the HDS-Toolbox. We will create a database, add a variety of objects and data, save the database and reload parts of the database from disk. The class definitions are in the Examples folder. You can create your own class hierarchy using the HDSTemplate.m file in the @HDSTemplate folder.

Step 1: Create new object Each database must have a single 'host'-object. This object is the top of the hierarchical data structure and will contain links to one or more 'child'-objects. From tutorial 1, we know that the 'exMain' class defines objects at the top of the hierarchy, so let's create a variable that contains an object of this class:

M = exMain
M.dbName = 'Sample Database'

What we did is that we defined a variable (M) as an object of class 'exMain'. We subsequently populated the 'dbName' property of the object with a string (This is optional). When the object is displayed in the command window, you will see a couple of links that can provide additional information about the object class. One of the links displays information about the types of classes that can be linked as children to the current object. Click on the 'ChildClasses' link to see this information.

Step 2: Adding children You can link new objects to the 'host' object to expand the database. Linked objects can be accessed similarly to a normal property. Let's add 5 new objects of class 'exSubject' to our host-object:

addobj(M, 'exSubject',5)

Now, let's add some experiment objects to the second subject in the database. You can index into the children just like a property. The returned objects are pointers so we can assign them to a variable without duplicating the data.

S = M.subj(2)
addobj(S, 'exExperiment', 4)

As you can see, the subject object now contains 4 experiments. The property name 'exp' is the default property name for objects of class 'exExperiment' and is defined in its class definition. If you want, you can add the objects to a different property using an additional input argument to the ADDOBJ method. Note that although it looks like the experiment objects are now a part of the subject object, they are in fact stored separately in memory.

Let's assign the name property for the experiments we just added. In the next step you'll see how you can use string based indexing as one of the options to navigate through the database:

E = S.exp;
E(1).name = 'experiment_1'
E(2).name = 'experiment_2'
E(3).name = 'experiment_3'
E(4).name = 'experiment_4'

It is possible to automatically populate object properties when they are created by defining class constructors. This is supported by the ADDOBJ method and you can find more information in the ADDOBJ help section. This falls outside of the scope of this tutorial.

Step 3: Navigating the database You can navigate through a HDS-database in exactly the same way as you would navigate through a large Matlab structure. In addition, one of the properties per class can be used for string-based indexing. This property is specified in the class-definition and can only contain a string.

Try the following variants for accessing objects:

M.subj(2).exp(3);
allSubjects = M.subj;
someSubjects = M.subj([2 5 3]);
someSubjects2 = M.subj([false false true true]);
ExperimentByName = M.subj(2).exp('experiment_3');

Step 4: Saving the database You can save the database using the SAVE method. It does not matter which object from the database is used as the input argument for the method, all unsaved objects will be saved to disk. Select an empty folder to store the database.

 save(M)

The database is stored across multiple files and folders. The binary files are used by the HDS-Toolbox to quickly find objects and the Mat-files are used for the Matlab objects. If you populate properties with 'data' (specified in the class-definition), the values are safed in .NC files. This file format (NetCDF) is better suited for raw data than the MAT-format and allows the user to load portions of data from these properties (Not used in this tutorial).

Step 5: Loading the database from disk If you have the HDSMONITOR enabled, you can see that there are currently 10 objects in memory. As the last part of this tutorial, we will clear the workspace and load a portion of the database back in memory.

CLear the workspace:

 clear all

Verify that all objects are cleared from memory with the HDSMONITOR. Now, let's reopen the database by loading the host object. Use HDSLOAD and select the 'exMain.mat' file in the folder where you stored the database.

 M = hdsload

Now, access the second experiment. Notice that only the objects that are accessed are loaded in memory. This is the main strength of the HDSToolbox and works whether you have a total of 10 or 1 million objects in your database.

 M.subj(2).exp(2)

Summary In this tutorial, the most basic commands of the HDSToolbox were explored. However, the toolbox contains far more possibilities such as, sorting, renaming, deleting of objects. Each method contains a extensive help section (type HELP 'method name'). To create your own class-definitions and database structure, look at the help section of the HDSTemplate class-definition.