Synopsis
DF_QCupdate
{study}
[
[-o]
| [-d #, #-#]
| [-s]
| [-last]
]
[-t yyyymmdd]
Description
DF_QCupdate applies the visit scheduling and CRF page requirement rules that have been specified for the study.
What does DF_QCupdate do? .
- DF_QCupdate adds queries to identify overdue visits and missing CRF pages.
-
DF_QCupdate removes these same queries when they are no longer relevant,
because the CRF pages have arrived in the database,
a missed visit plate has arrived,
the CRF plates have been registered as missed,
or because the visit requirements have been changed in the study setup.
DF_QCupdate does not add or remove any other queries, i.e. those added
by users or edit checks.
Code 23 EC missing page queries added by the
dfaddmpqc()edit check function are not removed or replaced by DF_QCupdate. - DF_QCupdate updates existing overdue visit queries if there has been any change in the scheduled target date for the visit, or the visit label specified in the visit map.
- DF_QCupdate creates a DFdiscover retrieval file listing any CRF pages which exist in the study database but that should not be there, e.g. a follow-up that was not expected because the subject died before it was due.
- DF_QCupdate creates summary files, in the study work directory, that are read by other programs that need to know the current status of subject follow-up, including visits and CRF pages completed, scheduled, overdue, missing and unexpected.
How does DF_QCupdate know what visits and CRF pages are expected? . Visit scheduling rules and CRF requirement rules are entered in the study setup tool where the dates that represent subject visits are identified using the VisitDate attribute, and input GUIs are provided for:
- a visit map which shows all study visits, their type (e.g. baseline, follow-up, termination, etc.), when they are due and what CRF plates are required and optional. The visit map allows visits to be grouped into one or more cycles or related visits, e.g. a screening cycle, 1 or more in-study treatment and follow-up cycles, and a cycle consisting of unscheduled event reports.
- a conditional visit map to identify visits that become required, optional or unexpected when a specified condition is met
- a conditional cycle map to identify visit cycles that become required, optional or unexpected when a specified condition is met
- a conditional plate map to identify CRF plates that become required, optional or unexpected when a specified condition is met
- a conditional termination map to identify visits at which follow-up is terminated, either just for the current visit cycle, or for all cycles, when a specified condition is met
A full description of these specifications and how they are used can be found in DFsetup Study Setup User Guide, Conditional Tests
How does DF_QCupdate know whether expected visits and CRF pages have arrived?
.
DF_QCupdate launches DF_XXkeys which exports the key fields and visit dates
from all records in the study database having status
final, incomplete, lost or pending.
It also exports all of the trigger fields used by the conditional cycle,
visit, plate and termination maps, from these records.
Data records with status pending are not exported
or used by DF_QCupdate in any way since the key fields on these data
records are by definition unreliable.
Thus pending records will never be counted among the
records that have arrived in the database, or be used to trigger a condition.
While it might be argued that records saved with pending in DFexplore
should also be considered unreliable, if we ignored these records missing page
and overdue visit queries would be created for records that are clearly underway,
the visit dates on these records would not be available for scheduling the next
visit, and conditions used to identify required cycles, visits and plates would
not be triggered. While pending records might include some errors which have
not yet been corrected this is also true of incomplete records. Thus on balance
we have decided that it is better to include these records than to exclude them.
When should I run DF_QCupdate? . DF_QCupdate should be run before you run any of the programs that depend on the summary files it writes to the study work directory, or that depend on the Query database being up to date with regard to overdue visit and missing page queries. In some cases you may not care if the summary files and Query database have not been updated within the last few hours or days, and in other cases you may need them to be more current.
Which programs and reports depend on DF_QCupdate? .
- DF_QCreports is used to create the Query Reports sent to each participating clinical site, showing the first, last and next scheduled visits, and all unresolved data queries, including those for overdue visits and missing pages. It is particularly important that these reports be accurate, otherwise you risk mis-informing and upsetting the clinical sites. When creating external Query Reports, to be sent to the clinical sites, DF_QCreports checks to see if DF_QCupdate is running and stops with a warning message if it is. This ensures that these reports will not contain old information which is in the process of being updated.
- DFexplore reads the Query database and reports the number of queries of each type (including overdue visit and missing page queries).
- DF_PTvisits, which is used to create reports showing visit scheduling information depends on summary files created by DF_QCupdate.
- DF_CTqcs creates reports showing the number and status of queries for each clinical site by reading the Query database
- DF_PTcrfs lists the CRF pages received and missing for each visit. Missing CRF pages are determined by reading the Query database.
Are there any restrictions on who can run DF_QCupdate or when it can run? .
- Only users with full permissions (e.g. no restrictions) can run DF_QCupdate. The user must have full permissions on Data, Queries and Reasons at all levels (0-7).
- If you try to run DF_QCupdate when it is already running you will receive an error message indicating that DF_QCupdate is already in progress.
- DF_QCupdate can be run while data entry is being performed. However, users should be aware that the update will only be accurate with regard to the state of the database when DF_QCupdate was started.
- When the study server is in read-only mode, it is not possible to make changes to the Query database. DF_QCupdate checks the study server access mode and exits with an abort message if the server is in read-only mode.
What summary files does DF_QCupdate create? . In addition to updating the Query database with respect to overdue visit and missing page queries, DF_QCupdate also creates a number of summary files, which are stored in the study work directory, and described in the programmers manual. As a first step DF_QCupdate runs DF_XXkeys to identify the visits that have been completed and the CRF pages that have been received for each subject. This step results in the creation of:
- DFX_keys - all required plates received at each visit for each subject
- DFX_visit.dates - all visit dates recorded for each subject
- DFX_visit.date - one visit date for each visit (preferred or available)
- VDillegal.drf - a DFdiscover retrieval file listing all illegal visit dates
- VDincon.drf - a DFdiscover retrieval file listing all inconsistent visit dates
Next, DF_QCupdate reads the conditional maps and creates a summary file containing a record for each condition that was met for each subject:
-
DFcvisit_map- conditional visit map -
DFccycle_map- conditional cycle map -
DFcplate_map- conditional plate map -
DFcterm_map- conditional termination map
DF_QCupdate then compares the data exported from the study database to the files listed above with the study visit map rules and generates overdue visit and missing page queries which it imports into the study database. These queries are distinguished from the queries created by users by the category stored in in each query (21 for missing page queries, and 22 for overdue visit queries). DF_QCupdate will not create a code 21 query for a missing CRF page if a code 23 query (i.e. a missing page query created by an edit check using function dfaddmpqc) already exists in the study database. In addition to creating new queries DF_QCupdate also deletes any old code 21 and 22 queries that are no longer relevant, and updates any old code 21 queries for which the plate label has been modified, and any old code 22 queries for which the visit label or visit date have been modified. In addition to creating, deleting and updating code 21 and 22 queries, DF_QCupdate generates the following summary files which remain in the study work directory:
-
DFX_schedule- all completed and scheduled visits for each subject -
DFX_studydates- all unique visit dates and their Julian values (days since Jan 1,1900) -
DF_QCupdate.log- a summary of results from the last execution of DF_QCupdate - - a DFdiscover retrieval file listing unexpected CRFs received
How are DF_QCupdate and Schedule View related? Schedule View, in DFexplore, is quite similar to DF_QCupdate in its goals. Both report the visit schedule information for study subjects and identify missing pages and overdue visits. The schedule information presented by both is the same. However, the manner in which the information is generated and maintained differs in several important ways:
The results calculated by DF_QCupdate are static - they are correct at the time that the report is run and then slowly age until refreshed when DF_QCupdate is run again. The results in Schedule View are always up-to-date each time that the Schedule View is presented.
To reflect the results calculated by DF_QCupdate, missing page and overdue visit queries are maintained in the study database. Schedule View does not create missing page or overdue visit queries.
DF_QCupdate requires a user with full database permission to run the report, including the permission to add queries. The results are calculated for the entire study every time. Schedule View can be narrowed down to an individual site, or even an individual subject. The Schedule View does not need query write permission and can also be calculated from a read-only database.
The output from DF_QCupdate is easily shared with external parties, who have no access to the study database, by emailing a PDF generated by DF_QCreports. Schedule View requires that the user has access to DFexplore and at least read access to their site or subject data.
Options
-o | do not update overdue visit queries (update missing page queries only) |
-d | delete all queries with the specified query category. If no categories are specified, delete all missing page (code 21) and overdue visit (code 22) queries. |
-s | when a subject terminates count visits overdue if scheduled ON or BEFORE the termination date. Without this option visits are overdue only if scheduled before the termination date. |
-last | show date and results from last execution of DF_QCupdate, then quit |
-t yyyymmdd | set today's date for visit scheduling and overdue visit calculations |
Examples
Example 2.88. Show results from last execution of DF_QCupdate then quit
-last
DF_QCupdate - jane Mon Mar 29 16:02:38 2018
today = 20180329 38074
Missing Pages Update = 10 Total = 44
Overdue Visits Update = 15 Total = 126
Unexpected Records Update = 0 Total = 9This example shows that DF_QCupdate was last executed by jane on Mar 29, 2018 at 38 seconds after 16:02 (4:02 pm). The value, 38074 shown on the next line is the Julian value of the date (calculated as the number of days since Jan 1,1900), and is the value used to determine how many days visits are overdue. The Update values on the next 3 lines show the number of records that need to be added, modified or deleted, for each category and the Total values show the resulting total for each category that will exist after the updates are applied.
Occasionally, as illustrated in the next example, some updates may become irrelevant before they can be applied.
Example 2.89. Update the Query database and all summary files
no options
DF_QCupdate: Update Query Database. DFstudy 253. Mar 31,2018 16:55
1. Checking permissions on study 253, Demo Study 253
2. Reading study configuration files
3. Exporting current overdue visit and missing plate queries
4. Exporting required data from study database:
-exporting visit dates and keys from required plates
-exporting data for conditional terminations
-exporting data for conditional plates
5. Checking for overdue visits, missing plates and unexpected records
Missing Pages Update = 8 Total = 48
Overdue Visits Update = 9 Total = 129
Unexpected Records Update = 0 Total = 9
6. Updating the Query database (using DFimport.rpc)
adding new queries, replacing modified queries, deleting queries no longer relevant
E** line 9 failed 'Import failed as existing record is in use'
Visit 21 is no longer overdue for ID 1023
17 records input: 16 imported (0 warnings), 1 failed with errors
7. DoneThis example shows the output messages displayed by DF_QCupdate as it proceeds step by step through the current study scheduling specifications and existing subject data. In step 6 the required updates for missing page and overdue visit queries are applied to the Query database. If users are working on the study while DF_QCupdate is running it is possible that a missing page or overdue visit identified during step 5 will have been entered before step 6 begins. When this occurs a 2 line message is written for each update record that is rejected. The final line of step 6 notes the total number of queries submitted for update, the number that were applied, and the number that failed. In the above example one of the overdue visit queries was rejected because the visit was no longer overdue when the updates were submitted to the database server in step 6. As a result the total number of overdue visit queries in the database will be 128 (1 less than the number calculated in step 5).
Example 2.90. Delete all overdue visit and missing page queries
-d
DF_QCupdate: Update Query Database. DFstudy 252. May 20,2017 10:33
1. Checking permissions on study 252, demo252
2. Reading study configuration files
3. Exporting current overdue visit and missing plate queries
4. Discarding missing plate and overdue visit queries
12 records input: 12 imported (0 warnings), 0 failed with errors
Discarded 5 missing page queries
Discarded 7 overdue visit queries
5. DoneWhen the -d option is used all current overdue visit and missing page queries are deleted from the Query database. This is all that is done. No subject scheduling is performed, no new overdue visit or missing page queries are created, and the summary files stored in the study work directory are not updated.
The number of records described as input in step 4, is the number of queries submitted to the study server for deletion. The total (12 in the above example) should match the total number of missing page and overdue visit queries deleted as reported in the final 2 lines of the output (5 + 7 in the above example).
Example 2.91. Delete missing page queries created by DF_QCupdate and dfaddmpqc
-d 21,23
DF_QCupdate: Update Query Database. DFstudy 252. May 20,2017 09:57
1. Checking permissions on study 252, demo252
2. Reading study configuration files
3. Exporting current overdue visit and missing plate queries
4. Discarding all queries with specified categories
Problem type 21 : 14 queries
Problem type 23 : 2 queries
16 records input: 16 imported (0 warnings), 0 failed with errors
5. Done
Each query has a category. The standard categories are:
1=missing, 2=illegal, 3=inconsistent, 4=illegible,
5=fax noise, 6=other problem, 21=missing page, 22=overdue visit,
and 23=EC missing page (queries created by edit check function dfaddmpqc).
Codes ranging from 30-99 may also exist if other query categories have been
defined at the study level.
When the -d option is followed by a list of query categories,
the queries with the specified categories are deleted.
No subject scheduling
is performed, no new overdue visit or missing page queries are created, and the
summary files stored in the study work directory are not updated.
![[Note]](../../imagedata/note.png) | Note |
|---|---|
Query categories 21 and 22 can be re-created by running DF_QCupdate,
and code 23 queries can be re-created using an appropriate batch edit check run,
but there is no automatic way to re-create queries that were added manually
by individuals using DFexplore.
There is no undo feature. Deletes are permanent, and the only record of their
prior existence will be in the audit trail. Use the
|