Defining DeepSee Models
Defining Dimensions, Hierarchies, and Levels
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to define dimensions and hierarchies, and describes the basics of defining levels. It discusses the following topics:

DeepSee provides many options that affect levels. The next chapter discusses levels in more details.
Overview
In the Architect, you can create model elements in either of two ways:
For reference, the following table describes the result of various drag-and-drop actions:
If you drop the property XYZ here... The Architect creates this...
Measures heading or any existing measure A measure named XYZ, XYZ1 or so on, as needed for uniqueness. The measure is based on the source property XYZ and is aggregated with SUM. See the chapter Defining Measures.”
Dimensions heading A new data dimension named XYZ, XYZ1, or so on, as needed for uniqueness. This dimension contains the hierarchy H1, which contains the level XYZ. The level is based on the source property XYZ.
Existing dimension A new hierarchy (H2, for example), which contains the level XYZ. The level is based on the source property XYZ.
Existing hierarchy A new level named XYZ, XYZ1, or so on, as needed for uniqueness within this hierarchy. The level is based on the source property XYZ.
Existing level A new level property named XYZ, XYZ1, or so on, as needed for uniqueness within this level. The level property is based on the source property XYZ. See the chapter Defining Properties.”
Creating a New Dimension, Hierarchy, and Level
To define a usable level, you must define the following, at a minimum:
In the Architect, you can use drag-and-drop actions as described in Overview.” Or, you can do the following:
  1. Add a dimension:
    1. Click Add Element.
      The system displays a dialog box.
    2. For Enter New Item Name, type a dimension name.
      See Names for Model Elements,” earlier in this book.
    3. Click one of the following choices, depending on the type of dimension you want to create:
    4. Click OK.
      The system creates the dimension and displays it in the Model Viewer. For example:
      Note that DeepSee has also created a hierarchy within this dimension and a level within that hierarchy.
  2. Modify the automatically created level to use a more suitable name:
    1. Click the level in the Model Viewer.
      The system displays details in the Details Area.
    2. Make the following changes:
      • Name — Change this to the level name you want.
        See Names for Model Elements,” earlier in this book.
      • Display Name — Specifies the localized display name for this level. Either clear this (so that the system uses the value given for Name instead) or specify a display name.
      See also Other Common Options,” earlier in this book.
  3. Specify the source values for this level, as described in the section Defining the Source Values for a Dimension or Level.”
  4. Click Save.
  5. When prompted, click OK.
Note:
By default, the Analyzer does not display hierarchy names shown unless a dimension contains multiple hierarchies. Alternatively, a dimension can be defined so that its hierarchy names are always shown or never shown. See the reference for showHierarchies in <dimension> in the appendix Reference Information for Cube Classes.”
Adding a Hierarchy and Level
In the Architect, to add a hierarchy and a level to an existing dimension, you can use drag-and-drop actions as described in Overview.” Or, you can do the following:
  1. Click the dimension in the Model Viewer.
  2. Click Add Element.
    The system displays a dialog box.
  3. For Enter New Item Name, type a hierarchy name.
    See Names for Model Elements,” earlier in this book.
  4. Click Hierarchy.
  5. Click OK.
    The system creates the hierarchy and displays it in the Model Viewer. It also creates one level within that hierarchy.
  6. Optionally select the hierarchy in the Model Viewer and edit the details in the Details Area.
  7. Select the level in the Model Viewer and edit the details in the Details Area.
Adding a Level
In the Architect, to add a level to an existing hierarchy, you can use drag-and-drop actions as described in Overview.” Or, you can do the following:
  1. Click either the hierarchy or an existing level within that hierarchy, in the Model Viewer.
    This action indicates where the level is to be added:
  2. Click Add Element.
    The system displays a dialog box.
  3. For Enter New Item Name, type a level name.
  4. Click Level.
  5. Click OK.
    The system creates the level and displays it in the Model Viewer.
  6. Optionally select the level in the Model Viewer and edit the details shown in the Details Area.
Alternatively, drag a class property from the Class Viewer and drop it onto a hierarchy. The system adds a level based on this property; this level is added after any other levels in this hierarchy.
Important:
The order of the levels in a hierarchy determines the structure of the hierarchy, as noted in Defining Hierarchies Appropriately,” earlier in this book. If you want to reorder the levels after defining them, see Changing the Order of Levels in a Hierarchy.”
Defining the Source Values for a Dimension or Level
Each level must have a specified source value. You can specify the source values within the dimension or within the level. Typically:
To specify a source value in the Architect:
  1. Select the dimension or the level in the Model Viewer.
  2. In the Details Area, specify a value for one of the following:
You can enter values into the Property and Expression fields in any of the following ways:
The information on this section and in the next section also applies to level properties and to measures, which also require source values of some form.
Specifying a Source Value when Using a Data Connector
If the cube is based on a data connector, note the following restrictions:
For information on creating data connectors, see Defining Data Connectors in the DeepSee Implementation Guide.
Details for Source Expressions
As noted in the previous section, you can specify either a source value or a source expression to use as the basis of a dimension or level (or property or measure). You can create source expressions as follows:
Note:
You cannot use a source expression if the cube is based on a data connector.
Also, if a level is based on a source expression (rather than a source property) and if the members have purely numeric names, InterSystems recommends that you also modify the cube in Studio and add castAsNumeric="true" to that level definition. This option causes DeepSee to treat the members as numbers when searching for a replacement for a member that does not exist, when a query that uses an MDX range expression (a specific kind of set expression).
Using a Term List
Term lists provide a way to customize a DeepSee model without programming. A term list is a simple (but extendable) list of key and value pairs. (See Defining Term Lists in the Advanced DeepSee Modeling Guide.)
You can invoke a term list within a source expression. To do so, use the %Lookup() method of %DeepSee.CubeDefinition. This method has the following signature:
%Lookup(term_list_name, lookup_value,default,alternative_field)
Where the arguments are strings, and their values are as follows:
This function examines the given term list, finds the term whose "key" field equals the string given by lookup_value and then returns the value contained in the field identified by alternative_field.
All term lists have at least two fields: "key" and "value". You can add additional fields. For information, see Defining Term Lists in the Advanced DeepSee Modeling Guide.
Note:
Because your cube definition class inherits from %DeepSee.CubeDefinition, which defines the %Lookup() method, you can use a source expression like the following:
%cube.%Lookup(term_list_name,lookup_value,default,alternative_field)
For example, suppose that you have the following term list, called LocalTeams:
You could add a property to the City level in HoleFoods as follows:
<property name="Team" sourceExpression='%cube.%Lookup("LocalTeams",%source.Outlet.City,"No Team")'/>
Using an Ensemble Business Rule
Business rules allow nontechnical users to change the behavior of Ensemble business processes. You can also use them in source expressions in DeepSee cubes. (For details on Ensemble business rules, see Using Business Rules with Ensemble.)
To access an Ensemble business rule within a source expression, use the %Rule() method of %DeepSee.CubeDefinition. This method has the following signature:
%Rule(rule_name)
Where rule_name is the name of an Ensemble business rule.
When this function is evaluated (for a given source record) during a cube build, the system passes to it an instance of the cube source class as the context object. The system uses this object, evaluates the rule, and then accesses the value returned by the rule.
Note:
Because your cube definition class inherits from %DeepSee.CubeDefinition, which defines the %Rule() method, you can use a source expression like the following:
%cube.%Rule(rule_name)
Changing the Order of Dimensions in the Cube
In the Architect, to change the order of dimensions in the cube:
  1. Click Reorder.
    The system displays a dialog box.
  2. Click Dimensions.
  3. Optionally click Alphabetize to alphabetize them.
    This affects the list immediately. You can then reorganize the list further if needed. Also, when you add dimensions, they are not automatically alphabetized.
  4. Click the name of a dimension and then click the up or down arrows as needed.
  5. Repeat as needed for other dimensions.
  6. Click OK.
