Agilent ChemStore C/S. Concepts Guide

Transcription

1 Agilent ChemStore C/S Concepts Guide A

2 Notices Agilent Technologies, Inc. 2002, 2004 No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Agilent Technologies, Inc. as governed by United States and international copyright laws. Microsoft - Microsoft is a U.S. registered trademark of Microsoft Corporation. Manual Part Number G Edition 03/04 Printed in Germany Agilent Technologies Hewlett-Packard-Strasse Waldbronn, Germany Software Revision This handbook is for a module of the Agilent ChemStation Plus software. In the section In This Guide " on page 3 you will find details about the module and the revision of the module that this book is intended to be used for. Warranty The material contained in this document is provided as is, and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Agilent disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Agilent shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Agilent and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control. Technology Licenses The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license. Restricted Rights Legend If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as Commercial computer software as defined in DFAR (June 1995), or as a commercial item as defined in FAR 2.101(a) or as Restricted computer software as defined in FAR (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Agilent Technologies standard commercial license terms, and non-dod Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR (c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR (June 1987) or DFAR (b)(2) (November 1995), as applicable in any technical data. Safety Notices CAUTION A CAUTION notice denotes a hazard. It calls attention to an operating procedure, practice, or the like that, if not correctly performed or adhered to, could result in damage to the product or loss of important data. Do not proceed beyond a CAUTION notice until the indicated conditions are fully understood and met. WARNING A WARNING notice denotes a hazard. It calls attention to an operating procedure, practice, or the like that, if not correctly performed or adhered to, could result in personal injury or death. Do not proceed beyond a WARNING notice until the indicated conditions are fully understood and met. 2 Agilent ChemStore C/S Concepts Guide

3 In This Guide This book introduces you to the main concepts of Agilent ChemStore C/S revision B It highlights the main features of the product and gives you some guidance for setting up your studies and managing your data. It is organized as follows: 1 Introducing ChemStore C/S This chapter gives an overview of the Agilent ChemStore C/S functionality to help you to get started. Information for Operators If you are an Agilent ChemStore C/S operator, and want to learn about the operation of Agilent ChemStore C/S in detail, read Chapter 2, Chapter 3 and Chapter 4. 2 ChemStore C/S Concepts This chapter describes the main benefits and concepts of using the ChemStore C/S database in the analytical laboratory. 3 Using the Custom Calculator This chapter gives you an overview on creating and using calculation templates. 4 Using the Report Template Editor This chapter gives you an overview on creating and using report templates. Information for Administrators If you are an Agilent ChemStore C/S administrator, and want to learn about setting up Agilent ChemStore C/S to suit the needs of different laboratories and users, read Chapter 5 and Chapter 6. 5 Data Security This chapter describes the facilities that are available in ChemStore C/S for ensuring the security of the data in the database. Agilent ChemStore C/S Concepts Guide 3

4 6 Data Management This chapter describes how to manage the data inside your database using back-up, restore and archival. 7 ChemStore C/S Computations Agilent ChemStore C/S includes a comprehensive suite of statistical calculations. You will find full details of how these calculations are performed in this chapter. It describes statistical calculations, custom calculator commands and error codes, calculations using custom fields and the time computations done by ChemStore C/S. 4 Agilent ChemStore C/S Concepts Guide

5 Contents 1 Introducing ChemStore C/S 2 ChemStore C/S Concepts ChemStations and ChemStore C/S 12 A Brief ChemStore C/S Tour 13 ChemStore C/S Workflow 18 ChemStore C/S Data Flow 19 Organizing Results 20 Organizing Results into a Study 20 Using Custom Fields 21 Transferring Data from the ChemStation 23 Retrieving Data from the Database 24 Setting Up a Query 24 Filtering the Dataset 27 Reviewing and Approving Results 29 Run Approval Status 29 The Graphical User Interface 33 Sample View 36 Compound View 41 Configuring Tables 44 Intra-sample Calculations 45 Statistics 46 Generating Control Charts 47 User Interface Settings 48 Transferring Data to the ChemStation 50 Versioning 51 Deleting Runs from the Database 53 Agilent ChemStore C/S Concepts Guide 5

6 Contents 3 Using the Custom Calculator 4 Using the Report Template Editor What is the Custom Calculator? 56 Preparing to Use the Custom Calculator Script Editor 57 Retrieving the calculation data set 57 Understanding the Custom Calculator Script Editor Views 57 Custom Calculator Script Editor 60 Understanding the Custom Calculator Script Wizards 60 Example: Creation of a report calculation script 68 Using the Custom Calculator Script Editor 79 What is the Report Template Editor? 88 Preparing to Use the Report Template Editor 90 Retrieving the report data set 90 Understanding the Report Template Editor Tree Views 91 Using the Report Template Editor 93 Using Dialog Boxes to Create Report Sections 93 Using Tree Views for Tables and Charts 95 Understanding Report Template Components 96 Page Headers and Footers 96 Data Sections 97 Section Headers 100 Section Elements 100 Understanding Tables 106 Grouping and Summaries for Tables 106 Understanding Table Types 108 Generating a Report Using a Template 121 Using Automatic Reporting Agilent ChemStore C/S Concepts Guide

7 Contents 5 Data Security Introduction 124 Security 125 Setting Up and Managing Users 127 Setting Up Organizational Information 131 Setting Up and Managing Studies 131 Setting Up and Managing Custom Fields 132 Setting Up and Managing ChemStore C/S Elements 134 Archiving and Dearchiving 135 Automated Archiving 135 Archiving Interactively 139 Archive units 141 Deleting Runs 142 Reopening Runs 142 Dearchiving Runs 143 Generic XML Archive Interface 143 Understanding Archive Status 145 Reviewing Archive Status and Reports 147 Taking a Closer Look at the Archive/Dearchive Process 148 Managing Archiving and Dearchiving on Admin Client 151 Overview of the Archive/Delete Process 152 Performing Archive/Dearchive Tasks on Admin Client 153 Audit Trail 155 Notification 157 Database Logbook 160 Validation and Security of Printed Files 161 File Validation in Operation 161 File Validation Functions 162 Agilent ChemStore C/S Concepts Guide 7

8 Contents 6 Data Management 7 ChemStore C/S Computations Replacing the Built-in Security Scheme with a Customized Solution 162 Backing Up Your Database 166 Back Up or Archive? 167 Backing Up the Stand-Alone Version 168 Windows 2000/XP Backup 169 Automating and Scheduling Windows 2000/XP Backup 169 Tape Drives 169 CD-ROM 170 Backing Up the Client/Server Version 171 Oracle Back-up Types 171 Maintaining the ChemStation Computer 172 Cleaning up Left-Over Temporary Files 172 Maintaining the PC s File System 172 Continuous operation 173 Disaster Recovery Plan 175 Disk drive Failure 175 Power Failure 175 Database is corrupted 175 Statistical Calculations 178 Single Value Calculations 178 Regression Calculations 179 The Linear Regression Model 180 Matrix Solution of the Regression 180 Statistical and Related Values 181 Modifications for Weighted Linear Regression 182 Modifications for Non-Linear Functions Agilent ChemStore C/S Concepts Guide

9 Contents Index 205 Custom Calculator Commands 185 Error codes and descriptions 194 Calculations using custom fields 198 Original response factor 198 List of built in functions 199 Time computation 201 Time synchronization 201 Time stamps 201 Time zones 202 Setting Time zones on the PC 203 Agilent ChemStore C/S Concepts Guide 9

10 Contents 10 Agilent ChemStore C/S Concepts Guide

11 Agilent ChemStore C/S Concepts Guide 1 Introducing ChemStore C/S ChemStations and ChemStore C/S 12 A Brief ChemStore C/S Tour 13 Agilent Technologies 11

12 1 Introducing ChemStore C/S ChemStations and ChemStore C/S ChemStations and ChemStore C/S ChemStore C/S is a data evaluation and storage module for the ChemStation for LC, LC/MS, GC, CE, CE/MS or A/D systems. Based on standard database functionalities, ChemStore C/S adds data storage in and retrieval from a relational database, as well as cross-sample and cross-instrument review calculation and reporting facilities. After successful installation, and selection of the Connection to Database checkbox, ChemStore C/S adds functionality to the ChemStation. It prompts for a specific user log-in to the ChemStation and adds funtionality to the user interface to handle the transfer of analysis results into the database, reviewing data, transferring it back to the ChemStation for batch review and/or reprocessing and other functions. The ChemStore C/S client software user interface is installed as a separate application. It allows you to extract information from an ChemStore C/S database using queries, and to create cross-sample calculations, reports and charts. ChemStore C/S is available as a stand-alone product, operating on a single ChemStation, or as a client/server product. The stand-alone version uses an MS Access database installed on a single ChemStation. The client/server version uses an Oracle database installed on an MS Windows or Unix server. Both versions provide centralized storage of raw data and results along with the metadata (method and sequence files) used to create the results. In either case, the ChemStore C/S client software and the database communicate via a standard ODBC driver. The ChemStore C/S client software is the same for both configurations; the client/server version has additional facilities for archiving and de-archiving. Both versions track reprocessed runs, maintaining the current version and all previous versions in strict chronological order, and contain facilities for maintaining data integrity by linking the raw data to method and sequence information. 12 Agilent ChemStore C/S Concepts Guide

13 Introducing ChemStore C/S 1 A Brief ChemStore C/S Tour A Brief ChemStore C/S Tour ChemStore C/S is an add-on database module for your ChemStations for LC, LC/MS, GC, CE, CE/MS and A/D systems. It provides the following functionality: Organizing Data ChemStore C/S is designed to help you to organize your results flexibly and efficiently in a database. You can set up Studies in which you can collect all runs associated with a specific project. Studies can be restricted to certain users to facilitate data security and ease of use. In addition, ChemStore C/S gives you the ability to specify custom fields into which you can incorporate additional data and organizational information associated with the run and/or study. Transferring Results The ChemStore C/S software is tightly integrated with your ChemStation software. After you have analyzed your results, you can easily transfer information for a single run, sequence or batch automatically or interactively to ChemStore C/S. In addition to the results, the information transferred can include the chromatograms and spectra, actual raw data, method information and sequence information. Retrieving Data Sets Once you have collected data inside the database, you can retrieve the set of data you are interested in by using the Query Builder to easily specify search criteria. The Query Builder allows you to set up queries easily using a graphical interface rather than a complicated SQL (Structured Query Language) statement. To facilitate your work, you can also store queries for later re-use. Agilent ChemStore C/S Concepts Guide 13

14 1 Introducing ChemStore C/S A Brief ChemStore C/S Tour Once you have specified the subset you are interested in, (the query ), you can work on it in all further tasks: review and approval, cross-sample calculations, control charting, transfer to a ChemStation for additional batch processing, and reporting. You can also export the data to other applications (e.g. MS Excel) or a LIMSystem. Reviewing and Approving Data The on-line review of data retrieved using a query allows you to inspect a set of analysis results in context. Based on this condensed information, you can use the integrated approval and rejection functions or mark the runs for resubmitting to the ChemStation batch review for more detailed inspection and reprocessing. The approval function allows up to three electronic signatures per result version. Tracking the Changes An Audit Trail, maintained independently of the run data, keeps track of all the changes made to the run; you can display or print the Audit Trail and detailed information about the changes made for any run. Generating Control Charts To visualize trends in your selected result data, you can use the included control charts. You can view any combination of results in context, with overlaid charts if desired. You can also customize the charts to your own requirements. Execute customized calculations A built-in custom calculator offers you the possibility to define your own cross-sample calculations and statistics. The calculation is based on a calculation script that can be easily developed with the help of calculation script wizards. Versioning is used for storage of those scripts. They can be re-used for all similar data sets. Calculation results and graphics can be included into reports. 14 Agilent ChemStore C/S Concepts Guide

15 Introducing ChemStore C/S 1 A Brief ChemStore C/S Tour Generating Reports Once you have reviewed and approved your data, you will probably want to create a report. A button on the main toolbar allows you to quickly create a report using one of the standard report templates. Reports can be printed, or saved to a file in one of several formats. Customizing Reports If the standard report templates included with ChemStore C/S don t fully fit your requirements, you can easily modify them using the report template editor. You can also use the report template editor to create your own template designs. Essentially all data that are visible in ChemStore can be included in the report, as well as additional data defined by user-specified calculations. Exporting to Other Applications To process your data further, ChemStore C/S allows you to export information to MS Excel, or to print reports to a file in html, xml or csv format. You can also export the data to the Windows Clipboard for use in other Windows applications. Archiving and Dearchiving Runs The client/server version also allows you to copy data to an archive and, if appropriate, delete the archived runs from the database. Archived runs that are not deleted from the database are locked, and changes cannot be made to them unless they are reopened. Of course, archived runs that are deleted can also be dearchived and reopened. Archiving allows long-term storage of data separate from the server database. Limiting the number of active runs in the database is crucial for the database size and performance. You can archive interactively, on an ad hoc basis, or you can set up to archive automatically at regular intervals. You can use either the internal ChemStore archive utility or a third-party archiving tool based on XML technology. A generic XML archiving utility is available on the installation CD. For further details contact your Agilent Technologies representative. Agilent ChemStore C/S Concepts Guide 15

16 1 Introducing ChemStore C/S A Brief ChemStore C/S Tour Data Protection and Integrity To prevent unauthorized access to the database or tampering with results, each ChemStore C/S user is given an access password and a set of permissions that define which facilities are available for that user. Only the Administrator, or other user with the requisite permissions, can change a user s permissions. If unauthorized access leads to the locking of an account, ChemStore can be set up to notify all affected users by . Associated with each run in the database is an Audit Trail, which contains a log of all changes that are made to the run. In addition, a built-in versioning facility ensures that injections that are reprocessed multiple times are maintained in ChemStore C/S as a set and can be retrieved in strict chronological order. You can choose to retrieve all versions (that is, the complete set of reprocessed results) or only the latest; if you retrieve all versions, you can choose to restrict the display to only the latest. The existence of more than one version of the run in the database is denoted by an asterisk in the run table. In addition, all database interactions that affect security are logged in a database logbook, which, if you are permitted the relevant access level, you can display. Scalability The database grows as your requirements grow. You can start with an MS Access based stand-alone system and upgrade to the Oracle based client/server version as you add further systems. A suite of utilities enables you to manage the migration of your stand-alone databases to the client/server version, which gives you the additional advantages of archiving and de-archiving your data, as well as allowing for much larger database sizes. The system grows with your requirements for the organization and reporting of your results, while you preserve your investment in data and training during the process, because the basic user interface does not change. 16 Agilent ChemStore C/S Concepts Guide

17 Agilent ChemStore C/S Concepts Guide 2 ChemStore C/S Concepts ChemStore C/S Workflow 18 ChemStore C/S Data Flow 19 Organizing Results 20 Transferring Data from the ChemStation 23 Retrieving Data from the Database 24 Reviewing and Approving Results 29 The Graphical User Interface 33 Transferring Data to the ChemStation 50 Versioning 51 Deleting Runs from the Database 53 Agilent Technologies 17

18 2 ChemStore C/S Concepts ChemStore C/S Workflow ChemStore C/S Workflow Chemstore C/S ChemStation Create a Study Set up Sequence Specify Custom Fields Assign Study and Custom Field Set up Query Run data transferred Sample View Review Compound view Data Statistics Reprocess Runs Reject Runs Accept Runs Mark Runs for Batch Batch transferred Load ChemStore Batch Define Report Define Chart Print Report Print Chart Figure 1 Typical workflow for the operation of ChemStore C/S 18 Agilent ChemStore C/S Concepts Guide

19 ChemStore C/S Concepts 2 ChemStore C/S Data Flow ChemStore C/S Data Flow ChemStation Spooler Run data from the ChemStation and custom field values for the injection Runs for batch reprocessing Database Approval Status Query ChemStore C/S Current data set Filter View Figure 2 Data flow in ChemStore C/S Agilent ChemStore C/S Concepts Guide 19

20 2 ChemStore C/S Concepts Organizing Results Organizing Results The central organizational entity in ChemStore C/S is the run. A run is defined as the set of results that is obtained when a data analysis method is applied to the raw data resulting from a single injection. When a run is inserted into the ChemStore C/S database, all the available associated information about the injection, the sample etc. is also entered. This is the only method available for inserting data into the database. Organizing Results into a Study Within the ChemStore C/S database, runs can be logically grouped for any desired purpose. For example, it may be appropriate to collect together all the analytical results related to a clinical trial or a stability study. Such a group of runs is referred to as a Study; a user with the requisite permissions (see Security on page 125), may define as many studies as desired, but each study must be identified with a unique name. When results are transferred from the ChemStation to ChemStore C/S, the individual runs (or groups of runs) are assigned to a study; these runs, together with any previous runs assigned to the same study, are then available as a logical unit. You can elect to store additional data along with the result data, for example the chromatogram and/or spectra. You can also optionally store the raw, unprocessed data, the method file and the sequence file, thus ensuring the maintenance of complete data integrity. To help in the organization and reporting of results, you can associate a set of custom fields (see Using Custom Fields on page 21) with the study. These custom fields may be either specific to the study, or they may be used by other studies. Any new custom fields that you specify when you set up the study are automatically available for use in other studies. When you set up a study that uses a custom field, you must specify how the data for the custom field will be entered. You can choose to enter the data automatically (by a ChemStation macro) or manually. If you choose to enter the data manually, you can specify whether input of a value is always required; if not, you can specify a default value. If you specify that a value is 20 Agilent ChemStore C/S Concepts Guide

21 ChemStore C/S Concepts 2 Organizing Results always required, a valid value must be entered in the field before the transfer of the analysis results to ChemStore C/S is allowed. In addition, you can specify certain characteristics for some field types (maximum and minimum values for numeric fields, maximum string lengths for text fields). The data entry characteristics are specific to the study; if the custom field is used in other studies, its data entry characteristics may be different. Studies are restricted to a list of assigned users. Only users who have been assigned to work on a study may add or access data for that study. This allows multiple teams to use the same database while being assured that their study data is secure from others who are not authorized to work with their data. Restricting study access also makes the product easier to use because the user only sees data from studies that they are assigned to access. Assignment of studies to users can only be performed by an administrator or other user with the proper ChemStore permission. Using Custom Fields In addition to the data normally associated with the analytical results, and provided by the ChemStation, external data can be appended to the database record. Such data are added in the form of Custom Fields, which are user-defined fields containing information of any kind. You can use such custom fields to organize your result data by defining the custom fields to match the kind of analyses you normally perform. For a preclinical study for example, you may want to set up fields to add information to each set of results about the ph value Patient s Name Patient s Age Non-Smoker Date of Testing Patient s Gender Dosage Applied etc. You can then use these data to retrieve a specific set of analysis results, for example all results for a certain patient. Agilent ChemStore C/S Concepts Guide 21

22 2 ChemStore C/S Concepts Organizing Results Custom fields are of six types: True/False Selection list Integer Real Text Date/Time The field can have the values true or false only, for example Non-Smoker would have the values True or False. The value is restricted to a specific value from a user-defined list, for Patient s Gender would offer the values Male or Female. The field can have an integer value only, for example Patient s Age would generally be given as an integer. The field can contain any numeric value, for example Dosage Applied might be a non-integer amount. The field can contain text only, for example the Patient s Name. The field can contain date and time information only, for example the Date of Testing. Organizing information in a database is helpful not just for retaining analysis results, with centralized storage, but also for flexible creation of cross-sample and/or cross-instrument reports, calculations and trend analyses on a set of results. Following the example structure outlined above, you could for example compare results for a certain doses and generate a control chart that displayed the concentration of the active component found. Custom fields are available on a database-wide basis so that any defined custom field can be appended to a study. Custom fields can have the status active or inactive; setting the status of a custom field to inactive does not affect studies that are configured to use that custom field, but makes the field unavailable for inclusion in any additional studies. Custom fields used in a study may be configured as always required. You must enter valid values in such fields before the transfer of the analysis results to ChemStore C/S is allowed. Custom fields are protected by user permissions and passwords (see Security on page 125). Only users with the requisite permission may create or modify custom fields, and changes need to be confirmed by electronic signature. 22 Agilent ChemStore C/S Concepts Guide

23 Transferring Data from the ChemStation ChemStore C/S Concepts 2 Transferring Data from the ChemStation Analysis results can be transferred from the ChemStation to ChemStore C/S either interactively or automatically as part of a sequence, in a batch or as single samples. After the run, the data are transferred through a spooler into the database; the spooler operates as a background process so that the ChemStation can continue to run. This process ensures that the ChemStation is not slowed by the transfer process, and guards against data loss if the insertion of the data into the database fails. Interactive data transfer is done from the Data Analysis view of the ChemStation, either in single data file mode, by reprocessing a sequence or in Batch Review. You can transfer the current data file into any active study which is assigned to you. You provide the necessary custom field values at the time of transfer. You may also change the default values of those custom fields that were given default values at setup. Automatic data transfer is done either from a sequence or from a batch. Each run in the sequence or batch is assigned to a study (you may use multiple studies and assign each run to a different study), and you provide the values for the custom fields associated with the study during sequence set-up or batch processing. NOTE For either interactive or automatic data transfer, you must provide values for those custom fields specified as always required before the transfer of data can take place. These fields headers are marked with an asterisk. Any data that has been selected to be saved along with the results (chromatograms, spectra or raw data, method and sequence files) are transferred along with the analysis results. Agilent ChemStore C/S Concepts Guide 23

24 2 ChemStore C/S Concepts Retrieving Data from the Database Retrieving Data from the Database Runs are retrieved from the ChemStore C/S database using a Query (see Setting Up a Query on page 24). A query is a request to retrieve a set of runs from the many thousands of runs that comprise your database that matches certain criteria, for example by asking the question Which samples contain Procaine? The more exactly you can specify the criteria, the smaller will be the set of runs retrieved. Prior to retrieving the set of runs, ChemStore C/S confirms the number of runs to be retrieved using the current query criteria. The data that comply with the criteria defined in the query are gathered together and copied to the local ChemStore C/S as a dataset a snapshot of the data that you want to review (see Figure 2 on page 19). The way that the runs within the database are organized, and the information that is stored with each run, can greatly increase the efficiency of retrieval of data. Runs assigned to studies designed to match the pattern of work of the laboratory can help to optimize retrieval of analysis results. This is aided by defining a well-structured set of custom fields that best reflect your data search requirements. For example, if you normally group results by test participant, you can define Test Participant as custom field. The custom fields can then be searched along with the standard search criteria, such as operator name and instrument name, which are by default stored in the database. Setting Up a Query ChemStore C/S provides two levels of query: Simple and Advanced. Both levels are set up using a graphical constructor that helps you to define your search criteria easily and without the requirement to learn SQL (structured query language), the standardized language used to specify search criteria in relational databases. The graphical editor allows you to select the data categories you are interested in and either choose pre-existing data items or enter values manually. A study selection is offered to limit the number of existing data items presented in the dialog. The simplest query uses a single item from one category of information, for example Find the samples from 24 Agilent ChemStore C/S Concepts Guide

25 ChemStore C/S Concepts 2 Retrieving Data from the Database the Study called Beta1, where Study is the data category and Beta1 is the item. If the simplest query does not produce the runs you require, you can extend the query criteria by using either multiple items or multiple data categories. If you select multiple items within one data category, they are combined in the Simple query with an OR (for example Find the samples from Study Beta1 OR Beta2 ). If you select multiple data categories, they are combined in the Simple query with an AND (for example Find the samples which contain Procaine AND which are control samples ). The Advanced query extends the query specification with the use of other logical operators (OR, NOT) and the specification of ranges of values (for example Find the samples which contain Procaine AND which are NOT control samples ). Select all or latest version of data Graphical constructor allows you to select data categories to search Restricts the view of data items below Possible values of the selected data item Query specification built up using graphical constructor Figure 3 The Query Builder ChemStore C/S offers two forms of query builder: The Simple form (shown in Figure 3) allows you to build up the query by selecting data items and values using the graphical interface. Multiple criteria are ANDed: runs are retrieved that match all of the conditions. The Advanced form uses the same graphical interface but adds the facility to extend the criteria using absolute and relative Where clauses, the OR operator and negation. The Where clauses available depend on the data type, as shown in Figure 1 on page 18. Agilent ChemStore C/S Concepts Guide 25

26 2 ChemStore C/S Concepts Retrieving Data from the Database Table 1 Where Clauses in the Advanced Query Builder Numeric Date/Time Text Selection List is equal Yes Yes Yes Yes is greater than Yes Yes is less than Yes Yes is between Yes Yes contains Yes relative clause not older than currently logged on user, current computer, The NOT operator negates the condition: is not equal, is not greater than, is not less than, is not between and does not contain. Once the query has been specified, the set of data that is retrieved is available for all subsequent tasks: on-screen review and approval customized calculations generation of control charts generation of reports Because it is likely that you will want to use queries multiple times to retrieve the same dataset, they can be saved and re-run at a later date. Queries form part of the ChemStore C/S Settings that can be shared between nominated users. Once a query has been specified and saved, it can be assigned to other users in addition to the owner. Queries are also protected from misuse by user permissions (see Security on page 125); only users with the necessary permissions can save queries or assign saved queries to other users. 26 Agilent ChemStore C/S Concepts Guide

27 ChemStore C/S Concepts 2 Retrieving Data from the Database Filtering the Dataset Often, the dataset that has been retrieved by a query contains runs that are not required to produce a specific control chart or report. In such cases, a filter can be used to filter out only those runs that are required, and hide information that is not required. For example, a query may return 50 samples that were run by two different operators; you can then apply a filter that displays the results from only one operator at a time. The filter operates only on the current dataset, not on the complete database, but it does not change the contents of the dataset. The application of a filter also speeds up the work time. Two filters are available: a custom filter can be specified using a graphical constructor in a similar way to the query, and can be used to filter the dataset using query-type search criteria (see Figure 4). The search criteria available are the configured columns of the results table. the Standard filter contains a set of predefined filters that have been selected to reflect the most frequently-used criteria. The criteria available are approval status, archive status and run version, see Figure 5 on page 28. The run version filter is useful when you have chosen to retrieve all versions of a run, but want to review only the latest version. If both the standard filter and a custom filter are applied at the same time, the criteria are combined with an AND operator. Available data categories from which to select List of values in the selected data category Filter condition Figure 4 The Custom Filter Graphical Constructor Agilent ChemStore C/S Concepts Guide 27

28 2 ChemStore C/S Concepts Retrieving Data from the Database Figure 5 The Standard Filter Selection Items The filters are available in two states: The Filter state displays only those runs that match the filter conditions; runs that do not match the filter conditions are hidden. The Complement Filter state displays only those runs that do not match the filter conditions; runs that match the filter conditions are hidden. Both filter states are set up in exactly the same way, and can be switched on and off. You can toggle between the Filter and Complement Filter to show the two complementary sets of runs that make up the dataset. Like queries, custom filters form part of the ChemStore C/S Settings that can be shared between nominated users. Once a custom filter has been specified and saved, it can be assigned to other users in addition to the owner. Custom filters are also protected from misuse by user permissions (see Security on page 125); only users with the necessary permissions can save a custom filter specification or assign a custom filter to other users. 28 Agilent ChemStore C/S Concepts Guide

29 ChemStore C/S Concepts 2 Reviewing and Approving Results Reviewing and Approving Results ChemStore C/S is designed for reviewing analysis results in context. The batch review function of the ChemStation is an ideal vehicle for review and transfer of data from the ChemStation to the ChemStore C/S database. Once the results are in the database, you can consolidate and review them in context. Having retrieved the data you are interested in by using a query, and, if necessary, filtered out a sub-set of the retrieved dataset, you can display the remaining results organized by either sample (sample review) or compound (compound review). Run Approval Status When a run is transferred from the ChemStation to ChemStore C/S, it is given the approval status Approval Pending. Depending on the study configuration, all runs of this study might electronically approved and signed by one or multiple 1st level reviewers and one or two 2nd level reviewers. The approval can also be denied by the "Reject" option. A rejection submitted by one user overrules the approval of other reviewers. User permissions for the 1st and 2nd approval level (see Security on page 125) can be assigned individually. The two 2nd level approvals are equivalent in respect to the execution order. A 2nd level approval can also be applied for runs with no 1 st level approval. A user with the requisite permissions can either approve or reject individual runs or complete sets of runs. The process of approval or rejection is divided in two steps, as outlined in Figure 6 on page 30. Agilent ChemStore C/S Concepts Guide 29

30 2 ChemStore C/S Concepts Reviewing and Approving Results Figure 6 Mark runs for approval Step 1 Step 2 is marking the runs for approval or rejection during the result review. is actually applying the electronic signature and approval/rejection comment to individual or all runs marked in step 1. To harmonize the approval comments, administrators can pre-define a set of standard comments in the Approval configuration menu (Figure 7 on page 31). However, the user can still add a new comment or modify or extend the pre-defined comments during the approval process. 30 Agilent ChemStore C/S Concepts Guide

31 ChemStore C/S Concepts 2 Reviewing and Approving Results Figure 7 Approval Comments configuration dialog Each action of step 2 is documented in the audit trail (see Figure Audit Trail on page 156) with the time of the action, the status of the run, the operator name and a comment, supplied or selected by the operator. The change of the approval status is confirmed as '1 st level approved', '2 nd level approved' or 'Rejected'. An approved run can be later rejected, and vice versa, and each of these actions, as for approval and rejection, invokes a request for a reason for the change in status. The change in status also generates an entry in the audit trail. The runs can also be automatically locked when a specified approval status is reached. Locking a run prevents further batch reprocessing of this run. To undo the locking, the approval needs to be rejected. Agilent ChemStore C/S Concepts Guide 31

32 2 ChemStore C/S Concepts Reviewing and Approving Results If modifications are made to the custom field values of an approved run, its approval status is reset to Approval Pending; in the client/server version, a run that is reopened is automatically given the Approval Pending approval status. change or reopen user Approved Approval Pending user user user change or reopen Rejected Figure 8 Run Approval Status Transitions 32 Agilent ChemStore C/S Concepts Guide

33 ChemStore C/S Concepts 2 The Graphical User Interface The Graphical User Interface The ChemStore C/S window is divided into four areas (see Figure 9 on page 36 and Figure 10 on page 41): the main toolbar the second toolbar the left panel of the display the right panel of the display The user interface settings, including the settings of all user-configurable elements, can be saved and later recalled (see User Interface Settings on page 48). The Main Toolbar The main toolbar is situated below the menu bar across the top of the ChemStore C/S window. It contains the tools that allow you to set up queries and filters, to switch views and layouts and to set up and print reports. All activities supported by the tools in all toolbars are also available from menu items. The following tools are available in all modes: Switches to the Sample View or Compound View, which you use to review, approve or reject, and mark runs for batch processing. Switches to the Delete View in the stand-alone version or the Archive/Delete View in the client/server version, which you use to mark runs for archiving and/or deletion. This button is absent if the current user does not have archive/delete permission. This tool appears twice. In the custom calculator context as well as in the report context. It displays a pop-up menu from which you can select to create a new calculation or report template, edit an existing calculation or report template or manage your calculation or report templates. Agilent ChemStore C/S Concepts Guide 33

34 2 ChemStore C/S Concepts The Graphical User Interface Displays a preview of the current calculation results using the currently selected calculation template. Displays a preview of the current report using the currently-selected report template. Prints a report of the current results using the currently-selected report template on the currently-selected printer. Displays a pop-up menu from which you can save the current user interface settings for later recall, manage previously-saved user interface settings or select a previously-saved user interface setting. The two tabs, Sample and Compound, switch between Sample View and Compound View. Each layout includes a second toolbar, the format of which is dependent on the layout selected (see Sample View on page 36 and Compound View on page 41). The following tools are available in the Sample View: Switches to the Sample Review layout Switches to the Sample Table layout Switches to the Sample Chart layout When Regression Statistics are selected in the Sample View, two additional tools are available: Displays the Regression Results table and calculated statistics Displays the Regression Residuals chart 34 Agilent ChemStore C/S Concepts Guide

35 ChemStore C/S Concepts 2 The Graphical User Interface The following tools are available in the Compound View Switches to the Compound Review layout Switches to the Compound Table layout Switches to the Compound Chart layout When Regression Statistics are selected in the Compound View, two additional tools are available: Displays the Regression Results table and calculated statistics Displays the Regression Residuals chart Agilent ChemStore C/S Concepts Guide 35

36 2 ChemStore C/S Concepts The Graphical User Interface Sample View Second toolbar Main toolbar Chromatogram of selected run Run list Summary sample table Figure 9 Sample Review Layout Sample View displays the retrieved runs based on sample information. It offers three layouts, which give different information on the current dataset: The Sample Review layout is a three-panel layout with the Run List in the left panel, the Chromatogram window in the upper part of the right panel and the Summary Sample table in the lower part of the right panel (see Figure 9 on page 36). The Sample Table layout is a two-panel layout with the Run List in the left panel and the Sample table in the right panel. The Sample Chart layout is a two-panel layout with the Run List in the left panel and the Sample chart in the right panel. In addition, Sample View can show two different sets of statistical results: Summary Statistics splits the right panel of the Sample Table layout and shows the Sample table in the upper part of the panel and the Summary Statistics results in the lower part of the panel. Regression statistics makes two layouts available: 36 Agilent ChemStore C/S Concepts Guide

37 ChemStore C/S Concepts 2 The Graphical User Interface The Regression Results layout is a three-panel layout with the Run List in the left panel, the Regression Results table in the upper part of the right panel and the calculated regression statistics in the lower part of the right panel. The regression Residuals layout is a two-panel layout with the Run List in the left panel and the Residuals chart in the right panel. The Second Toolbar in Sample View The tools that are available in the second toolbar in Sample View depend on the layout selected. The following tools are available in all Sample View layouts: Allows you to set the approval status of all runs marked for approval to Approved. Allows you to set the approval status of all runs marked for rejection to Rejected. Allows you to set up one or more batches for the runs marked for batch reprocessing. Displays the sample-related information about the current run, including the sample-related processing parameters. Displays the run- and data analysis-related information about the current run. Displays the Audit Trail for all versions of the current injection. Displays the ChemStation method parameters for the selected run. It is only active for run versions transferred to ChemStore revision B or higher. Displays the table column selection dialog box to allow you to select the columns to include in the Sample table. Agilent ChemStore C/S Concepts Guide 37

38 2 ChemStore C/S Concepts The Graphical User Interface Displays a menu that allows you to switch between the normal custom filter and the complement filter. Toggles the state of the current normal custom filter, on or off. Toggles the state of the current complement filter, on or off. Enables you to export data either to the Windows Clipboard or to a file in Microsoft Excel format. Enables you to print one or more sections of the current view to the currently-selected printer. Sample Review layout adds one tool to the general tool set: Starts an automatic stepping through the runs. Choose the Stop button, which replaces the Start button to stop the automatic stepping through. You can configure the time interval for the automatic stepping through. Sample Table layout adds two tools to the general tool set: Sorts the results in alphanumeric or date/time order of the selected column of the Sample Table. Sorts the results in reverse alphanumeric or date/time order of the selected column of the Sample Table. Sample Chart layout adds one tool to the general tool set: Enables you to specify the chart options. 38 Agilent ChemStore C/S Concepts Guide

39 ChemStore C/S Concepts 2 The Graphical User Interface Regression Statistics adds one tool to the above tool sets: Enables you to set up the parameters for the calculation of regression statistics and residuals. Run List The Run List (see Figure 9 on page 36) is a table containing information about all the runs in the current dataset. The table contains five columns: Run shows the number of the run in the dataset Mark run for shows how you have marked the run: P indicates that the run has been marked for approval R indicates that the run has been marked for rejection B indicates that the run has been marked for inclusion in a batch to be reprocessed in the ChemStation EXC indicates that the run has been excluded from reports and statistical calculations Sample name shows the sample name Audit shows if a run has already been reprocessed: If only the latest version of a run has been retrieved, an asterisk denotes that there are multiple versions. If all versions have been retrieved, they are numbered in sequence, 1 being the earliest version; + denotes the latest version. Displays the ChemStation method parameters for the selected run. It is only active for run versions transferred to ChemStore revision B or higher. Status shows the current status of the run (approval status in data review, archive status in the archive/delete view). Use the checkboxes at the bottom of the panel to mark runs for approval, rejection or batch processing, or use the right mouse button and select from the pop-up menu. Marking the runs does not change the approval status of the runs (see Run Approval Status on page 29), or transfer the runs to a batch. The approval status of the runs is changed only when the appropriate tool is used (the Approve tool sets the approval status of the runs marked for approval to Approved; the Reject tool sets the approval status of the runs marked for rejection to Rejected) and the batch is set up only when the Batch Agilent ChemStore C/S Concepts Guide 39

40 2 ChemStore C/S Concepts The Graphical User Interface Processing tool is used. If you approve or reject a run, you must supply a reason for the change in status; this information, together with the change in status, is entered in the Audit Trail for the run, together with the change of status. Summary Sample Table The Summary Sample Table contains information about each peak in the run selected in the run list. You can configure the Summary Sample Table and select the information that is displayed (see Configuring Tables on page 44). You can use the Next and Previous buttons below the table to manually step through the runs, The Exclude button marks the run as Excluded and removes the run from the right panel of the sample review; you can remove the exclusion mark using the Include button. Sample Table The Sample Table of the Table Layout view contains information about each run in the run list. You can configure the Sample Table and select the information that is displayed (see Configuring Tables on page 44). Typically that view is used to display the equivalent to the sequence table in a sequence oriented workflow. 40 Agilent ChemStore C/S Concepts Guide

41 ChemStore C/S Concepts 2 The Graphical User Interface Compound View Main toolbar Second toolbar Compound list Chromatogram of selected run Spectrum of selected compound Summary results table Figure 10 Compound Review Layout Compound View displays the retrieved runs based on compound information. Like Sample View, it offers three layouts, which give different information on the current dataset: Compound Review layout is a four-panel layout with the Compound List in the left panel, the Chromatogram window at the left of the upper part of the right panel, the Spectrum window at the right of the upper part of the right panel and the Summary Results table in the lower part of the right panel (see Figure 10 on page 41). Compound Table layout is a two-panel layout with the Compound List in the left panel and the Results table in the right panel. Compound Chart layout is a two-panel layout with the Compound List in the left panel and the Compound chart in the right panel. In addition, Compound View can show two different sets of statistical results: Summary Statistics splits the right panel of the Compound Table layout and shows the Results table in the upper part of the panel and the Summary Statistics results in the lower part of the panel. Agilent ChemStore C/S Concepts Guide 41

42 2 ChemStore C/S Concepts The Graphical User Interface Regression statistics makes two layouts available: Regression Results layout is a three-panel layout with the Compound List in the left panel, the Regression Results table in the upper part of the right panel and the calculated regression statistics in the lower part of the right panel. Regression Residuals layout is a two-panel layout with the Compound List in the left panel and the Residuals chart in the right panel. The Second Toolbar in Compound View The tools that are available in the second toolbar in Compound View depend on the layout selected. The following tools are available in all Compound View layouts: Displays the table column selection dialog box to allow you to select the columns to include in the Results table. Displays a menu that allows you to switch between the normal custom filter and the complement filter. Toggles the state of the current custom filter on or off. Toggles the state of the current complement filter, on or off. NOTE The data that are available for the filter are only based on sample related data. Enables you to export data either to the Windows Clipboard or to a file in Microsoft Excel format. Enables you to print one or more sections of the current view to the currently-selected printer. Compound Review layout adds five tools to the general tool set: 42 Agilent ChemStore C/S Concepts Guide

43 ChemStore C/S Concepts 2 The Graphical User Interface Allows you to set the approval status of all runs marked for approval to Approved. Allows you to set the approval status of all runs marked for rejection to Rejected. Allows you to set up one or more batches for the runs marked for batch reprocessing. Displays the peak-related information about the current compound. Starts an automatic stepping through the runs. Choose the Stop button, which replaces the Start button to stop the automatic stepping through. You can configure the time interval for the automatic stepping through. Compound Table layout adds two tools to the general tool set: Sorts the results in alphanumeric or time/date order of the selected column of the Results Table. Sorts the results in reverse alphanumeric or time/date order of the selected column of the Results Table. Compound Chart layout adds one tool to the general tool set: Enables you to specify the chart options. Regression Statistics adds one tool to the above tool sets: Enables you to set up the parameters for the calculation of regression statistics and residuals. Agilent ChemStore C/S Concepts Guide 43

44 2 ChemStore C/S Concepts The Graphical User Interface Compound List The Compound List (see Figure 10 on page 41) contains a list of all compounds (analytes) in the current dataset. Calibrated compounds are reported with their name, non-calibrated compounds are reported as Uncalibrated Compounds. You select the compound to display from the list. In Compound Review layout, you can select only one compound, but in Compound Table layout, an additional column allows you to select multiple compounds to display. In Compound Chart layout, you can chart multiple parameters of a single compound or single parameters of multiple compounds. If you chart multiple parameters of a single compound, the plots are normalized to the largest value in the dataset. Summary Results Table The Summary Results Table shows the information for the selected compound in each run. You can configure the Summary Results Table and select the information that is displayed (see Configuring Tables on page 44). Use the checkboxes below the table to mark runs for approval, rejection or batch processing. Marking the runs does not change the approval status of the runs (see Run Approval Status on page 29), or transfer the runs to a batch. The approval status of the runs is changed only when the appropriate tool is used (the Approve tool sets the approval status of the runs marked for approval to Approved; the Reject tool sets the approval status of the runs marked for rejection to Rejected) and the batch is set up only when the Batch Processing tool is used. Results Table The Results Table shows the information for all the selected compounds in each run. You can configure the Results Table and select the information that is displayed (see Configuring Tables on page 44). You can use the Results table to select the X- and Y-axis enumerators for your charts (see Figure 11 on page 45). Configuring Tables You can configure all tables that are displayed in the right panel of the ChemStore C/S window. Using a dialog box, you can select the columns that constitute each table, and their sequence in the table. For numeric columns 44 Agilent ChemStore C/S Concepts Guide

45 ChemStore C/S Concepts 2 The Graphical User Interface and rows of the statistic results, you can also select the number format and precision; for date columns, you can also select the display style. The configuration dialog box contains only those columns that are valid for the table you are configuring. During column configuration, you can also select the enumerators for the X- and Y-axes of your charts using the checkboxes in the column configuration dialog box. X- and Y-axis enumerators may be selected only from columns that are included in the table. You may choose only one X-axis enumerator, but as many Y-axis enumerators as you wish. Figure 11 Column configuration dialog In addition to the standard results that are available from the ChemStation, you can also define columns that are the results of arithmetical calculations using the data available in the configured table. Intra-sample Calculations In your results tables, you can configure a column that contains a mathematical expression to perform a simple intra-sample calculation, for example a sum or a ratio, on the results for each run or compound. These intra-sample relate to the run or peak in the row of the table. For calculations covering a cross-sample and enhanced intra-sample (relating to a column in the table) see Statistics on page 46 and Preparing to Use the Custom Calculator Script Editor on page 57 Agilent ChemStore C/S Concepts Guide 45

46 2 ChemStore C/S Concepts The Graphical User Interface In your custom calculations, you can use any of the data items from the table; the mathematical expression can include arithmetical operators and mathematical functions as well as numerical constants. Statistics ChemStore C/S provides three levels of statistics: Summary Statistics are displayed below the Sample Table in Sample Review or the Results Table in Compound Review. Regression Statistics are displayed in two separate layouts: Regression Results Table layout and Residuals Chart layout. If statistic results needs to be used for further calculations the summary and regression statistics can also be calculated by the custom calculator. See Example: Creation of a report calculation script on page 68. Summary Statistics Summary statistics are calculated and displayed for each column in the Sample Table or Results Table. The statistics that are displayed are: Count Max Mean Min RSD Std. Dev Sum Variance Number of values in the data set Maximum value in the data set Mean value of the data set Minimum value in the data set Relative standard deviation of the values in the data set Standard deviation of the values in the data set Sum of the values in the data set Variance of the values in the data set For details of the calculations used in Summary Statistics, see Statistical Calculations on page 178. Regression Statistics For details of the calculations used in Regression Statistics, see Regression Calculations on page Agilent ChemStore C/S Concepts Guide

47 ChemStore C/S Concepts 2 The Graphical User Interface Generating Control Charts You can generate charts from the results you choose to include in the Sample Table (Sample Review) or the Results Table (Compound View). The X- and Y-axis enumerators that you chose when you set up the table are transferred to the chart. However, you can use the buttons on the X-and Y-axes to change the selections, for example to simplify the chart. Using the Chart Options dialog box, available either from the options menu or from the toolbar, you can format the color, style and shape of the lines and points for each of the lines on your chart. You can also format the style, size and position of the title, axis labels and chart legend. By default, charts are displayed with automatic scaling of the axes: the X-axis is scaled from the minimum to maximum value of the X-axis enumerator range, the Y-axis is scaled from the minimum to maximum value of the set of Y-axis enumerators. You may change the scaling by setting maximum and minimum values, and you may also specify the precision of the axis scaling values. You may also choose to display the data on logarithmic axes, in which case the precision settings have no effect. You cannot display time enumerators in logarithmic form. Data points less than or equal to zero are not shown on logarithmic plots. Adding Limit Lines In addition to plotting your results, you can add up to five limit lines to your charts: center line, upper and lower warning limits and upper and lower critical limits. To set the positions of these lines on the Y-axis, you can use either calculated values (mean and standard deviation) or specified values: Center Line Limit Lines Can be based on either the mean value of one of the Y-axis enumerators, or set to a specified value. Can be specified values, or set to a specified difference from the center line. The specified difference can be an absolute value or based on the standard deviation of the selected Y-axis enumerator. Agilent ChemStore C/S Concepts Guide 47

48 2 ChemStore C/S Concepts The Graphical User Interface User Interface Settings When you have reviewed your data, and set up tables, control charts and statistics options, you can save these user interface settings and recall them for later reuse (see Figure 12). The information that is saved includes not only the configuration and format of configurable tables and charts, but also the widths of columns in non-configurable tables (for example the run list and compound list) and the sizes of the panels in each of the layouts. The user interface settings are saved with a name, and are available for you to use again at a later date; a person with the user permission to manage user interface settings, can also allocate the saved settings to other users for their use. 48 Agilent ChemStore C/S Concepts Guide

49 ChemStore C/S Concepts 2 The Graphical User Interface Column widths of all tables in all layouts Line and point style and color, axis labelling, legend and title on all charts Panel sizes in all layouts Number format and precision in results tables Figure 12 Configurable Settings of the User Interface Agilent ChemStore C/S Concepts Guide 49

50 2 ChemStore C/S Concepts Transferring Data to the ChemStation Transferring Data to the ChemStation Transfer of data from ChemStore C/S to the ChemStation takes place in two stages. The first stage occurs during the review process in ChemStore C/S, when you select those runs to be transferred back to the ChemStation for reprocessing or re-analysis. The addition of a run to a batch request generates an entry in the audit trail for that run. When you have selected all relevant runs, they are transferred into one or more batches, together with all associated information (study name, custom field values and attributes). Before the runs are transferred, the system looks for identical files in the original location; if the files already exist, and they are identical, no transfer is made. If the files do not exist in the original location, and they are available in the database, they are transferred to the ChemStation in a separate, temporary storage area. The second stage occurs in the ChemStation when you choose to load a ChemStore C/S batch into the ChemStation s batch review function. If more than one batch has been set up in ChemStore C/S, you select the batch to load from a list of pending batches. Only those batches that have been assigned to the current ChemStation user, or to all users, are shown in the list. You can also choose to reload any or all files saved with a run or a complete sequence interactively from the run information interface (raw data, method or sequence files). In this case, if the files already exist in the ChemStation, you are prompted change the destination path or cancel the transfer. Reprocessed runs that are transferred to ChemStore C/S are stored in the database as new runs; they do not overwrite the original results. The original results are retained in the database, and are optionally retrieved (if they fit the search criteria). You can use the standard filter to display all versions (the latest version plus all previous versions), or to display only the latest version. 50 Agilent ChemStore C/S Concepts Guide

51 ChemStore C/S Concepts 2 Versioning Versioning ChemStore C/S retains all previous versions of files that are reprocessed by the ChemStation. If you choose to store raw data, method and sequence files with the data, only those files that have been changed are stored with the new version, i.e. the raw data file is stored only once, the method file is stored only if the method has been modified and the sequence file is stored only if the run is transferred in a sequence, and not if the run is transferred in a batch or manually. When you set up a query, you can choose to retrieve either all versions of the run or only the latest version. If you choose to retrieve all versions of the run, you can apply a standard filter to display only the latest version. When all versions of the run are displayed, the Audit column of the run list shows the version number of the run: 1 is the oldest version, 2 the next oldest; the run marked with + is the latest version. If only the latest version of the run is displayed, a * in the Audit column of the run list denotes that multiple versions of the run exist in the database. An <A> in the Audit column generally denotes that there is more detailed information for this run besides the information that the version has been added to the database (event: NEW). The following events triggers the <A> sign: run added to a new batch run approval status changed or approval rejected run reopened custom field value changed sample name changed Agilent ChemStore C/S Concepts Guide 51

52 2 ChemStore C/S Concepts Versioning Only latest version retrieved Denotes that multiple versions exist in the database Denotes the latest version All versions retrieved Denotes an entry in the audit trail for the latest version Previous versions Denotes an extended entry in the audit trail for this version Figure 13 Retrieval and display of versions 52 Agilent ChemStore C/S Concepts Guide

53 ChemStore C/S Concepts 2 Deleting Runs from the Database Deleting Runs from the Database You can delete runs from the ChemStore C/S database using the Delete view of the stand-alone version or the Archive/Delete view of the client/server version. In the client/server version, you can choose to archive the runs before deleting, or to delete them without archiving. To archive the data in the stand-alone version, copy the *.mdb database files to your archive medium. CAUTION Runs that you delete are removed from the database and cannot be retrieved. Be sure that you only delete runs that you have either archived, copied to another medium, or no longer need. You select the runs for deleting from the run list in the left panel of the Delete view (stand alone version) or Archive/Delete view (client/server version). When you select the Delete button from the toolbar, the runs are deleted. Deleting is protected by user permission and password. The Archive/Delete and Delete views are available only to users with the requisite permissions, and you must enter your password before deletion of the runs will begin. Agilent ChemStore C/S Concepts Guide 53

54 2 ChemStore C/S Concepts Deleting Runs from the Database 54 Agilent ChemStore C/S Concepts Guide

55 Agilent ChemStore C/S Concepts Guide 3 Using the Custom Calculator What is the Custom Calculator? 56 Preparing to Use the Custom Calculator Script Editor 57 Custom Calculator Script Editor 60 This chapter describes the usage of the custom calculator. It shows how to create customized calculations on data sets of the ChemStore database and how to integrate the results into a ChemStore report. Agilent Technologies 55

