This section introduces the concepts and functions needed to work with WinList's database features. It is more of a discussion than a tutorial, however there are examples to clarify some aspects of the system.
WinList has a simple, yet powerful database engine that allows you to store large amounts of data easily in one or more database files. You can view databases from within the program, manually add, delete, and replace records, and select the fields you want to store in each database. The databases are created in a simple, text format known as tab-delimited ASCII text, which can be read by common database and spreadsheet programs. These features give you a great deal of flexibility in choosing what information to store, where to store it, and how to integrate the information into other database systems.
How do you create a database?
Set up WinList with a protocol before you create or edit a database. This includes opening one or more data source files, selecting the histograms you want to work with, creating regions and gates, and displaying results. You can set up a separate database for each protocol you use, one database for everything you do with the program, or anything in between.
It's important to have an FCS file open and regions defined before you create a database. The information available to the database depends on what you have set up on the screen.
Databases are accessible from the Edit tab on the ribbon bar. Click the Setup button in the Databases group to display the Edit All Databases dialog.
There is one database, "Database1", created by the program automatically. This database will not store anything until you tell the program what information you want to save. To do so, you need to select the database in the list and click the Edit button. You can also double-click on the item in the list to do this.
The Edit Keyword Map dialog is displayed. The left side of this dialog presents the information available to store, and the database fields already added are shown on the right. The two controls on the left are the Keyword Groups tree and the Keywords list. The right-hand list is the Keyword-Database Map, showing the fields you will store in the database. Initially, the right-hand list is empty.
What can you database?
WinList allows you to database virtually any statistic it generates, as well as keyword information from the files that you analyze. The tree in the top left of the dialog can be expanded to display branches of keywords. To open a branch of the tree, double-click on it with the mouse.
Sometimes it's easier to create a database directly from Results windows that you have already created. The Database Wizard makes that an easy task by automatically adding fields for the selected Results window.
As you select a branch in the tree, the list below the tree will fill with the objects beneath the branch. For example, when you double-click to open the Region keywords branch, the Keywords list below the tree will fill with a folder for each region that has been created. These also appear in the tree because they are branches that can be expanded further. File keywords come from the FCS keywords for each data source; System keywords are items like current date, and current time.
When you see an item in the Keywords list that you want to database, select it and click the Add button. One or more fields will be created, depending on what you have selected to add. Here is the important thing to understand about adding items to the database: everything contained in the selected item will be added to the database. This means that if you select the File keywords, the Region keywords, and the System keywords list items and click Add, everything that WinList can store for the current Protocol will be added to the database.
There is a downside to this simplicity. It is very easy to create a database with much more information than you want or need. In fact, you can create a database that other programs will not read because it has too many fields.
In most cases, you probably want to store most of the Region keywords, but rarely would you want to store all of the File keywords. File keywords come from the files you are analyzing, and many of them are meaningless to anything except the program that created the files. For example, storing how many bytes each parameter for each event uses in the listmode file is not useful information, in most cases. On the other hand, keywords that identify the sample, experiment, and file name will be useful to database.
Another reason you would not want to store all the File keywords is the limitation that most database and spreadsheet programs impose. Other programs usually will not read a database with more than 255 fields of data. If, for example, your files contained 100 keywords and you set up a protocol with 10 data sources open at once, there would be 1000 keywords available to you in the File keywords branch. Reading such a database is well beyond the capabilities of most other programs. Since it is likely that you will want to open WinList databases with other software, avoid creating databases with more than 255 fields.
A better solution, if you need to store more information, is to break the storage into several smaller databases. This is possible because WinList can work with any number of database files simultaneously.
The field names initially assigned when you click the Add button are designed to help you know what keyword has been added. For example, all of the keywords relating to Region R1 are prefixed with "R1:", so you can differentiate "MeanX" for regions R1 and R2 easily.
File keywords are prefixed with the data source id.
Editing fields
You can edit the names for the fields after they are added to the Keyword-Database Map list, if you wish. Click once on the field name to select it. After a brief pause, click slowly again. An edit control will appear around the field name, allowing you to type a new name for the field.
To remove one or more fields from the database, select the fields in the Keyword-Database Map and click the Delete button.
To replace an existing field with a new keyword, select the new field in the Keywords list and the one to replace in the Keyword-Database Map list. Then, click the Replace button. The name of the field will not change, only the keyword used to evaluate the field.
If you need assistance understanding the dialog, click the Help button to display the on-line help.
When you have finished selecting information to store in the database, click the OK button to close the Edit Keyword Map dialog.
What files are created?
When you select keywords to store in a database, WinList creates three or four files on disk to manage the database. The files are created in the WinList application folder by default. However, you can choose another location by editing the database's properties, discussed below.
First, a file is created to store a "map" of keywords to database fields. The map file name uses the name of the database object and appends ".map" to it. For "Database1", the map file is named "Database1.map".
Next, the program creates or revises the actual database file. This is the tab-delimited, ASCII text file that you may open in other database or spreadsheet programs. The database file name uses the database object name and appends ".txt" to it. This file is readable in virtually any program that can open unformatted text. The first line of the file contains the names of the fields separated by tabs; it is known as the database header or definition. Each subsequent line contains a record of information.
If the database already exists on disk, WinList will automatically create a backup of the database before overwriting the existing one. The backup file will have the same name as the database, with " backup" appended to it.
Finally, the program creates a text file called a "key" file. This is a text file that explains the database and mapping files. You can open this file in a text editor to review the structure of the database you have created. Its name is based on the database object name, with "key.txt" appended to it.
How do you activate the database?
Once a database has been defined, there are several additional properties you can specify. These properties determine whether the database is active, whether it will prompt you before saving a record, whether or not you want to see the records in a database viewer, and where you want to store the database.
To edit these properties for a database, select the database in the Edit All Databases dialog box and click the Properties button. The Edit Properties for Database dialog will be displayed.
The properties are enabled or disabled with simple check boxes. Path selection is initiated by clicking the Database Path Folder button.
In order to store records of information in a database, it must be "active". To make a database active, check the Active checkbox in the Edit Properties dialog. Database records are saved when you click the Replay button on the ribbon bar, or when you click the Replay options in the Replay menu. Additionally, you can save a record at any time by choosing Save Current Results from the Edit menu, or by clicking the "+" button on the database viewer.
If the Prompting checkbox is checked, WinList will display a message each time it is about to save a record to the database. You can choose at that time whether or not you want to save the record. If Prompting is disabled, the database will save a record without prompting.
To view the database while you work with WinList, check the Viewer checkbox in the Edit Properties for Database dialog. A database viewer window will be created and displayed. The database viewer can be moved, resized, and scrolled horizontally or vertically. It has a toolbar that provides some additional manual database functions. See the topic Database Viewer for more information.
How do you rename or create additional databases?
It is useful to rename a database so that its name relates to its purpose. For example, if you have an activation study for which you have created a WinList protocol called "Activation", it makes sense to name the database "Activation" as well.
To rename a database, display the Edit All Database dialog box by selecting Edit Databases from the Edit menu. Click once to select the database you want to rename. After a brief pause, click again on the object to display an edit box in the Name column. Type the new name for the database.
The name you type must contain only alphabetic, numeric, or space characters, and must be at least 4 characters shorter than the maximum file name length for the operating system you are using. If a file with the new name already exists, you will be given a chance to overwrite the existing file, use the existing file, or cancel the operation.
When you want to create an additional database, select the first database in the Edit All Databases dialog and click the Copy button. This will create an identical database to the one copied, but will give the database a new name.
Each database has its own map of keywords to fields, and its properties determine whether it is active, prompting, and showing a viewer.
Making the databases open automatically when WinList starts
If you would like to open the database setup each time the program starts, enable the Auto-open check box.
Links: