The SAM Dataset Editor is a simple web interface which allows you to quickly and easily build and find dataset definitions. It is built in a framed interface, with the Menu frame serving as a dataset definition navigation tool, allowing you to quickly find the definitions of interest to you. The Editor frame is used to display the dataset definition details, including who created it, the keywords assigned to it, the dimensions used to create it, and the files that would be found if it was used to run a project now. You can create or edit dataset definitions directly in this Editor frame. Details about the Menu and Editor sections of this interface are described below.
If you are already familiar with the Dataset Definition Editor, you can check the release notes for a quick review of any updates. All updates are also reflected in the current version of this document.
You can go directly to the SAM Dataset Definition Editor if you are ready.
The left hand side of the Dataset Definition editor is a navigation menu, allowing you to traverse the existing dataset definitions in a number of different ways. The menu is formatted in a hiearchical fashion, with the first level of the hierarchy being some high level concepts which are intended to help in your searching. You first decide if you want to look for existing dataset definitions created for a certain Group, by a certain Person maybe even yourself, with certain Keywords defined, or using certain Dimensions.
Once you select your navigation path, the menu will open another lower level in the hiearchy. This next level will contain a list of all Groups, Persons, Keywords, or Dimensions used to define datasets. In this second level menu, You will notice that to the left of every item is a number in parentheses. This is the number of existing dataset definitions classified by that item. If you pick an option from this menu with a reasonable number of dataset definitions, a summary listing of the dataset name and create time will be displayed in the menu. If you select an option which has a large number of definitions, you will automatically be routed to the SAM Data Browsing page for Dataset Definitions and instructed to perform a more restrictive query. Displaying large sets of dataset definitions in the navigation frame was determined to be too slow and cumbersome a technique. Currently more than 500 dataset definitions triggers the redirection to the query page.
When you finally find the dataset definition of interest, click on it to display it in the Editor window. You can then view it, and edit it if allowed to in the Editor section.
Along the bottom of the menu, you will find the following options:
When editing a dataset definition you must first provide some header information about you and your definition, then you can optionally enter keywords to assist you in finding your definition later, and you must enter the dimensions and constraints that limit the datafiles found by your dataset definition.
When creating a new definition you must enter the required Definition Name, Work Group and Username. You may optionally enter a description and keywords. The description is informational only, helping you and others understand the reason for this project when viewed later. The keywords are for navigational and search purposes, making it easier for you to find certain projects of interest later, by searching on keywords. Finally, you must enter a set of dimensions and constraints.
When editing an existing dataset definition, you will be allowed one of two levels of editing abilities. If the definition has not been used to create any existing analysis projects, then you will be allowed to edit the description, keywords, and even the dimension and constraints that define the dataset file list. But, if the definition has been used to create a project, then you are only allowed to change the keywords. You may not change the work group, person and especially not the dimensions and constraints once a dataset definition has been used.
A detailed description of all the Editor fields and their usage follows.
Definition Name : Enter a name of your choice to describe your definition. This name must be unique across all dataset definitions. If you try to enter a name already used, you will be informed and asked to change it.
Definition Id : A unique integer id will automatically be created once you save your definition.
Create Date : The definition create date and time are automatically stored when you save your dataset definition.
Work Group : The work group name for which the dataset definition is being created must be entered. This name is useful when later navigating the dataset definition navigation menu. It is also useful when creating and starting analysis projects using this definition, as it will be the default work group for the project. The group name entered must be a valid group already defined in the SAM database. If you enter an invalid group name you will be informed to change it. Or, check this list of valid Work Groups now.
Username : The username for which the dataset definition is being created must be entered. This name is useful when later navigating the dataset definition navigation menu. It is also useful when creating and starting analysis projects using this definition, as it will be the default person the project. The person name entered must be a valid person already defined in the SAM database. If you enter an invalid person name you will be informed to change it. Or, check this list of valid Persons now.
Description : Any pertinent descriptive text can be added to better denote the intended use of this dataset definition. This is for information purposes only.
Keywords : Keywords may be added to provide better searching of dataset definitions. You can add keywords to a definition by simply assigning pre-existing keywords to your definition. Or, you can create new keywords on the fly for your dataset definition. Any new keywords created will then show up in the list of available keywords, so that you can then easily reuse them for subsequent dataset definitions. Keywords are useful in the navigational menu of this dataset definition interface.
Dimensions and Constraints : You must enter the dimension/constraint values that define your set of files. There are two techniques you can use to enter your dimensions and their constraints. Using the "Simple Query" entry technique, you can pick dimensions from the pull-down list, enter the constraints, and then pick the and/or/minus operator used to combine your dimensions. This simple technique can be used for most queries.
However, more complex queries may require you to enter your own level of parenthetical grouping of constraints. When entering a more complex query, you can either type the entire thing directly in the Free-Format entry box. Or, you can enter conditions in both the free-format area and the pull-down entry fields. You can then use the Combine Query button to see the resulting query before executing it. Then, you can modify your query as needed, such as changing the paranthetical grouping of operators, changing the comparison operators, or more before you either translate the constraints or save your dataset definition.
For more help on how to enter dimensions, see the Dataset Definition Grammar design document.
Translate Constraints : When you are ready, you can perform a quick translation of your constraints to see if they would create a satisfactory project if run today. A summary of all the files found based on your constraints will be displayed in the scrollable text region below this button. This summary will show the total number of files, the sum of events in all the files, and the average file size. Additionally, it will include the complete list of all file names.
Clone : When viewing an existing dataset definition, you will see a Clone button near the bottom of the page. Cloning a definition will display a new page with the contents of the current definition entered, except for the Definition Id and Create Date which will be blank. You may change any of the header fields, keywords, or dimensions/constraints and then Save your changes when ready to create a new dataset definition.
Save : When creating a new dataset definition, editing a non-used definition, or cloning a definition use the Save button to complete your changes.
Edit : Upon saving the changes to your definition, the page will display differently as an indication that your changes were indeed saved. You will not be able to edit the definition in this display. If you would like to make additional changes to this same definition, simply use this Edit button to redisplay your definition in an editable mode.
Create Dataset : When working with either a new dataset definition, or one that was already used to create datasets, you can create new datasets directly from this web interface. If you are editing a definition, creating a dataset will save the definition first. It will then create a new dataset of the files that meet your constraints at this moment. You may then use this new dataset when running projects. BE SURE TO REMEMBER THE DATASET DEFINITION NAME AND VERSION FOR USE WHEN RUNNING YOUR PROJECT. The same rules for dataset creation are enforced here as the command line interface, which is to say that if your dataset has no files it will not be created, and if it has the same set of files as the last version created for this same dataset, a new version will not be created.
Delete : You may delete dataset definitions that have not been used to create specific datasets. This button will only be shown when this definition does not have any datasets.