56 3 Using the Custom Calculator What is the Custom Calculator? What is the Custom Calculator? The Custom Calculator is an integrated ChemStore component that provides enhanced calculation capabilities. Calculations are described by calculation templates (scripts) using a simple, SQL-like programming language. A number of wizards help the development of syntactically correct calculation templates. These wizards guides the user through the creation of each calculation step. For experienced users, a script editor allows the direct programming of calculation scripts. The programming language contains constructs that range from simple mathematical operations and functions to complex summary calculations. A set of built-in calculation templates is designed for common calculations; these may serve as a starting point for the development of custom calculation templates. When a calculation template is written, it can be tested and debugged using powerful debugging tools such as step-by-step execution and breakpoints. Calculation templates can be stored and assigned to specific users for execution only. When modifying a calculation template, the user can store it either as a separate version or as a new calculation template. The ChemStore C/S logbook keeps track of such operations. The user can preview the results of a calculation template, format and include them in reports. Calculation templates included in reports are automatically executed each time a report is generated. The results of these calculations can be printed in a tabular form as well as in charts. Access to these calculation capabilities is regulated by a special user privilege, assignment of calculation templates to users, and management of calculation template ownership. 56 Agilent ChemStore C/S Concepts Guide

57 Using the Custom Calculator 3 Preparing to Use the Custom Calculator Script Editor Preparing to Use the Custom Calculator Script Editor Retrieving the calculation data set The calculator template works on the current dataset downloaded by a database query. It s the dataset that can be seen in the review table. However, the review tables doesn t need to display all columns that are supposed to be used for calculations. The Table Wizard of the Custom Calculator allows to specify all columns of the current dataset, independent of the user interface settings. When starting the development of a new calculation template it is important to query a dataset that is representative for the data where the template should be used for. Understanding the Custom Calculator Script Editor Views Windows selection tree The window navigator is a tree view that helps the user to navigate through the custom calculation windows represented as leafs. Double clicking on a leaf node of this tree view finds, shows, and brings to the top the selected window that is partially or completely overlapped by other windows or even invisible at the time. The top two leaf nodes (Calculation, Errors) are always present. These nodes bring to the top the Calculation editor and Calculation errors windows. Below the Tables node all the currently available calculation table windows are listed. These nodes bring to the top the selected custom calculation table. Agilent ChemStore C/S Concepts Guide 57

58 3 Using the Custom Calculator Preparing to Use the Custom Calculator Script Editor Figure 14 Windows selection tree Calculation window This window is used for editing and debugging of calculation scripts. The title bar contains the name and version of the loaded calculation template, if available. The left border contains current execution line and breakpoint markers. The bottom border contains the cursor position (line and column) and an execution progress bar. The client area of the window is used for editing of the calculation script. The calculation script lines are written in black unless an error is detected or a warning is triggered. Error lines are written in red, while warning lines appear in blue. Figure 15 Calculation window Variables list The list of variables is a list containing names and values of currently available variables of a calculation Double clicking on a variable in the list of variables pops up a dialog containing a read-only copy of the variable name and value. This dialog can be used for viewing long variable names and values. It is also possible to copy these values to clipboard. 58 Agilent ChemStore C/S Concepts Guide

59 Using the Custom Calculator 3 Preparing to Use the Custom Calculator Script Editor Figure 16 Variables list Errors and warnings window The errors and warnings window lists detailed information on all errors and warnings resulting from the execution of a calculation script. A reference to the script line and a visual indication of the position of the malfunction helps to resolve the error. Agilent ChemStore C/S Concepts Guide 59

60 3 Using the Custom Calculator Custom Calculator Script Editor Custom Calculator Script Editor The custom calculator script editor is a yellow colored calculation window where the scripting of the custom calculator template is done. This can either be done by using the custom calculator wizards to create the appropriate script code or by free-hand programming, like writing a macro. Understanding the Custom Calculator Script Wizards Wizards are used to support the user in generating a script code for the desired calculation. For each individual calculation operation task a specific wizard is used to create this particular part of the script. The wizards can be invoked either from the toolbar or by clicking on a line in the template (right mouse click, select Edit from the upcoming popup menu). According to the content of this line the correct wizard is displayed holding the content of this line in its appropriate fields. The wizards can be used to create new lines or edit given lines in the template. Common wizard characteristics Figure 17 shows an example of a simple table wizard. At the left of each wizard dialog there is a symbol that visualizes the calculation statement s goal. A table wizard is e.g. used to put data from the current dataset into a table. In the middle there are syntactical components that define the parts of the command line to be generated. The order of these components is the same as they appear later on in the calculation statement. Each syntactical component contains a terminal name (large blue letters), description (small black letters), and controls for selecting and/or entering statement specific information. 60 Agilent ChemStore C/S Concepts Guide

61 Using the Custom Calculator 3 Custom Calculator Script Editor Figure 17 Table Wizard Common sub-wizards Selecting columns Figure 18 shows a dialog used for selecting table columns, e.g. when browsing the SELECT function of the table wizard. A tree view at the left contains all available tables and their columns. By moving items to the right, the new table gets defined. A list of selected columns is placed at the right of the dialog. The icons before selected tree nodes are green while those before unselected tree nodes are white. Agilent ChemStore C/S Concepts Guide 61

62 3 Using the Custom Calculator Custom Calculator Script Editor Figure 18 Column selection screen (Custom Calculator) Expressions The Expressions dialog shown in Figure 19 is the heart of the custom calculator. It allows the creation and edition of expressions and conditions. The edit box in the topmost frame contains the expression composed so far. It is possible to compose the contents by selecting the items from Data Items and Functions frame and clicking on the Add to Expression buttons. The contents of the edit box can also be typed in manually. A check icon at the top right corner and an additional information line indicate if the currently built expression is syntactically correct. These two items are updated continuously if the check box for Continuous check is checked. If the currently built expression is not syntactically correct, the check icon changes to a question mark. The check information gives some hints about the problem an the offending part of the expression is colored red in the edit box. 62 Agilent ChemStore C/S Concepts Guide