The order of the dimensions in the cube affects how they are displayed in the Analyzer. It does not have any other effect. Some customers choose to alphabetize their dimensions for convenience; others put more-often used dimensions at the top of the list.
Changing the Order of Levels in a Hierarchy
In the Architect, to change the order of levels in a hierarchy:
Important:
The order of the levels in a hierarchy determines the structure of the hierarchy, as noted in Defining Hierarchies Appropriately,” earlier in this book.
Validating Your Levels
After defining levels, you should build the cube and validate that the levels behave appropriately. For each level, use the Analyzer and create a new pivot table that displays the level as rows.
  1. Click DeepSee, click Analyzer, and then click Go.
    Tip:
    If the Analyzer is already open, just click the Analyzer link at the top of the page.
  2. If the left area is not currently displaying the cube you are validating, click Open and choose the cube.
  3. In the left area, find the dimension that contains the level, and expand that dimension.
  4. Drag and drop the level to the Rows box.
In this pivot table, look for the following items:
Tip:
In the Analyzer, you can access the generated MDX query for a pivot table (to do so, click the Query Text button ). Then you can save that query to a text file and rerun the query later programmatically. This technique enables you to revalidate the model again later, if the data has changed. Sometimes new data contains values that you did not consider when creating the model.
For information on running queries programmatically, see the DeepSee Implementation Guide.
Another useful tool is the %AnalyzeMissing() method of %DeepSee.Utils. This method analyzes every non-computed level, measure, and relationship within the given cube and return the number of facts that have no value for each. For example:
Do ##class(%DeepSee.Utils).%AnalyzeMissing("patients")
 
-----------------------------------------------------------------------------
    Level                                                   #Missing %Missing
Lvl [AgeD].[H1].[Age]                                              0    0.00%
Lvl [AgeD].[H1].[Age Bucket]                                       0    0.00%
Lvl [AgeD].[H1].[Age Group]                                        0    0.00%
Lvl [AllerD].[H1].[Allergies]                                    388   38.80%
Lvl [AllerSevD].[H1].[Allergy Severities]                        388   38.80%
Lvl [BirthD].[H1].[Date]                                           0    0.00%
Lvl [BirthD].[H1].[Decade]                                         0    0.00%
Lvl [BirthD].[H1].[Period]                                         0    0.00%
Lvl [BirthD].[H1].[Quarter Year]                                   0    0.00%
Lvl [BirthD].[H1].[Year]                                           0    0.00%
Lvl [BirthQD].[H1].[Month]                                         0    0.00%
Lvl [BirthQD].[H1].[Quarter]                                       0    0.00%
Lvl [BirthTD].[H1].[Birth Time]                                    0    0.00%
Lvl [ColorD].[H1].[Favorite Color]                               221   22.10%
Lvl [DiagD].[H1].[Diagnoses]                                     831   83.10%
Lvl [DocD].[H1].[Doctor]                                         159   15.90%
Lvl [DocD].[H1].[Doctor Group]                                   271   27.10%
Lvl [GenD].[H1].[Gender]                                           0    0.00%
Lvl [HomeD].[H1].[City]                                            0    0.00%
Lvl [HomeD].[H1].[ZIP]                                             0    0.00%
Msr [Measures].[Age]                                               0    0.00%
Msr [Measures].[Allergy Count]                                   388   38.80%
Msr [Measures].[Avg Age]                                           0    0.00%
Msr [Measures].[Avg Allergy Count]                               388   38.80%
Msr [Measures].[Avg Enc Count]                                     0    0.00%
Msr [Measures].[Avg Test Score]                                  200   20.00%
Msr [Measures].[Encounter Count]                                   0    0.00%
Msr [Measures].[Test Score]                                      200   20.00%
Lvl [PatGrpD].[H1].[Patient Group]                                 0    0.00%
Lvl [PatGrpD].[H1].[Tested]                                        0    0.00%
Lvl [ProfD].[H1].[Industry]                                      564   56.40%
Lvl [ProfD].[H1].[Profession]                                    564   56.40%
 
    TOTAL FACTS                                                1,000