63 Using the Custom Calculator 3 Custom Calculator Script Editor Figure 19 Set condition dialog Table Wizard The table wizard displayed in Figure 17 offers the possibility to select a set of columns from the current dataset and store it into a new calculation table. This is the initial step to create a new calculation template. It is recommended to add all columns used for sample identification and used for the desired calculation steps to one overview table as a starting point. The wizard writes the result of the user s selection into the script window as given in the following example: SELECT Study, StudyName,Sample.'Sample Name', etc. FOR "Antipyrine", Phenacteine WHERE (Phenacetine.PeakArea>0 INTO "1_overview" Agilent ChemStore C/S Concepts Guide 63

64 3 Using the Custom Calculator Custom Calculator Script Editor In this example the Study name column was selected from the study table and the Sample column was selected from the sample table. The selection is based on the compounds Antipyrine and Phenacetine and limited to all samples where a Phenacetine peak was found. The result of this section will be written to the new table called 1_overview. Column Wizard Figure 20 Column Wizard The Column wizard allows the extension of a given table by a new calculation column. This column contains values based on an expression defined using the expression wizard similar to Figure 19. The example shown in Figure 20 adds a new column ResRatio to the table 1_overview. The contents of the column is defined by the area ratio of the compounds Ethanol and Methanol. 64 Agilent ChemStore C/S Concepts Guide

65 Using the Custom Calculator 3 Custom Calculator Script Editor Variable Wizard The Variable Wizard is similar to the Column wizard. The user can apply a mathematical expression of values from one or more columns and stores the result in a variable. Usually this is the case when the result comprises the evaluation of a series of values. If Wizard The previous examples showed how to calculate new values based on given values in columns and assign them either to new values in a column or to a single variable. In cases where this assignment should be dependent on a certain condition, the IF wizard can be utilized. Format Wizard The custom calculator displays numbers as raw figures using all available decimals. To achieve a better readability or display significant digits only, the Format wizard formats single values (variables), a column of a specific table or even a set of columns from multiple tables. The precision of calculation is not affected by the number format. Besides numbers it also possible to format strings, dates and times and even empty cells. The on-line help of the Format Wizard contains examples of these extended formatting options. Transpose Wizard The Transpose Wizard allows to transpose an existing table by turning columns into rows and rows into columns. This can be useful when calculating statistics over values which are given in a row. Those might result from a previous calculation. However, statistics are only possible along columns and a transpose step needs to be done prior to statistics calculation. The Transpose wizard dialog (Figure 21 on page 66) contains the following syntactical components: In the TRANSPOSE combo box the user can specify the name of the table to be transposed. Note: The selection contains only those tables that are available at the given calculation line - all previously generated tables. Agilent ChemStore C/S Concepts Guide 65

66 3 Using the Custom Calculator Custom Calculator Script Editor In the BY combo box the user needs to specify which table column should be used as the header row for the transposed table. Typically this is the sample name or run ID, as those items defined the rows of the original table. In the INTO edit box the user can specify a name for the transposed table. Figure 21 Transpose Wizard Group Wizard Grouping a table is useful e.g. in cases of calculating statistics over a certain set of samples, rather than overall statistics. The same results can be achieved by defining multiple sub-tables, but the Group wizard combines this to one step. The dialog shown in Equation 22 on page 67 contains the following syntactical components: In the GROUP combo box the user specifies the name of the table considered to be grouped. 66 Agilent ChemStore C/S Concepts Guide

67 Using the Custom Calculator 3 Custom Calculator Script Editor In the BY combo box the user specifies the identifier of the group. E.g. grouping by Sample calibration level allows to combine samples and calibration in separate groups. Calibration runs will also be grouped by the calibration level. The DO component defines a (statistical) function being applied to a given table column resulting into a new named column. The INTO box needs to be filled with a name for the resulting table. Figure 22 Group Wizard Agilent ChemStore C/S Concepts Guide 67

68 3 Using the Custom Calculator Custom Calculator Script Editor Example: Creation of a report calculation script In the following chapter it is shown how a simple example template can be developed. The example is based on the data you receive when executing the query SSR for quality control on the ChemStoredemo.mdb database installed with ChemStore C/S. It is recommended to follow the steps in this chapter to get familiar with the usage and the functionality of the calculator wizards. This example does not represent a recommendation on how to evaluate acceptance criteria for a data set. NOTE In case the described script cannot get achieved, a copy of this example script is located on the ChemStation Plus installation CD. Browse the support folder for simple_example.cct. To import the example script to the demo database, use the import function of the custom calculator. Assuming you have been given the following task: Develop a template where the relative standard deviation of the areas of a given compound gets calculated for calibration runs and sample runs. The comparison should mark sample runs as pass if the relative standard deviation is less in comparison to the relative standard deviation for calibration runs. The results should be integrated in a report. To achieve a solution for this task you have to go through four phases: 1 Set up a plan including the steps which are needed to achieve a solution. 2 Develop the template according to this plan. This includes testing and correcting of each development step. 3 Refine the template 4 Include template into report. Set up a plan To set up the plan you first have to fully understand the task. Divide the task into steps and write down what you want to achieve in each step: 68 Agilent ChemStore C/S Concepts Guide

69 Using the Custom Calculator 3 Custom Calculator Script Editor 1 Create a table which consists of all parameters which you need for your calculation and all sample parameters which need for sample identification and reporting. For calculation you need: Peak area Sample type to distinguish calibration runs from sample runs For sample identification you want to see: Sample name Raw data file name 2 Calculate the relative standard deviation of peak areas per calibration level and store it into a new table. 3 Calculate the average of the relative standard deviations and store it in a variable. 4 Calculate the mean areas for all sample runs and the absolute and relative deviation from this mean amount. This should be done on a per run basis. 5 Check whether the relative deviation of each sample is less than the average relative standard deviation of the calibration runs and mark it appropriately. After each step you should test the intermediate result to see whether you are on the right track. If the intermediate result deviates from your expectation you should undertake corrective actions. Developing the template Create an overview table To create the starting table you will use the table wizard as shown in Figure 23 on page 70. Select the columns Sample Name, Sample Calibration level, Sample type, Acq. Sequence name, Raw data file name and Peak area for compound Antipyrine and store it in the table '1_overview'. It's a good practice to add a leading number to the tables created by the script in order to reflect the script structure in the results. Agilent ChemStore C/S Concepts Guide 69

70 3 Using the Custom Calculator Custom Calculator Script Editor Figure 23 Table Wizard Figure 24 Overview table 70 Agilent ChemStore C/S Concepts Guide

71 Using the Custom Calculator 3 Custom Calculator Script Editor For testing this step you execute the script and you should get a table where sample names, calibration levels, sample types, acq. sequence names, raw data file names and peak areas for the compound 'Antipyrine' are listed for all samples retrieved by the query 'SSR for quality control (see Figure 24 on page 70). Create sub-tables The next step is to create a sub-table to separate calibration runs from sample runs. This can be achieved by using a sub-table wizard. The key to separate the sample types is the WHERE condition, that has to match exactly example shown in Figure 25 on page 71. The condition "Calibration" has to be typed manually in the set condition dialog and it needs to be enclosed in double quotes. Figure 25 sub-table wizard for separating calibration runs Executing the script will result in a simple table that lists all calibration samples with the calibration level and the peak areas of compound 'Antipyrine' (see Figure 26 on page 72). Agilent ChemStore C/S Concepts Guide 71

72 3 Using the Custom Calculator Custom Calculator Script Editor Figure 26 Calibration run sub-table Calculate the relative standard deviation of peak areas for each calibration level To calculate the relative standard deviation per calibration level you can utilize the Group wizard. Grouping the table '2_calib_runs' on calibration Figure 27 Group Wizard levels generates one result per level and stores it in the new table '3_calibstatistics'. The calculation to be executed per group gets defined in the DO/AS section of the group wizard (Figure 27 on page 72). The group wizard 72 Agilent ChemStore C/S Concepts Guide

73 Using the Custom Calculator 3 Custom Calculator Script Editor allows to define multiple calculations for multiple compounds at the same time, but the current example is restricted to one, for the sake of simplification. Executing the script results in a small table containing the relative standard deviation for each calibration level. Figure 28 Relative standard deviation of Antipyrine peak areas To average the relative standard deviations, the variables wizard should be used with the following definition statement: Avg(RSTD_Antipyrine)=mean( 3_Calibstatistics. RSTD_Antip_area ) For testing this step you execute the calculation and you will find your variable with the appropriate result in the variable list. The calculation on the calibration runs is finalized now and the next step is to perform calculations on the sample run results and finally perform the desired comparison. Calculate the relative area deviation for sample runs To list the sample runs in a separate table generate a sub-table as shown in Figure 25 on page 71, but replace the sample type Calibration in the WHERE condition by Sample and the destination table name to '4_sample_runs'. The next two steps are adding two additional columns to the sample table - one for calculating the average response over all samples (see Figure 29) and another one for calculating the absolute deviation of the individual responses from the average. Use the 'add columns' wizard twice to achieve this result. The 'set condition' dialog for calculating the absolute deviation is shown in Figure 30. Agilent ChemStore C/S Concepts Guide 73

74 3 Using the Custom Calculator Custom Calculator Script Editor Figure 29 Averaging Antipyrine responses for sample runs Figure 30 Absolute deviation of Antipyrine area from mean value 74 Agilent ChemStore C/S Concepts Guide

75 Using the Custom Calculator 3 Custom Calculator Script Editor Executing the script results in the following sample table: Figure 31 Results of deviation calculations Check and mark Now, all results are available to define a final result table where the comparison will be executed. Use a sub-table wizard to generate an extract of the table '4_sample_runs' and store it in the final result table Figure 32 Calculating relative area deviation Agilent ChemStore C/S Concepts Guide 75

76 3 Using the Custom Calculator Custom Calculator Script Editor '5_Antipyrine_results'. The example uses the columns sample name, raw data file name, peak area, delta_ant. If other columns for sample identification should appear in the final report, they need to be added in addition to the results table. Before comparing sample runs and calibration runs, the absolute area deviation of the sample runs needs to be divided by the area to get the relative deviation. The add column wizard for this calculation is shown in Figure 32 on page 75. If the relative area deviation is less than the average value for the calibration runs, the runs should be marked with PASS, otherwise with FAIL. This can be achieved with the If wizard. The IF condition in Figure 33 on page 76 shows this comparison. The THEN and ELSE statements are defined by column wizards, accessible through the browse buttons of the IF wizard. This step, shown in Figure 34 on page 77, will add a 'status' column to the result table. Figure 33 If wizard for result evaluation 76 Agilent ChemStore C/S Concepts Guide

77 Using the Custom Calculator 3 Custom Calculator Script Editor Figure 34 Defining a THEN statement with the help of a column wizard For testing this final step you execute the script and a new column is added to the result table having PASS or FAIL next to the relative deviation column (Figure 35 on page 77) Figure 35 Final result table Agilent ChemStore C/S Concepts Guide 77

78 3 Using the Custom Calculator Custom Calculator Script Editor Refining the template Formatting columns Last but least you might want to format some of the columns. Use the format wizard to format e.g. the delta_ant column of table 4_sample_runs and in table 5_Antipyrine_results, the rel_dev column and the Antipyrine.Peak.Area column as shown in Figure 36. All table columns and all variables that should appear with the same number format can be defined by one table wizard. Figure 36 Formatting the final result table Embedding template into report In section Calculations on page 104 it is described how to embed a calculation result table into a report. 78 Agilent ChemStore C/S Concepts Guide

79 Using the Custom Calculator 3 Custom Calculator Script Editor Using the Custom Calculator Script Editor The script editor is like a text editor for custom calculator scripts. Experienced users can write scripts without the help of wizard. This also allows to create script constructs which cannot be created with a wizard. Such script constructs can make the script code much shorter and clearer to overview. Commands In the following, the most important commands used for scripting the template will be briefly described. For a detailed description of all commands, refer to the reference section Custom Calculator Commands on page 185. Selection of columns from database To select columns from the database, optionally using a condition for shrinking the resulting dataset, you use the SELECT command: SELECT column(s) FOR compound(s) WHERE acondition INTO atable column(s) can be one or more columns, specified by name, from any available table in the database. compound(s) can be one or more compounds, specified by name, for which the columns should be selected. Wildcards are allowed here. See the reference part of Custom Calculator Commands on page 185 for more details. acondition is optional. It specifies a condition for the selection. atable is the name of a table to which the selection will be written. Selection of columns from a table To select columns from a custom calculator table, you use the FROM command: FROM atable SELECT column(s) FOR compound(s) WHERE acondition INTO anothertable This command does the same as the SELECT command, except that it retrieves the columns only from a table which you have received from a previous SELECT or FOR command. Agilent ChemStore C/S Concepts Guide 79

80 3 Using the Custom Calculator Custom Calculator Script Editor Making decisions Decisions can be made by using conditional statements. The IF THEN ELSE command is used to perform this operation: IF acondition THEN dothis ELSE dothat If the condition is fulfilled, the THEN part will be evaluated; if the condition is not fulfilled, the ELSE part will be evaluated. The ELSE part is optional and can be omitted. NOTE The conditional statement can be assigned only to operations on variables or table columns. It cannot be used for conditional evaluation of your template script. Formatting results in table(s) The resulting values in the custom calculator tables or from variables can be formatted using the FORMAT command: FORMAT column(s)/variable(s) USING aformat aformat is a string (enclosed with quotes) containing the format specification. See the reference part of Custom Calculator Commands on page 185 for more details. Transposing table(s) Calculations are performed on selected columns for each row. Results are written into new columns. Certain (statistical) calculations need to be done on one row for each column. This is not possible directly: this row has to be turned onto a column. To do so, you use the TRANSPOSE command: TRANSPOSE atable BY acolumn INTO destinationtable A column is used as key for the transpose operation. The entries of this column will be used as column headers for the destination table. Since the column names must be unique, the destination table does not contain any column with a name that appears more than once. Grouping table(s) Grouping tables is a way to better organize the contents of a table to make some statistics possible. You group tables using the GROUP command: 80 Agilent ChemStore C/S Concepts Guide

81 Using the Custom Calculator 3 Custom Calculator Script Editor GROUP atable BY acolumn DO operation(s) INTO destinationtable Grouping of a atable is defined by the values of a column. Each group of rows contains rows with equal values in the column. The operations to be performed on each group of rows are defined by the operation(s). Adding comments The #-symbol is used to start a comment. Text written after this #-symbol will NOT be evaluated: # This is a comment! In spite of a future wizard which will handle the declaration part of your script the comments are added after the variable definition in case they are related to this definition: strcompund = Barbital # This is the definition for the compound The declaration part of the script starts with the # D E C L A R A T I O N comment and ends with the # I M P L E N T A T I O N comment. Syntax The detailed description for the syntax of all commands and script parts you will find in the reference section of Custom Calculator Commands on page 185. The following part describes some specials which should be considered to avoid unnecessary errors in the script. Using quotes Quotes must always be used to enclose strings. Strings are names of compounds, samples etc. and names of columns. Furthermore, as you will see in the next section, strings also can contain commands. If the string also contains quotes, these quotes must be turned into double quotes. Agilent ChemStore C/S Concepts Guide 81

82 3 Using the Custom Calculator Custom Calculator Script Editor Apostrophes around column names must remain when enclosed by quotes. Using brackets Brackets must always be used when several operations in an expression have to be ordered hierarchically. Expressions in brackets will be evaluated first. Therefore each part of expression which must be evaluated before another part has to be enclosed with brackets. Case sensitivity Usually the scripts (commands, column names, expressions) are not case-sensitive. There is just two exceptions: When a comparison is made on strings to check the identity of strings (string1=string2), this operation is case sensitive. The names of variables must be used in the script as they were defined in the beginning Usage of string variables The major feature of the script editor is to create string variables. In the following we will prefix string variable names with str. A string variable is a piece of text enclosed with quotes. The content of these string variables can be a simple name e.g. a compound name or the definition of the sample name column: strcompound = Barbital strsmplname = Sample. Sample Name but also a piece of script code itself e.g. the instruction to select columns from the database: strselect = SELECT Sample. Sample Name FOR Barbital INTO atable Consider that column names using a blank: Sample. Sample Name or a special characters in their names (like 1_overview ) have to be enclosed by (apostrophe). The purpose of using string variables is to define such variables once and reuse them in the rest of the script even multiple times. 82 Agilent ChemStore C/S Concepts Guide

83 Using the Custom Calculator 3 Custom Calculator Script Editor To reuse these string variables you must prefix them with a $-sign: $strcompound $strselect The $-sign will instruct the script interpreter to interpret the content of this variable. Instead of writing SELECT Sample.SampleName FOR Barbital INTO atable you also can write: SELECT Sample.SampleName FOR $strcompound INTO atable The interpreter will substitute $strcompound by Barbital before evaluating the SELECT command and doing the database selection. This has the advantage that you define a compound name once in the beginning of the script and then you can refer to it in the rest of the script. When you have to change the compound name you just do it once in this variable at the beginning of the script. As shown in the upper example you can also define string variables for script coding: strselect = SELECT Sample.SampleName FOR Barbital INTO atable or considering the name substitution: strselect = SELECT $strsmplname FOR $strcompound INTO atable To use this type of construct you just write in the script editor the string variable with the $-sign as prefix: $strselect The script interpreter first will substitute the sample and compound name string variables by their contents and then do the selection itself which means in this case to select all sample names for Barbital. As you have seen, string variables can also contain string variables (with $-sign as prefix). The string variables are substituted by their contents at the moment when the script interpreter is evaluating and executing the command either from a string variable as shown in the last example: $strselect or from the entered command itself as shown in the previous example: Agilent ChemStore C/S Concepts Guide 83

84 3 Using the Custom Calculator Custom Calculator Script Editor SELECT $strsmplname FOR $strcompound INTO atable There is another very special sign for substitution. Peak parameters such as area, height but also tailing factor, resolution etc. are dependent on the chosen compound. You usually select these parameters for specific compounds. The script editor allows you to use the! (exclamation mark) for selecting these peak parameters referring to the currently used compound: SELECT!Peak.Area FOR $strcompound INTO atable Executing this command will select only peak areas of the compound defined in strcompound (e.g. Barbital). The! stands for Barbital or whatever compound name was defined in the strcompound string variable. You could have also written: SELECT Barbital.Peak.Area FOR $strcompound INTO atable but then you are fixed to Barbital or SELECT $strcompound.peak.area FOR $strcompound INTO atable but using! is simpler. Example: Creation of a report calculation script Remember the example which you have developed in the previous section. In this chapter this example is used to demonstrate the advantages of using string variables. This adds more flexibility when adapting the script to other data sets. NOTE In case the described script cannot get achieved, a copy of this example script is located on the ChemStation Plus installation CD. Browse the support folder for refined_example.cct. To import the example script to the demo database, use the import function of the custom calculator. First you define some string variables. This will become the defining section in your script. Then replace the appropriate part of the script with these variables. This will become the implementation part of the script. Finally you add some comments to the script. 84 Agilent ChemStore C/S Concepts Guide

85 Using the Custom Calculator 3 Custom Calculator Script Editor Defining string variables Define a string variables for the compound name. Then it will be easy to replace the compound name in case you need to use this script for another compound: strcompound = Antipyrine Define a string variable for the response column name. Then it becomes easier to switch between area and height as response indicator: strresponse = Peak.Area For better readability define a string variable for the selection. This makes it easier for modifying the complete selection. You can even use the upper defined string variables as part of this one with the $-sign as prefix: strselection="sample.'sample Name', Sample.'Sample Calibration Level', Sample.'Sample Type', 'Acq Sequence'.'Acq. Sequence Name', 'Raw Data'.'Raw Data File Name',!$strResponse" Applying string variables The first select statement will turn into: SELECT $strselection FOR $strcompound INTO '1_overview' and the second one will be reduced to: FROM '1_overview' SELECT $strselection FOR $strcompound WHERE '1_overview'.Sample.'Sample Type'="Calibration" INTO '2_calib_runs' The three calculation statements will simplify to GROUP '2_calib_runs' BY 'Sample.Sample Calibration Level' DO rstdev ($strcompound.$strresponse) AS 'RSTD_Antip_area' INTO '3_Calibstatistics' '5_compound_results'.'rel_dev'='5_compound_results'.'delta_Ant'/'5_compoun d_results'.$strcompound.$strresponse Commenting script The last step is adding meaningful comments to separate the definition section from the implementation section and to simplify the customization of the definition section. See also the refined_example.cct template on the installation CD-ROM. Agilent ChemStore C/S Concepts Guide 85

86 3 Using the Custom Calculator Custom Calculator Script Editor 86 Agilent ChemStore C/S Concepts Guide

87 Agilent ChemStore C/S Concepts Guide 4 Using the Report Template Editor What is the Report Template Editor? 88 Preparing to Use the Report Template Editor 90 Using the Report Template Editor 93 Understanding Report Template Components 96 Understanding Tables 106 Generating a Report Using a Template 121 Using Automatic Reporting 121 Agilent Technologies 87

88 4 Using the Report Template Editor What is the Report Template Editor? What is the Report Template Editor? The Report Template Editor is an application that is available by clicking the left icon under the name of the report (Compound Amounts [(built-in)] in the figure below) or choosing a menu item from the Report menu in the main dialog box in ChemStore C/S. Figure 37 Report template editor The Report Template Editor is used to create and edit report templates, which are then used to generate reports. Because you may want to use the same report many times, but with slightly different specifications and with different data, the Report Template Editor was designed to allow you to create easily modifiable report templates. Figure 38 Report Template Editor 88 Agilent ChemStore C/S Concepts Guide

89 Using the Report Template Editor 4 What is the Report Template Editor? When you create a report template, you specify such things as the contents and placement of a header or footer, tables or charts to include and the fonts used in each area of the report. In effect, you create a specific design for the layout and contents of a report and save the design to use again the next time you want to generate that report. In addition, you can change the design of any report template and save it under a new name. Agilent ChemStore C/S Concepts Guide 89

90 4 Using the Report Template Editor Preparing to Use the Report Template Editor Preparing to Use the Report Template Editor Retrieving the report data set In ChemStore C/S, you query the database based on data fields that you choose and specify values for. The group of data records that result from the query is called the current data set (also known as a snapshot). Then, you select a report template and use it to generate a report. This report prints information contained in the current data set according to the structure of the template. You can even restrict the data that appears on the report further, but if the data is not in the current data set, it does not appear on a report that was generated using the current data set. 90 Agilent ChemStore C/S Concepts Guide

91 Using the Report Template Editor 4 Preparing to Use the Report Template Editor Understanding the Report Template Editor Tree Views The Report Template Editor uses tree views to display various objects. Figure 39 Tree View of Report Template in Report Template Editor The first object that is displayed in a tree view, when you open a template, is the report template itself (on the left-hand side of the main dialog). When you edit an existing report template, the Report Template Editor main dialog box contains a tree view of the structure of the template. The report template name is the top of the tree. Directly under the template name, you might see report template components: page headers and footers data sections section headers section elements, such as tables, charts, calculations, chromatograms and spectra Agilent ChemStore C/S Concepts Guide 91

92 4 Using the Report Template Editor Preparing to Use the Report Template Editor Anything in a tree view that can be expanded (like a directory structure in Windows Explorer) is adjacent to a plus sign in a box. Page headers never have a plus sign next to them because they are never expanded. But data sections contain tables and charts; so if you click the plus sign next to a data section name, you can view the elements that make up the data section. See Understanding Report Template Components on page 96 to learn more about the sections and elements that make up a report template. 92 Agilent ChemStore C/S Concepts Guide

93 Using the Report Template Editor 4 Using the Report Template Editor Using the Report Template Editor Using Dialog Boxes to Create Report Sections You use the Report Template Editor main dialog box to create the sections and elements that you want to appear on the report by using menu items or by right-clicking the mouse. Figure 40 Menu for Creating Elements of Data Sections The parameters associated with the section or element that you are editing appear in the right-hand side of the dialog box. For example, if you are adding a page header, the right-hand side of the dialog box contains parameters such as those that specify whether or not to print the header on every page or whether or not to print a border around the header, etc. Agilent ChemStore C/S Concepts Guide 93

94 4 Using the Report Template Editor Using the Report Template Editor Figure 41 Page Header Dialog Box on Report Template Editor Then, on the bottom of the dialog box, there are one or more buttons that you click to reach the dialog boxes used to edit the parameters. When editing a page header, there is only one button on the Report Template Editor main dialog box and it is labeled Edit. When you click it, you can edit the many different parameters associated with a header such as the number of columns and rows in the header and what text or data items to print in the columns/rows. If you are editing a table, there are many more buttons at the bottom of the Report Template Editor main dialog box because there are many more parameters that can be configured for a table than for a header. Figure 42 Table Dialog Box on Report Template Editor 94 Agilent ChemStore C/S Concepts Guide

95 Using the Report Template Editor 4 Using the Report Template Editor Using Tree Views for Tables and Charts Another area where a tree view is used is during data field selection, such as for table columns or chart axes. It is convenient to use a tree view when selecting database fields because fields are members of records that are themselves members of a data set. For example, if you are selecting the columns for a sample table, you would expand the view of the data set that contains the information about sample organization so that you could view all of the fields associated with samples. Figure 43 Tree View for Designing a Table Agilent ChemStore C/S Concepts Guide 95

96 4 Using the Report Template Editor Understanding Report Template Components Understanding Report Template Components A report template comprises one or more of the following objects: a header, a footer, page breaks and data sections. Data sections contain report elements such as tables, calculations, chromatograms, spectra and charts. Any one of these sections or elements can be excluded from a generated report without deleting it from the report template simply by using a check box. Each of the components of a report template is called an object because you can edit them on an individual basis and they do not depend on the other components that you have selected for the template. Page Headers and Footers You can set up a page header or footer for the report template to indicate Report Name, Report Comment, User, Time, Page, Report Modified Date and Report Modified By. Each of these items can be placed in one of three columns in the header and formatted with any font and size that your computer supports. In addition, each of these items can be labeled and justified within the column. Graphics, such as your company logo, can also be placed in the header or footer. 96 Agilent ChemStore C/S Concepts Guide

97 Using the Report Template Editor 4 Understanding Report Template Components You edit headers and footers using a dialog that allows you to see where each item is placed, in relation to the header and in relation to other items in the header. This dialog is set up so that you can see what the header/footer looks like, as you edit it. Figure 44 Editing Headers and Footers Data Sections Data sections contain one or more report elements, such as tables, calculations, charts, chromatograms and spectra. There are few parameters directly associated with a data section, as you can see if you click on a data section name in the tree view of a report template. There is a description field (which appears in the tree view) and there is a check box for whether or not to include this data section in a report. The one button, Repeat, that appears on the dialog box is used to select fields for repeating. Thus, the repeat function has a major influence on the internal order of the report you generate. It s the key to create all different type of reports. Agilent ChemStore C/S Concepts Guide 97

98 4 Using the Report Template Editor Understanding Report Template Components Figure 45 Data Sections Repeating a Section You can repeat a data section for every unique combination of the fields that you select. For example, suppose you want to create a summary report for sequences, including statistical calculations. However, you don't like to calculate one overall statistic over all calibration levels and sample runs. To report calibration levels and sample types separately, the items 'Sample calibration level' and 'Sample type' needs to be added to the repetition section, as shown in Figure Agilent ChemStore C/S Concepts Guide

99 Using the Report Template Editor 4 Understanding Report Template Components Figure 46 Repetition In our example, we also want to avoid cross-sequence and cross-study statistics, so these items are also added as separators. Finally, we like to report the sequence results for each compound in an individual table, including statistics. There for, the item 'Compound name' is added. Another important criteria is the order of the field items in the data section. The lowest item in the list gets iterated first. In our example, the pages of the report would show the following order: Compound A (Cal.level 1),Compound B (Cal.level 1), Compound A (Cal.level 2), Compound B (Cal.level 2), Compound A (samples), Compound B (samples) To get all reports for Compound A in one series of report pages, the item 'Compound Name' needs to get moved above the item 'sample type'. This would result in the following printing order: Compound A (Cal.level 1),Compound A (Cal.level 2), Compound A (samples), Compound B (Cal.level 1), Compound B (Cal. level 2), Compound B (samples). Agilent ChemStore C/S Concepts Guide 99

100 4 Using the Report Template Editor Understanding Report Template Components Calculated Fields You can create calculated fields using any of the fields in the current data set. Once created, calculated fields can be used to determine the repeating section as well as columns in a table or axes in a chart. Calculated fields are selected in the same way as other data fields except that they all appear together under the heading Calculated Fields in the tree view of the data set. Section Headers Section headers are used to differentiate report sections. In addition to the items listed for page headers/footers (Report Name, Report Comment, Page and so on), section headers can contain any data that you have selected as data items to repeat on. For example, if you chose to repeat the section based on the unique combinations of Sample Type and Study Name, then those two data items appear in the list of data items that can be placed in the section header. If you do not select repeating data items, then the only items you can place in a section header are the ones that are available to the standard page header. Section Elements Tables You can create eight different types of tables; the type of table that you select determines the data set fields that you can use. The choices are injection, run, signal, compound, peak, column configuration, instrument components and audit trail. See Understanding Tables in this chapter to learn more about how these tables work. For each table, you specify the following: the data fields to use as columns in the table the data fields to use to group data in the table the columns to sort on (up to 3) any summaries to generate for each group or for the overall report the font and size of the information that is printed 100 Agilent ChemStore C/S Concepts Guide

101 Using the Report Template Editor 4 Understanding Report Template Components Figure 47 Run Table Whenever a table uses columns containing only names or strings and no numerical entries, rows containing the same entries will collapse into one row. Whenever a table uses columns containing numerical entries, the table rows will remain separate, even though the entries in the rows appear identical, as in rows one and three in the Peak Table below: Agilent ChemStore C/S Concepts Guide 101

102 4 Using the Report Template Editor Understanding Report Template Components Table 2 Peak Table Study Name Sample Name Inj Vol Compound Name Expected RT Procaine Procaine decay 3.0 Amino-Benzoic Acid Procaine Control Procaine 3.0 Amino-Benzoic Acid Procaine Procaine decay 3.0 Amino-Benzoic Acid Charts You can create two types of chart for your report: compound or sample. For both types of chart, you specify the following: the data fields to be used to create the X and Y axes restrictions on the actual data used to create the chart and for compound charts, the compounds to include the data fields to use to group charts additional chart options including curve type, weighting, treatment of the origin, limits, titles and scaling 102 Agilent ChemStore C/S Concepts Guide

103 Using the Report Template Editor 4 Understanding Report Template Components Figure 48 Compound Chart When creating a sample chart, the values for the Y-axis can be chosen from per-run fields. For each Y-axis field that is selected, there is a single point per run, with the values for the various runs spread out along the X-axis of the chart. When creating a compound chart, the values for the Y-axis can be chosen from per-compound fields. If the section has data for multiple compounds, that data may be overlaid on a single chart (with one curve per compound) or on multiple charts. You can also group data in charts. If the data is grouped, then only data from a single group is included in a single chart. Therefore, there is one chart printed for each different group of data. Agilent ChemStore C/S Concepts Guide 103

104 4 Using the Report Template Editor Understanding Report Template Components Calculations You can include the results generated by a custom calculator script in your report. The results to display are either a calculation table, a list of variables used for calculation or a calculation chart visualizing the calculation results. In addition, the calculation script itself and the list of calculation errors and warnings can be added to the report. Figure 49 Calculation Table For each items, you specify the following: the name of the calculation template the version of the calculation template the font and size of the information that is printed 104 Agilent ChemStore C/S Concepts Guide

105 Using the Report Template Editor 4 Understanding Report Template Components For calculation tables and charts you need to select in addition the name of the result table generated by the calculation template. Once the calculation template and version are chosen, the calculation tables are selectable. The 'data series' dialog then allows to select the columns to be displayed or plotted. CAUTION In order to successfully create a report template including custom calculations it is important to have a calculation template that runs smoothly on the current data set. Report and calculation templates are not hard-linked when exporting those to a file system. Both templates needs to be exported and imported individually. Chromatograms Chromatograms can be added to the report if they were stored in the database. Storing chromatograms is an option in the study transfer settings. When chromatograms are printed in the report, they are presented simply as graphical metafile representations of the chromatogram plots generated in the ChemStation software. They may not be further customized within the ChemStore reports. If your ChemStation system used a color or greyscale printer driver, then the chromatograms stored in ChemStore will be in color. Otherwise, they will be black and white. The size, position and grouping of chromatograms can all be specified from the report template designer. Spectrum plots If spectra were stored with the data, they can also be included on the report. Storage of spectra is also controlled through the study transfer settings. As with tables and certain charts, additional restrictions such as printing only spectra for a particular compound or group of compounds can be set up. If your ChemStation system used a color or greyscale printer driver, then the spectrum plots stored in ChemStore will be in color. Otherwise, they will be black and white. The size, position and grouping of spectrum plots can all be specified from the report template designer. Agilent ChemStore C/S Concepts Guide 105

106 4 Using the Report Template Editor Understanding Tables Understanding Tables The concepts behind the process of constructing tables with the ChemStore Report Template Editor are the most complex within the software. In this section these concepts are presented so that you can understand the tables that appear from the choices you make. Grouping and Summaries for Tables Grouping Data in tables can be grouped, meaning that all rows with the same value of a field are placed together. The groups are sorted by the field that controls grouping while the rows in each group are sorted according to the sort order you select. If you choose to group rows in a table, then you can save a column in the table by not including the grouping item as a column. In fact, if you have set up the columns in your table and then you set up grouping, using a field that is already represented by a column, a message box appears letting you know of the duplication. For example, you can group the rows of a table on Study Name so that all data for the same study appears together. The grouping data item, Study Name, appears at the top of each group and then all the data for that group is sorted according to any sort you set up. Another way to do this is to include Study Name as a column and then assign Study Name as the first sort item. By grouping on Study Name instead, though, you can create space in your table to include another column. 106 Agilent ChemStore C/S Concepts Guide

107 Using the Report Template Editor 4 Understanding Tables Figure 50 Compound Table Statistics Statistics can be printed in table summaries. You can request an overall summary and/or group summaries (if you have specified a data item for grouping). Summaries consist of up to seven lines of statistical information such as Mean, Std Deviation, Minimum, Maximum, etc. You can specify whether or not a column is included in group or overall summaries. Agilent ChemStore C/S Concepts Guide 107

108 4 Using the Report Template Editor Understanding Tables Understanding Table Types Relationships between Table Elements The relationships between table elements, even within a small database, can be quite complex. The figure below shows an example of how some table elements within a small database are related to one another. Injections Runs Compounds Peaks (1A) 2 (1B) 3 (2A) 4 (2B) X (1) X (2) Y (2) Y (3) Y (4) Z (3) Z (4) Signals I? 1, I, 1.0 main 1, II, 1.0 qual 2, I, 1.0 main 2, II, 1.0 qual 2, I, 2.0 qual 2, II, 2.0 main 2, I, 3.0 unk 2, II, 3.5 unk 3, I, 2.0 main 3, II, 2.0 3, III, 2.0 3, I, 4.5 main continued II III Figure 51 Relationships between Table Elements Within the figure, injections, runs, compounds, signals and peaks are related to one another in the following ways: The database holds data from two different injections. Each of these has been analyzed twice, so there are a total of four runs. During the first injection, signals (chromatograms) I and II were acquired (e.g., signals from two different detectors, or two different channels of a multi-channel detector). During the second injection, three signals (I, II and III) were analyzed. In run 1 only the compound X was detected, but run 2 found both compounds X and Y. Runs 3 and 4 both found compounds Y and Z. 108 Agilent ChemStore C/S Concepts Guide

109 Using the Report Template Editor 4 Understanding Tables The results for signal I from run 2 include peaks at 1.0, 2.0 and 3.0 minutes. Signal II for that run has peaks at 1.0, 2.0 and 3.5 minutes. Signal I was used to quantitate Compound X, so the peak (2, I, 1.0) is identified as a main peak. The peak at the same time from signal II is still associated with Compound X, but not as the main peak. There are also two peaks associated with Compound Y for run 2; in this case Signal II is designated the main peak. Note that the peaks for Run 2 at 3.0 and 3.5 minutes are not associated with ANY compound. This example is now used to help explain the Injection, Run, Signal, Compound and Peak Tables. Injection Table In an Injection Table, the only fields (columns) that you can include are those with one value per injection (for example, injection date/time, name of the instrument used, vial number, data file name). Effectively, the data model shown in Figure 51 on page 108 is simplified to that shown in Figure 52. Injections 1 2 Figure 52 Data Model for an Injection Table Generally speaking, the table in the report will have no more than one row for every injection in the snapshot database (in this case, two rows), see Table 3 on page 110. Agilent ChemStore C/S Concepts Guide 109

110 4 Using the Report Template Editor Understanding Tables Table 3 Example of Table in a Report Injection Date Instrument Operator Vial Number 1-Apr :00 LC System A Fred 10 1-Apr :20 LC System A Fred 33 There are several reasons there might be fewer rows than this: If the table is in a section that is repeated, each repetition of the table will only have the rows that are associated with the values of the repeat fields for that repetition. For instance, if the section is repeated on compound name, then there will be three repetitions (one for X, Y and Z). The injection table in the first repetition would have only injection I (because compound X is only detected in runs based on the first injection). The Y repetition would have injections I and II, and the Z repetition would have only a row for injection II. If there are any data restrictions specified for the table element, then any row which doesn t meet the criteria will be eliminated. If the table does not contain any numeric or date/time columns, then only unique rows are shown in the table. In the above example, if only the instrument and operator columns were included then there would be only a single row, rather than two rows with identical contents. 110 Agilent ChemStore C/S Concepts Guide

111 Using the Report Template Editor 4 Understanding Tables Run Table The only fields that you can include in a Run Table are those with one value per injection or one value per run (for example, study name, custom field values, processing method name). The data model from Figure 51 on page 108 is reduced to that shown in Figure 53. Injections Runs 1 (1A) 1 2 (1B) 2 3 (2A) 4 (2B) Figure 53 Fields in a Run Table Generally speaking, the table in the report will have no more than one row for every run in the snapshot database (in this case, four rows), see Table 4. Table 4 Example of Table in a Report Run No. Injection Date Vial Run Version Approval Patient Code 1 1-Apr : Pending PKH Apr : Approved PKH Apr : Pending PKH Apr : Approved PKH9004 Agilent ChemStore C/S Concepts Guide 111

112 4 Using the Report Template Editor Understanding Tables As in the case of Injection Tables, there may be fewer rows for the following reasons: The table is in a repeated section. There are data restrictions specified for the table element. No numeric or date/time columns are present and some rows would otherwise be identical. For instance, if you include only the Approval OR Patient Code columns, there would be only two rows. If you include both Approval AND Patient Code, there are still four rows, as there are four unique combinations for these columns. Signal Table The only fields that you can include in a Signal Table are those with one value per injection, run or signal (for example, signal description, start time, end time, type). The accessible data model looks like Figure 54. Injections Runs Signals I II III 4 Figure 54 Data Model of a Signal Table Generally speaking, the report will have no more than one row for each combination of run and signal. In this case, there are two signals associated with runs 1 and 2, and three signals associated with runs 3 and 4, so there may be as many as ten rows, see Table 5 on page Agilent ChemStore C/S Concepts Guide

113 Using the Report Template Editor 4 Understanding Tables Table 5 Example of Table in a Report Run No. Version Vial Channel DAD1 A, Sig=282,8 Ref=550, DAD1 B, Sig=295,8 Ref=550, DAD1 A, Sig=282,8 Ref=550, DAD1 B, Sig=295,8 Ref=550, DAD1 A, Sig=282,8 Ref=550, DAD1 B, Sig=295,8 Ref=550, DAD1 C, Sig=320,8 Ref=550, DAD1 A, Sig=282,8 Ref=550, DAD1 B, Sig=295,8 Ref=550, DAD1 C, Sig=320,8 Ref=550,100 As in the case of Injection and Run Tables, there may be fewer rows for the following reasons: The table is in a repeated section. There are data restrictions specified for the table element. No numeric or date/time columns are present and some rows would otherwise be identical. For example, if only the channel column were included, the table would have only three rows (one for each of the three signals). Agilent ChemStore C/S Concepts Guide 113

114 4 Using the Report Template Editor Understanding Tables Compound Table The Compound Table may include fields with one value per injection, run, or compound. In addition, it may include peak and signal fields. However, the only peak values that will be included are those for the main peak for each compound result. This means that there will be only one value for, say, peak area associated with compound X in run 1. Similarly, the only signal information included in the Compound Table is from the signal associated with the main peak for the compound. The data model in this case looks like that shown in Figure 55. Note that only main peaks are shown, and they have a 1:1 relationship with both compound result and signal entries. Injections Runs Compounds Peaks Signals 1 X (1) X (2) 1,I,1.0 main 2,I,1.0 main I (1) I (2) 1 2 Y (2) Y (3) 2,II,2.0 main 3,I,2.0 main II (2) I (3) 2 3 Y (4) 4,I,2.0 main I (4) 4 Z (3) Z (4) 3,II,4.5 main 4,II,4.5 main continued II (3) II (4) Figure 55 Data Model for Compound Table In this example, there are three different compounds, but there are seven sets of compound results for the four runs (because some compounds are detected in more than one run), so the table may have up to seven rows, see Table 6 on page Agilent ChemStore C/S Concepts Guide

115 Using the Report Template Editor 4 Understanding Tables Table 6 Example of Compound Result Table Run No. Vial Cpd Name Cpd Amt RT Channel 1 10 X n.nnn DAD1 A, X n.nnn DAD1 A, Y n.nnn DAD1 B, Y n.nnn DAD1 A, Z n.nnn DAD1 B, Y n.nnn DAD1A, Z n.nnn DAD1 B,... As in the case of other tables, there may be fewer rows for the following reasons: The table is in a repeated section. There are data restrictions specified for the table element. No numeric or date/time columns are present and some rows would otherwise be identical. For example, if you include only the Cpd Name column, the table will have only three rows (one for each of the three compounds). Peak Table Like the Compound Table, Peak Tables may include fields with one value per injection, run, compound, signal or peak. Unlike peaks in the Compound Table, peaks in the Peak Table are not restricted to the main peak for each compound. That is, the table may contain information for all peaks, even those not associated with any compound. The data model in this case looks like that shown in Figure 56 on page 116. Agilent ChemStore C/S Concepts Guide 115

116 4 Using the Report Template Editor Understanding Tables Runs Compounds Peaks Injections 1 X (1) X (2) 1, I, 1.0 main 1, II, 1.0 qual 2, I, 1.0 main Signals Y (2) Y (3) Y (4)?? 2, II, 1.0 qual 2, I, 2.0 qual 2, II, 2.0 main 2, I, 3.0 unk 2, II, 3.5 unk I II 4 Z (3) 3, I, 2.0 main 3, II, 2.0 qual III Z (4) 3, III, 2.0 qual 3, I, 4.5 main continued Figure 56 Data Model for Peak Table In this example, there are eight peak entries just for the first two runs. If you were to create a Peak Table with exactly the same columns as the previous Compound Table example, the Peak Table would have many more rows, as shown below. Note that peaks not associated with a target compound have no amounts and have compound names like Unknown n. 116 Agilent ChemStore C/S Concepts Guide

117 Using the Report Template Editor 4 Understanding Tables Table 7 Example of Peak Table in a Report Run No. Vial Cpd Name Cpd Amt RT Channel 1 10 X n.nnn DAD1 A, X n.nnn DAD1 B, X n.nnn DAD1 A, X n.nnn DAD1 B, Y n.nnn DAD1 A, Y n.nnn DAD1 B, <Unknown 1> DAD1 A, <Unknown 2> DAD1 B, Y n.nnn DAD1 A, Y n.nnn DAD1 B, Y n.nnn DAD1 C,... As in the case of other tables, there may be fewer rows for the following reasons: The table is in a repeated section. There are data restrictions specified for the table element. No numeric or date/time columns are present and some rows would otherwise be identical. For example, if you included only the Cpd Name column, the table would have five rows (for the compounds X, Y, Z, Unknown 1 and Unknown 2). CAUTION When multiple channels of data are collected, the peak table can have more entries than any other table in the database and can consume significant amounts of resources (computer time and printer paper!). Agilent ChemStore C/S Concepts Guide 117

118 4 Using the Report Template Editor Understanding Tables Instrument Components Table In an Instrument Components Table, you can include columns with one value per run, injection or instrument components. Each run is associated with some single instrument, which is associated with possibly several components. Components Injections Runs Pump 1 Oven 1 FLD 1 DAD 1 Pump 2 DAD 2 VWD 2 1 Instrument I 2 Instrument II Figure 57 Data Model for Instrument Components Table If the above diagram represents the data we are dealing with, an Instrument Component Table would have a maximum of 14 rows (the four components of Instrument 1 are used for Injection 1 and runs 1 and 2; the three components of Instrument 2 are used for runs 3 and 4), as represented in Table 8 on page Agilent ChemStore C/S Concepts Guide

119 Using the Report Template Editor 4 Understanding Tables Table 8 Example of Instrument Components Table Component Name Injection No. Run No. Pump Oven FLD DAD1 1 1 Pump Oven FLD DAD Pump DAD VWD Pump DAD VWD The number of rows may be reduced by any of the three factors that apply to other tables mentioned earlier. Column Configuration Table This table works exactly like the Instrument Components Table, with column configuration information replacing the instrument components information (each injection may be associated with multiple column configuration entries). So the only columns you can include are injection, run, or column config fields. Agilent ChemStore C/S Concepts Guide 119

120 4 Using the Report Template Editor Understanding Tables Audit Trail Table In this table, you may include columns with one value per injection, run or audit trail entry. Each run entry is associated with one or more audit trail entries (one for each entry when you change the approval status or custom field values). Injections Runs Audit Entries Pending Pending Approved 2 3 Pending 4 Pending Approved Figure 58 Data Model for Audit Trail Table Table 9 Example of an Audit Trail Table Inj. No. Run No. Approval Status Audit Time 1 1 Pending 01-Apr-97 08: Pending 02-Apr-98 10: Approved 02-Apr-98 14: Pending 01-Apr-97 08: Pending 02-Apr-98 10: Approved 02-Apr-98 14: Agilent ChemStore C/S Concepts Guide

121 Using the Report Template Editor 4 Understanding Tables Generating a Report Using a Template When you have finished preliminary editing of a report template, you can preview the report that will be created using the template. Then, you can make any changes you need to make in the template without ever having left the Report Template Editor application. When you are satisfied with the template, then you can print the report. From within the ChemStore C/S application, you select the set of analysis results you want to report on by specifying a query, and then select the report template you want to use. Using Automatic Reporting ChemStore C/S allows automatic reporting after a sequence. After a sequence a sequence summary report can be generated based on the results of the current sequence. The reports are initiated via a DDE (Microsoft dynamic data exchange) link to ChemStore C/S. The Preferences dialog box of the ChemStore menu in the ChemStation Method and Run Control View allows you to set up the name and type of report for post-sequence. For the Post-Sequence report you can choose between any of the available ChemStore C/S reports (standard templates and your own customized templates). Agilent ChemStore C/S Concepts Guide 121

122 4 Using the Report Template Editor Understanding Tables 122 Agilent ChemStore C/S Concepts Guide

123 Agilent ChemStore C/S Concepts Guide 5 Data Security Introduction 124 Setting Up and Managing Users 127 Setting Up Organizational Information 131 Setting Up and Managing ChemStore C/S Elements 134 Managing Archiving and Dearchiving on Admin Client 151 Audit Trail 155 Notification 157 Validation and Security of Printed Files 161 Agilent Technologies 123

124 5 Data Security Introduction Introduction Data security and integrity is a major concern when an analytical laboratory is working under regulatory control, such as Good Laboratory Practice (GLP) and current Good Manufacturing Practice (cgmp) regulations. NOTE If you require the software to fulfill explicitly the GLP/GMP regulations, add the Security Pack G2183AA, available from your local Agilent Technologies supplier, to your ChemStore C/S installation. ChemStore C/S provides the following capabilities to fulfill these needs: Logging on to ChemStore C/S is password-protected; users must supply a valid password to start ChemStore C/S. In addition, many other activities that make changes to the database require the user to supply the user ID and password. ChemStore C/S uses a system of user permissions to prevent unauthorized users from executing management functions such as defining report layouts or deleting runs from the database. The user profile specifies the user s permissions; you can use one of the built-in user profiles or customize user profiles for each individual user. ChemStore C/S does not allow stored analysis results to be modified; they are protected. The user can change only the custom fields or the approval status of a record. All changes are documented in an audit trail. The client/server version of ChemStore C/S provides archive functions which allow you to archive your data when your project is completed and to restore them if you need to review them at a later date. In order to trace the transfer of the data, ChemStore C/S provides an audit trail that records the following events: additions to the database (analysis runs), changes to the custom fields, changes to the approval status of a run, adding to or deleting from a batch changes to the archive status of a run. 124 Agilent ChemStore C/S Concepts Guide

125 Data Security 5 Introduction Both the ChemStation and ChemStore can be locked while they are running, to prevent tampering by an unauthorized person. The lock-out may be Private, when either the current user s or an Administrator s user ID and password must be supplied to unlock the session, or Non-Private, when any valid user ID/password combination is sufficient to unlock the session. Security ChemStore C/S provides two levels of security to prevent unauthorized access or use of the database. The first level of security is the password protection, which prevents unauthorized access; the second level of security is through user permissions, which restrict the available facilities to authorized users. Passwords and user permissions are not global; they are configured individually for each ChemStore C/S database. Password Protection ChemStore C/S is password-protected; in order to start ChemStore C/S, the user must supply a valid password. Several other activities within ChemStore C/S also need password verification in addition to user permission, for example: changing to a different user changing passwords editing custom fields reopening a previously-archived run deleting a run archiving and dearchiving runs approving and rejecting runs NOTE For reasons of security, we recommend that you change the default user passwords after installation of ChemStore C/S. See Server Change default Passwords in the ChemStore C/S Installation Guide. Agilent ChemStore C/S Concepts Guide 125

126 5 Data Security Introduction Password Settings A number of conditions apply to the validity and longevity of passwords. The administrator can specify the values for these conditions. Minimum length Password validity Minimum password recycle Retries before rejection This is the minimum acceptable length (in characters) of a password. Passwords shorter than the minimum length are invalid and are rejected by ChemStore C/S. The default minimum password length is 8 characters. This is the length of time (in days) over which the password remains valid. The password expires after the specified validity, and a new password must be provided. The default validity is 90 days. This is the minimum number of new, unique passwords that a user must use before a password can be re-used. The default value is 12, which means that a user must change the password at least 12 times before re-using the original password. This is the permitted number of consecutive unsuccessful attempts that a user can enter before ChemStore C/S rejects the user. The default value is 3. If the maximum number of retries is exceeded the current password is invalidated. 126 Agilent ChemStore C/S Concepts Guide

127 Data Security 5 Setting Up and Managing Users Setting Up and Managing Users Many of the facilities of ChemStore C/S are safeguarded from modification by unauthorized personnel by applying a set of user permissions. Each ChemStore C/S user is granted permission to perform certain tasks. Individual users can be granted different sets of permissions depending on each laboratory s business needs and each user s job requirements. A ChemStore C/S user is someone who has been registered in ChemStore C/S with a user log-on name, a user display name, which is shown in audit trails and other reports, a password and a set of permissions. The set of permissions identifies the ChemStore C/S facilities that are available to the user. Only an Administrator, or a user with the relevant permissions, can set up a new ChemStore C/S user. To assist in configuring user permissions for new users, four standard user profiles are provided: Operator Chemist The Operator is the basic user. The Operator can retrieve data from the database, but has no permission to make changes to the ChemStore C/S configuration. Permissions: Create batch only. The Chemist can change the approval status of retrieved data, and can change the values of custom fields. Chemists can also save their user interface settings and, in the client/server version, can archive/dearchive and retrieve files. Permissions: Archive/dearchive runs, First level approval, Create batch, Create/edit queries, advanced filters, calculation and report templates. Define columns/expressions, Edit/save settings. Agilent ChemStore C/S Concepts Guide 127

128 5 Data Security Setting Up and Managing Users Lab Manager Administrator The Lab Manager has all the permissions of the Chemist and, in addition, can create and modify studies and custom fields. The manager is permitted to approve runs on a 2nd level and to change the data reload configuration. The lab manager also has the ability to allocate ChemStore C/S settings to other users, and to delete runs. Permissions: All except Admin client test mode (a special diagnostic and maintenance mode), Administer DB server, Administer users (see Table 10 on page 128), Assign studies to users, define the approval configuration, perform database migration or compact a stand-alone database. The Administrator has the same permissions as the Lab manager, but in addition has the ability do administer users, Assign studies to users and, in the client/server version, to administer the ChemStore C/S server and perform database migration. Permissions: All (see Table 10 on page 128). Users can be set up using one of the four standard user profiles, but individual permissions may be granted or refused, to give each user a custom set of permissions. The permissions contained in the templates provided are shown in Table 10. NOTE In case Security Pack is installed, permissions for tasks like pausing the spooler, deleting spool jobs or pre-selecting a database are handled on the operating system level. The standard operation of the software should be performed by a member of the Windows user group users. See also ChemStation Plus Security Pack User s Guide. Table 10 User Permissions Templates Permission Operator Chemist Lab. Manager Admin client test mode Administer DB server Administrator Yes Yes Administer custom fields Yes Yes Administer users Yes Administer user settings Yes Yes Assign studies to users Yes Archive/de-archive runs Yes Yes Yes 128 Agilent ChemStore C/S Concepts Guide

129 Data Security 5 Setting Up and Managing Users Table 10 User Permissions Templates (continued) Permission Operator Chemist Lab. Manager Administrator 1st level approval Yes Yes Yes 2nd level approval Yes Yes Create/edit queries Yes Yes Yes Create/edit advanced filters Yes Yes Yes Create/edit report templates Yes Yes Yes Create/edit calculator templates Yes Yes Yes Create/modify study Yes Yes Define columns/expressions Yes Yes Yes Delete runs Yes Yes Edit custom field values Yes Yes Yes Reopen runs Yes Yes Create batch Yes Yes Yes Yes Compact database (standalone only) Yes Edit/save settings Yes Yes Yes Migrate database Yes No permission is needed for the following tasks: Storing results in the database. Retrieving and reviewing data using saved queries to which the user has been granted access. Accessing any user setting (query, filter, report template or user interface setting) that is not controlled by security permissions or that the user owns or has been granted access to. Reloading raw data files, methods files or sequences files to the ChemStation requires the Create batch permission. Agilent ChemStore C/S Concepts Guide 129

130 5 Data Security Setting Up and Managing Users Deactivating Users An Administrator (or other user with the permission to administer users) can deactivate any registered ChemStore C/S user. Deactivated users cannot log on to ChemStore C/S. 130 Agilent ChemStore C/S Concepts Guide

131 Data Security 5 Setting Up Organizational Information Setting Up Organizational Information Only users with the requisite permissions can set up and manage Studies and Custom Fields. For standard user profiles, only Lab Managers and Administrators have the requisite permissions. Setting Up and Managing Studies A study may only be created or modified by an Administrator, Lab Manager or other user with the requisite permission. A new study can be created from scratch, or can be based on an existing study. During the creation of the study, the creator identifies the items (chromatograms, spectra, raw data, method and sequence information) that will be stored by ChemStore C/S along with the results, and specifies the custom fields to be associated with the study. All custom fields that have been created for other studies and have not been deactivated are available for inclusion in the new study. Any new custom fields for inclusion in the study can also be specified at this time (see Setting Up and Managing Custom Fields on page 132). Irrespective of whether the custom fields included in the study are newly-created or already existing, the values in the custom field are unique to the runs in the study. Once the study has been set up, users are either granted or denied access to that study depending on the study assignments (see Assigning Studies on page 133). Users who have been assigned to the study may add data into the study and retrieve runs using the study name as a search criterion. When creating a new study, a user with sufficient privileges also has the option to change the approval mode, run lock mode and LIMS notification mode. Studies can be given the status Active or Inactive by a user with the requisite permission. An active study is available for all activities of the ChemStation and ChemStore C/S. An inactive study is no longer available to the ChemStation for adding data into. It is still available in ChemStore C/S for retrieving data, but is not available for use as a template for a new study or for modification. Agilent ChemStore C/S Concepts Guide 131

132 5 Data Security Setting Up Organizational Information Setting Up and Managing Custom Fields Only an Administrator, Lab Manager or other user with the requisite permission may create or modify custom fields. The creation of a custom field requires the provision of a name and the specification of the data type (see Using Custom Fields on page 21); for some data types, additional information (units, a list of possible values) is also necessary. A newly-created custom field is available for inclusion in any study. Data Entry for Custom Fields Part of the specification of the custom field is the method of data entry. Custom field values can be entered automatically (by a ChemStation macro) or manually. Manual data entry can be specified as always required, when a valid value must be entered in the field before the transfer of the analysis results to ChemStore C/S is allowed. If a value is not always required, a default value may be specified; this default value can be overwritten prior to data transfer. In addition, data masks can be specified for some field types: maximum and minimum values for numeric fields, maximum string lengths for text fields. These data masks are specific to the study; if the custom field is used in other studies, its data masks can have different specifications. If the data is to be entered into the custom field automatically, using a ChemStation macro, you must ensure that the macro returns the correct data type (in accordance with the custom field specifications) the macro is loaded in the ChemStation For more details on macros, refer to the ChemStation on-line help on Commands. Custom fields can be given the status Active or Inactive by a user with the requisite permission. If the status of a custom field is changed to inactive, it becomes unavailable to all ChemStation and ChemStore C/S activities except use as a query criterion. 132 Agilent ChemStore C/S Concepts Guide

133 Data Security 5 Setting Up Organizational Information Assigning Studies Only users who are assigned to a study will have access to that study. The assignment of studies to users can be done either during study creation and modification or through a separate interface where all study assignments can be edited. Users will only be able to access studies that are assigned to them within the ChemStore and ChemStation software interfaces. This protects studies from being modified, accessed or have inappropriate data added by unauthorized users. Assigning a limited number of studies to each user also makes the software easier to use, as fewer studies and options are shown to the user. A specific user permission Assign Studies to Users is required to make study assignments. Agilent ChemStore C/S Concepts Guide 133

134 5 Data Security Setting Up and Managing ChemStore C/S Elements Setting Up and Managing ChemStore C/S Elements Five major elements of the ChemStore C/S configuration can be saved and later reopened; these elements can also be specified for use by other ChemStore C/S users, even when they do not have the requisite permissions to create or save the elements. This setup limits data access to predefined data sub-sets. The creator of the element is assigned as the owner, but ownership can be transferred to another user by a user with the requisite permission. Queries Filters Report templates User Interface Settings Calculation templates Queries can be saved with a name for later re-use; saved queries can be allocated for other users to use. Custom filters can be saved with a name for later re-use; saved custom filters can be allocated for other users to use. Report templates can be saved with a name for later re-use; saved report templates can be allocated for other users to use. User interface settings include all current configurations of all windows, tables and charts. these settings can be saved with a name for later re-use; saved user interface settings can be allocated for other users to use. Calculator templates can be saved with a name and version number for later re-use; saved calculator templates can be allocated for other users to use. The allocation of a calculator templates affects all versions with the same name. In addition to allocating ChemStore C/S elements for use by other users and transferring ownership to other users, a user with the requisite permission can rename a saved element. Elements can also be modified by a user with the requisite permission and resaved either with a new name or with the same name, in which case the original element is overwritten. 134 Agilent ChemStore C/S Concepts Guide

135 Data Security 5 Archiving and Dearchiving Archiving and Dearchiving The client/server version of ChemStore allows you to archive (copy and save) runs present in the database to a separate file on disk or tape. After the runs have been archived, you can automatically delete the runs from the ChemStore C/S database, to free up space in the database. Before you can archive, dearchive or reopen a file, your administrator must give you permission to do so. Your administrator also sets up and manages certain archive functions through the ChemStore C/S Admin Client. See the section Managing Archiving and Dearchiving on Admin Client on page 151. If you have not deleted runs after archiving, you can still access the runs on the database, although you cannot modify (e.g., approve) them unless you reopen them first. Before you can reopen a deleted run you must dearchive and restore it to the database. Archiving, deleting, dearchiving and reopening act on all versions of a run. If multiple versions of a run exist, all versions are archived - even if they are distributed over different studies. Similarly, if you specify to automatically delete the runs after archiving, all versions of the run are deleted. ChemStore C/S provides two modes of archiving: automated and interactive. Automated Archiving A user with administrator permissions can set up to archive specified runs automatically at regular intervals. The runs to be archived are selected by a query. To set up new archive queries the user has to select Automated Archiver from the administration menu of the Review Client. The archive query section allows to enter information similar to the Create Archive Unit-dialog used for manual archiving. A name for the archive query has to be specified (mandatory and unique) as well as the name of the archive unit and the path. The archive unit name is extended with creation date, i.e. <filename>-yyyy-mm-dd. Agilent ChemStore C/S Concepts Guide 135

136 5 Data Security Archiving and Dearchiving The checkbox Active allows to enable an archive query. The archive query will be shown as 'active' in the list of automatic archive queries. If the checkmark is removed, the query will be disabled showing a status inactive. Optionally runs can be deleted from the database after they have successfully been archived. The query criteria include items such as injection time, instrument name, operator name, acquisition sequence name, method name, sample name, study name, custom fields, injection operator, approval status and so on. Operands depend on the data category and can be negated with NOT. 136 Agilent ChemStore C/S Concepts Guide

137 Data Security 5 Archiving and Dearchiving Figure 59 The Automated Archives dialog box Text based data: is equal, contains (wildcards) Numeric data: is equal, is greater than, is lower than, is between Date : is older than X days/months For optimum performance, the number of clauses that can be defined for automated archives is restricted to 10. Agilent ChemStore C/S Concepts Guide 137

138 5 Data Security Archiving and Dearchiving An individual frequency for the archival can be set for each archive query. The time interval can be configured, e.g. daily, weekly, monthly or in conjunction with a counter (every x days, weeks etc.). A First starting date when the query should be executed on the server has to be entered. The user must authenticate and confirm the creation or editing of an archive query with UserID and password, similar to the create archive unit dialog for creating manual archives. The button Test Query provides information of how many runs the query currently returns with the given query condition. When an archive query is enabled it will run automatically for the first time as defined through the 'first starting date. The following archives will be created according to the specified time interval. 138 Agilent ChemStore C/S Concepts Guide

139 Data Security 5 Archiving and Dearchiving Archiving Interactively The users have also the option to select runs for archiving from the Archive/Delete view or graphics layout of the main ChemStore panel. Figure 60 Archive/Delete View of the main ChemStore panel Note that the Archive icon is depressed, rather than the Sample Review icon. Agilent ChemStore C/S Concepts Guide 139

140 5 Data Security Archiving and Dearchiving The Archive/Delete view contains a similar toolset to the Sample Review graphics layout with the exception of the following three icons: Enables you to specify where and when your archive unit will be stored. Deletes all runs marked in the run list for deletion. This button is also present in the Delete view of the stand-alone version. Reopens all runs marked in the run list for reopening and sets their approval status to Approval Pending (see Run Approval Status on page 29). See Sample View on page 36 for more information on the Sample Review graphics layout. You select the runs for archiving from the run list in the left panel of the Archive/Delete view, just as you would search data for reviewing or reporting in the Review view. Runs marked for archiving are protected from any further modification of approval status or custom field values. Since archiving can be postponed to a suitable time (for example, during non-working hours), runs marked for archiving are stored in a dataset until archiving has been completed. In principle, manual archiving jobs do not interfere with automatically triggered ones. It operates on a first in - first served basis. A run that is scheduled for archiving in two separate jobs will be archived by the first job in the queue. Figure 61 Create Archive Unit Panel 140 Agilent ChemStore C/S Concepts Guide

141 Data Security 5 Archiving and Dearchiving Archive units Archived runs are stored as archive units; an archive unit contains all versions of the specified runs. The archive unit is created either automatically or manually, as described above. When you set up the archive unit, you specify a file name and a path, and you can also add a description of the archive unit. These items can be used later to search for a specific archive unit. When ChemStore C/S creates the archive unit, it attaches a system-generated archive ID and a catalog file in XML format describing the contents of the binary archive unit. The file name corresponds to the name of the archive unit with the extension XML. Figure 62 on page 141 shows an example of an XML catalog file. Figure 62 An example of an XML catalog file For enhanced archive management, for example in external document management systems (DMS), this catalog file can be used for indexing. Agilent ChemStore C/S Concepts Guide 141

142 5 Data Security Archiving and Dearchiving Archiving is protected by user permission and password. The Archive/Delete view as well as the Automated archives menu item are available only to users with the correct permissions. To submit an archiving job the user must enter the user ID and password. Deleting Runs If there is no Security Pack for ChemStore C/S installed, it is possible to delete runs without archiving first. In the Delete view of the stand-alone version, and in the Archive/Delete view of the client/server version, you can mark runs explicitly for deletion. Data security is ensured by allowing only users with the required permissions ( Setting Up and Managing Users on page 127) to perform this task, and by requiring password-protected confirmation that the runs are to be deleted. In the client/server version, it is also possible to automatically delete runs from the database after they have been archived. CAUTION Runs that you delete are removed from the database and cannot be retrieved. Be sure that you only delete runs that you have already archived or no longer need. Reopening Runs Runs that have been archived but not deleted are still in the database, but they are locked and cannot be modified. You can reopen archived runs for access by selecting them for reopening from the run list in the left panel of the Archive/Delete view and then clicking the Reopen icon described on the previous page. Like archiving, reopening is available only to users with the correct permission. 142 Agilent ChemStore C/S Concepts Guide

143 Data Security 5 Archiving and Dearchiving Dearchiving Runs Runs that have been archived and deleted are no longer in the database. In order to access archived, deleted runs, you must first dearchive them (copy the runs back into the database) and then reopen them. You can dearchive a complete archive unit, or you can select one or more runs to dearchive from within the archive unit. To select an archive unit for dearchiving, you use the Archive History, which displays all archive units in chronological order of creation. Because you may have many archive units in the database, making it difficult to find the one containing the required run(s), a search facility is available to allow you to search the list of archive units for the required one. You can specify that dearchiving, like archiving, begin immediately (within the wake-up interval of the server); alternatively you can postpone dearchiving until a later time. Dearchiving copies all versions of the selected run in the archive into the database. Dearchiving is protected by user permission, user ID, and password. Only users with the required permission have access to the Archive/Delete view, and the user s ID and password must be entered before dearchiving will begin. Generic XML Archive Interface In addition, a generic XML-based archive interface can be optionally added to the ChemStore C/S server. It allows to implement a linkage to external archive management systems (DMS, HSM etc.).the archive interface is installed from the directory \G1410a\archiver_interface on the ChemStation Plus CD-ROM. Please refer to the readme.txt for installation details. In case it is installed, ChemStore C/S notifies the generic XML-based archive interface every time an archive unit is created. The name and location of the archive unit and the corresponding XML file is passed on to the default plug-in. Depending on the nature of the plug-in, different activities, such as the transfer of the archive unit to a DMS followed by local deletion, can be started. After successful processing of the archive unit a notification message with an external ID for the storage location can be reported back to the generic XML-based archive interface, which sends this information to ChemStore C/S. Agilent ChemStore C/S Concepts Guide 143

144 5 Data Security Archiving and Dearchiving A prerequisite for using the generic XML-based archive interface is the development of a plug-in. On request Agilent supplies a developer's kit with the necessary information to program such a plug-in. A simple example for a plug-in comes along with the installation of the XML Archive Interface and it needs no further configuration. The simple plug-in triggers a dialog box popping up on the server PC each time a new archive file has been created. Figure 63 Message generated by simple plug-in of generic XML-based archive interface The message and function of the simple plug-in can be changed by modifying the file AddArchive.cmd in the simple plug-in folder ("C:\Program Files\ Agilent Technologies\XML-based Archive Restore\Examples\Simple Plugin"). A schematic overview of the data flow with the simple plug-in and the potential extension with a customized plug-in is given in Figure Agilent ChemStore C/S Concepts Guide

145 Data Security 5 Archiving and Dearchiving scheduled archiving generic archive interface Simple Plug-In DMS or HMS plug-in Review Client Oracle database dearchiving archive unit + XML file archive unit + XML file manual archival (e.g. on tapes/ CDs/DVDs) DMS or HMS DMS or HMS plug-in generic archive Interface Figure 64 Generic XML-based archive interface Restoring has to be done manually first by putting the binary archive file back to its old location and then by means of ChemStore in the same way as in previous revisions of ChemStore. Understanding Archive Status When a run is transferred from the ChemStation to ChemStore C/S, it is given the archive status Never Archived. A run that has been selected for archiving is given the archive status Archive Pending and is locked against further modification. If deletion after archiving has been specified, the run is given the status Archive Delete Pending. This status prevents runs being retrieved by queries. The statuses Archive Pending and Archive Delete Pending apply until the archive has been completed, when the run s archive status is changed Agilent ChemStore C/S Concepts Guide 145

146 5 Data Security Archiving and Dearchiving to Archived for a completed archive operation. For Archive Delete operations, the archiving and delete information is only available from the archive unit interface in the admin client application. NOTE Archive status is not automatically updated; you must refresh the status by conducting another query on the runs of interest to update archive status. If the archive fails perhaps because the storage medium filled before the archive was complete the runs are given the status Archive Failed. In such a case, your administrator must use the Admin Client to solve the problem and reschedule the archive. A run that has been archived but not deleted that is, it remains in the database is locked against any change, such as a change to its approval status or to a custom field value, until the run is explicitly reopened. Then it is given the status Reopened. Reopened runs may be archived again in the normal way. Certain rules exist for determining the status of a run when you dearchive runs to the database. If the run no longer exists in the database, then the following rules apply: If you attempt to dearchive the last archive created, the run is transferred to the database and marked Dearchived. If the run was archived multiple times and you attempt to dearchive an archive that is not the most recent run, the run is transferred to the database and marked Read-Only. If the run exists in the database after an actual delete and dearchive process, then the following rules apply: If you attempt to dearchive the most recent archive the run will be transferred to the database and have the status dearchived If you attempt to dearchive an archive dated that is not the most recent one, the run will be dearchived and marked read-only.if you dearchive as a next step a more recent but not the latest run version, the older dearchived run will be overwritten and all runs get the status read-only.in case you try to dearchive older versions of the run than those that are already dearchived, the application will not allow to dearchive these runs or to overwrite runs in the database 146 Agilent ChemStore C/S Concepts Guide

147 Data Security 5 Archiving and Dearchiving If the run still exists in the database and has not been restored from an archive unit so far, the application will not allow to dearchive or overwrite an existing run in the database. You can find a listing of the runs that were overwritten or not overwritten for the last dearchive operation of an archive unit in the Archive Reports/View of the admin client. This information is also written to the server log file. The relationships between the archive statuses are shown in Figure 65. See also the topic Taking a Closer Look at the Archive/Dearchive Process in this section for a specific example of how the archiving and dearchiving process affects the status of the run. Never Archive Select for Archive Archive Pending Archive Archive Dearchive (if deleted) Archive Reopen (if not deleted) De- Archive Reopen Reopened Figure 65 Archive Status Relationships Reviewing Archive Status and Reports To see the schedule of pending archives and dearchives, look under the Review menu at the top of the main panel of the Archive/Delete view (see Figure 60 on page 139). You can review the history of an archive from the same menu and assess why an archive or dearchive may have failed. Automated archives are not listed in the schedule of pending archives because automatic archive queries are directly executed at the specified date and time. You can also view the archive schedule and history from the Admin Client panel. Any user can view these reports without needing a password to access them on the Admin Client. You can also view the following additional reports through the Admin Client: Archive Units Runs in an archive unit Runs to be deleted Agilent ChemStore C/S Concepts Guide 147

148 5 Data Security Archiving and Dearchiving Audit Trail Information for an object Base path, wake-up interval and time-out interval Active spool/download table Taking a Closer Look at the Archive/Dearchive Process An example may provide a deeper understanding of the archive/dearchive process. Example The following example shows two figures: Figure 66 on page 149 represents the steps in the process of archiving a run to several archive units. Figure 67 on page 150 is an example of the dearchive process when the run is no longer in the database based on Figure Agilent ChemStore C/S Concepts Guide

149 Data Security 5 Archiving and Dearchiving Database Archive Status for Run10 Tape/Disk Archive Unit ID Never Archived Select for archive Archive Pending Archive at specified time ID1 (12/3) Reopened (Changes Made 12/6) Reopen Archived Archived Archive Archive Again/Delete ID2 (12/7) ID3 (12/11) Database no longer contains run10 Figure 66 Example Archive Process Agilent ChemStore C/S Concepts Guide 149

150 5 Data Security Archiving and Dearchiving Database Tape/Disk Archive Status for Run10 Archive Unit ID Database no longer contains run10 Read Only Dearchive run10 (12/12) ID1 (12/3) Read Only Dearchive run10 ID2 (12/7) If you attempt to dearchive run10 in the archive units dated earlier than the most recent one, the runs are transferred to the database but given the status of Read Only. Dearchived Dearchive run10 ID3 (12/11) Since ID3 is the most recent archive unit, run10 will be dearchived and available for reopening on the database. Figure 67 Example Dearchive Process Run10 no longer on database 150 Agilent ChemStore C/S Concepts Guide

151 Data Security 5 Managing Archiving and Dearchiving on Admin Client Managing Archiving and Dearchiving on Admin Client Administrators may perform certain setup tasks on ChemStore C/S Admin Client before users with the correct permissions archive or dearchive runs. ChemStore C/S Admin Client is a web-based application that you can use from any PC on the network to easily manage the archive and dearchive functions and other server processes. Admin Client communicates with the Archive Server running as an NT service on the server computer. You access Admin Client using a web browser. You can perform the following tasks through Admin Client: schedule archive, dearchive and delete operations modify scheduled operations view reports detailing pending operations review archive and dearchive history view information about archives, runs and other objects execute archive, dearchive and delete operations immediately set server operational parameters such as wakeup interval connect the Archive Server to Oracle add and modify database connection information See the online help for Admin Client for more information on how to use these administrative functions. See the section Archiving and Dearchiving on page 135 for details on the concepts behind archiving and dearchiving with the ChemStore C/S software. Agilent ChemStore C/S Concepts Guide 151

152 5 Data Security Managing Archiving and Dearchiving on Admin Client Overview of the Archive/Delete Process The Admin Client helps manage the archive process taking place on the archive server. Below are listed the steps involved in archiving and deleting a run. 1 Using a function inside of ChemStore C/S itself, a user specifies which runs in the database to archive and sets a time to archive them. These runs are placed in Archive Tables that are used exclusively by the archive server. The operation and the scheduled time are placed in the Schedule Table. 2 When the server wakes up next, it checks the Schedule Table to determine if there are any pending archive requests. If there are, the system checks the integrity of the requests; for example, runs can be archived only in certain status states. 3 If a run is determined valid to archive, then the data is written into a binary file (in the directory specified by the base path variable). In addition to writing the data from a run in the archive file, all data about related objects, such as the method and raw data, are also written to the binary file. If there is a failure during this part of the process, the archive is marked as Failed in the Archive Tables and deleted from the Schedule Table. 4 When the server is finished writing data to the binary file, it goes back to the database to mark every archived run for Delete, if the archive includes the AutoDel flag set to TRUE. 5 The delete operation runs automatically after a successful archive. Administrators can use ChemStore C/S Admin Client to schedule a run delete operation manually at any time. 6 When the delete operation runs, all runs marked for delete during archive or manually from ChemStore C/S are deleted. 152 Agilent ChemStore C/S Concepts Guide

153 Data Security 5 Managing Archiving and Dearchiving on Admin Client Performing Archive/Dearchive Tasks on Admin Client The tasks listed at the beginning of this section are divided into five groups. There are archive reports, archive tasks, server control, global configuration options and test functions. Administrators must log on to the Admin Client with a user name and a password to perform archive, server control or testing tasks. Any user with access to the network can view archive reports without logging on to the Admin Client. You access the tasks under these groups from the main web page for Admin Client. Figure 68 Main Web Page for Admin Client Agilent ChemStore C/S Concepts Guide 153

154 5 Data Security Managing Archiving and Dearchiving on Admin Client Once you have accessed the main web page for Admin Client, you can access the task depending on your permissions. Most of the views and reports have the following format: Figure 69 Archive Server History Report 154 Agilent ChemStore C/S Concepts Guide

155 Data Security 5 Audit Trail Audit Trail The Audit Trail tracks all changes that are made to a run. Each sample has an Audit Trail which is maintained separately from the sample data. The Audit Trail is not archived with the run, so that archiving and dearchiving activities can be added to the Audit Trail; the link to the Audit Trail is maintained, even when the run is archived. Activities that give rise to an entry in the Audit Trail are: changes to custom field values changes to approval status changes to the sample name changes to reprocessing status adding to or deleting from a batch changes to archive status The Audit Trail for any run can be displayed; it contains a table showing a summary of all the changes made to the run, who made the change and when (see Figure 70 on page 156). Buttons are available to display additional information on changes to custom field values and archive status. Agilent ChemStore C/S Concepts Guide 155

156 5 Data Security Audit Trail Figure 70 Audit Trail 156 Agilent ChemStore C/S Concepts Guide

157 Data Security 5 Notification Notification The following facility is available on Client/Server systems only. It sends an automatic notification on specific events and needs to be set up by the administrator (or other user with administrator permissions). The events to trigger an automated notification are: locking of an user account due to exceeded number of unsuccessful log-on attempts. submitting a batch for review clearing a password creation of a new user permission modification With the exception of 'notification of batch submission', the notifications should only be sent to administrators to warn about security violations. The operation of notification requires a working server. The mail can be sent in two ways: By anonymous SMTP to a mail server. In this case, the mail server must be configured to allow anonymous SMTP. For increased security, the mail server can add the IP address of the ChemStore database server to its trust list, and allow anonymous SMTP only from trusted servers. Using LDAP For this purpose, the SMTP virtual server from the Windows 2000 server, which has LDAP routing capability, can be used. The notification is then sent via LDAP to the mail server. This requires an existing account on the mail server that is used to send the mail; this account is then the originator of the mail. Agilent ChemStore C/S Concepts Guide 157

158 5 Data Security Notification Figure 71 The Notification dialog box The Notification Setup dialog box, shown in Figure 71, contains settings for the server connections, and the addresses of the recipients of the notification. A default subject e.g. Account locked can be edited, and additional text can be added. The notification message contains the date and time of the intitiation of the message, the user ID of the affected user and the ChemStore client details, as well as the additional text specified during setup. A test mail function allows to verify the successful setup of this function. 158 Agilent ChemStore C/S Concepts Guide