Retraction wizard

[Nicklas Nordborg]

Patients that no longer wish to participate in the study may retract their consent at any time. So far, this has been handled manually by deleting/modifying items following a certain procedure. The procedure has not been fully formalized yet. When the procedure is in place, a retraction wizard should be implemented to aid the process.

[olle]

Ticket accepted.

[olle]

Functionality specification update:

The retraction wizard should support two cases:

1. When a patient have withdrawn an originally approved consent.

2. When samples have been processed by mistake without an approved consent.

[olle]

Functional specification:

The first version of the retraction wizard will only cover the initial steps of the retraction procedure:

1. Taking a case name (scan-b id) or patient item name as input, stored items in the database will be listed for the related patient. If a case name is input, it is first used to find the patient, and then all cases (at most 2) for that patient are found. Information about items in all found cases are listed.
2. It should be possible to create a protocol with information on locally stored items related to the cases. This protocol should include item type, item name, and storage data, and is intended to be used to find the samples in question and destroy them. The protocol should include the following item types: Specimen, Lysate, RNA, DNA, and FlowThrough.
3. The user should be able to select a number of annotation changes, intended to prevent further analysis of some items types, e.g. RNA. For this to have the desired effect, it is both necessary that a Reggie wizard is used before the actual analysis, and that the wizard in question checks the value of the annotation in question, before allowing an item to be processed further.
4. When marking data for a patient as retracted, the patient record (a BioSource item), should have its type changed from "Patient" to "Retract" or "RetroNo", and its item name to "Retract" or "RetroNo" + a 6-figure consecutive serial number for the subtype in question, e.g. "Retract000009" or "RetroNo000012". The wizard should suggest the new item type based on the previous patient type, but the user should be able to change it before the final registration.
5. The wizard will require the user to have Curator preferences.

Information listed for different item types:

Patient

Item type

Item name

Date type

Date

Gender

All cases

Personal number

All first names

Family name

Cases

Item type

Item name

Date type

Date

Consent

Consent date

Site

Laterality

Comment

Flag

Flag to set

Blood samples

Item type

Item name

Date type

Date

Consent

Consent date

Sample type

RCC-ID

Serum

Flag

Flag to set

Other items

Item type

Item name

Date type

Date

Other data name

Other data value

Storage type

Storage ID

Storage position

Flag

Flag to set

AutoProcessing

AutoProcessing to set

Sequencing runs

Item type

Item name

Start date

End date

Flow cell name

Flow cell cluster date

Case name

Result

Comment

AutoProcessing

AutoProcessing to set

More detailed specification about some data listed for different item types ("NA" = "Not Applicable"):

Item type	Date type	Other data name	Storage type	Flag to set	AutoProcessing to set
Patient	Registration	-	NA	-	-
Case	Registration	-	NA	-	-
Blood	Sampling	-	-	-	-
Specimen	Sampling	PAD	Storage box	-	-
NoSpecimen	Registration	-	NA	-	-
Histology	Partition	No. slides	Paraffin block	Retracted	Disable
Stained	-	-	Slide	-	-
Lysate	Lysis		Storage box	-	-
RNA	-	No. QC	Storage box	Retracted	Disable
RNA-QC	-	-	Plate	-	-
DNA	-	-	Storage box	-	-
FlowThrough	-	-	Storage box	-	-
mRNA	-	-	Work plate	-	-
cDNA	-	-	Work plate	-	-
Library	-	No. Dilutes	Library plate	-	-
Library dilute	-	-	-	-	-
Pooled library	-	-	-	-	-
Sequencing run	Execution	-	NA	NA	-

The lab protocol should consist of 3 tables:

1. Source with retracted consent
2. Samples/extracts to be destroyed
3. Lab representative certification

The protocol tables should contain the following data:

1. Source with retracted consent: Patient item name, all case names
2. Samples/extracts to be destroyed: A table with one row per sample/extract item with columns for the following information:
   
   a. Item type
   b. Name
   c. Storage ID
   d. Storage position
   e. Result/Comment
   
   The Result/Comment column should contain a check box with title "Destroyed", to be checked on the paper copy, after the item in question has been destroyed.

3. Lab representative certification: Four lines for "Date", "Name", "Signature", and "Comments".

[olle]

Design specification:

The code design borrows (steals) heavily from other wizards:

• Case summary also tracks child items for a case/patient, and a lot of the code for finding that data is taken from this source. Two main differences exist; the retraction wizard should find items for all cases for a patient, and the emphasis of display is more on a simply structured listing of item data, one row per item, than on a presentation tailored for each item type, with some data accessible through links and hints. As an example, in the case summary, the storage location is displayed when the mouse pointer is placed over an info icon, while this information is one of the essential parts of the retraction data.
• Export utilities like that for exporting monthly operation lists or data to INCA were used as base for creating a tab-separated list of the item data, suitable for download and import in a spreadsheet program.
• Lab protocols of different types, e.g. clustering and sequencing (flowcell_protocol.js, flowcell_protocol.jsp, and flowcell_protocol2.jsp) were used for the design of the retraction protocol part of the code. The retraction lab protocol in itself is very simple, the tricky part is mainly the interaction between different JSP and Javascript files, and transfer of information between them.

File updates:

• JSP file index.jsp in resources/ is updated with a new header "Retraction wizard" in section "Personal information wizards". Initially, it will only have one entry, "Mark extracts for retraction", with a link to new JSP file retractionform.jsp in resources/personal/.
• JSP file retractionform.jsp in resources/personal/ is coupled to Javascript file retractionform.js, and in its "form"-tag has an action attribute set to value "retraction_protocol2.jsp" (all later files also in resources/personal/). The JSP file has an input field for entering a case name or personal number. After initial validation of the case name/personal number, servlet RetractionFormServlet is called with command "GetCaseInfo" to obtain a JSONObject with information on all cases for the patient in question, which is sent to function rf.caseInfoLoaded(response) to be displayed in table form. The form contains checkboxes for setting values for the Flag and AutoProcessing annotations for the histology and RNA items, as well as a checkbox for selecting whether an unchecked checkbox should trigger the corresponding annotation to be reset to null (default is to ignore unchecked checkboxes).
  a. Button "Register" is coupled to function rf.submit(), that calls function checkBoxValues(...) to retrieve string-coded checkbox values and send them together with the input case name/personal number to servlet RetractionFormServlet with command "RegisterRetraction".
  b. Buttons "Preview" and "Download" are both indirectly coupled to function rf.doExport(preview), but with preview set to true and false, respectively. The latter function creates a table with tab-separated column data of the case/patient information, more suitable for import into spreadsheet programs, although containing several sub-tables with separate headers. If attribute preview is false, a dialog will be opened to download the table to a file.
  c. Button "Create protocol" is coupled to function rf.createProtocol(), that will save input case name/personal number and the number of items to be destroyed in hidden input fields in the HTML form, after which frm.submit() is called, which will transfer the action to JSP file "retraction_protocol2.jsp, and it related Javascript file retraction_protocol.js.
• JSP file retraction_protocol2.jsp in resources/personal/ is coupled to Javascript file retraction_protocol.js. Values for input case name/personal number and the number of items to be destroyed are retrieved from the HTTP response, and retraction_protocol2.jsp creates a template for a table of items to be destroyed, one row per item, and retraction_protocol.js calls servlet RetractionFormServlet with command "GetProtocolInfo" (currently identical to command "GetCaseInfo") to obtain a JSONObject with information on all cases for the patient in question, which is sent to function rp.initializeProtocol(response) to be inserted into the protocol template. The reason for the suffix "2" in the name of JSP file retraction_protocol2.jsp, is that most protocol wizards have an initial JSP file retraction_protocol.jsp, with input fields for information required to retrieve the protocol data, but this role is here taken by retractionform.jsp.
• New java servlet class/file RetractionFormServlet.java in src/net/sf/basedb/reggie/servlet/ accepts GET requests for commands "GetCaseInfo", "GetProtocolInfo" (currently identical to "GetCaseInfo"), and "ExportRetractData", as well as POST request for command "RegisterRetraction". It accesses the database to retrieve the requested information, or update the contents, and sends the results back in JSON format. Private method Patient fetchPatient(DbControl dc, String caseOrPersonalNumber) calls new public static method Patient findByPersonalNumber(DbControl dc, String pnr, boolean restrictToPatientBioSources) in class Patient with attribute restrictToPatientBioSources set to false, in order to find BioSource items of subtypes RETRACT and RETRO_NO, in addition to PATIENT subtypes.
• XML servlet configuration file servlets.xml in META-INF/ updated with entry for new servlet RetractionFormServlet.
• Java class/file Annotationtype.java in src/net/sf/basedb/reggie/dao/ updated in public static final Annotationtype AUTO_PROCESSING by including Item.SAMPLE in list of item types for annotation "AutoProcessing", allowing the annotaiton to be used for histology items.
• Java class/file Consent.java in src/net/sf/basedb/reggie/dao/ updated by adding new static final String constant FLAG_RETRACTED with value "Retracted".
• Java class/file Subtype.java in src/net/sf/basedb/reggie/dao/ updated by adding new static final Subtype items RETRACT and RETRO_NO for BioSource items, with values "Retract" and "RetroNo", respectively.
• Java class/file Patient.java in src/net/sf/basedb/reggie/dao/ updated with new public static method Patient findByPersonalNumber(DbControl dc, String pnr, boolean restrictToPatientBioSources), that allows BioSource items of subtypes RETRACT and RETRO_NO to be found, in addition to PATIENT subtypes.
• Java class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) to create items Subtype.RETRACT and Subtype.RETRO_NO, if not existing, and to allow the Flag annotation to have value Consent.FLAG_RETRACTED.
• CSS (Cascading Style Sheet) files retractionform.css in resources/css and retractionexport.css in resources/personal contain style information for the forms.

[olle]

(In [2839]) Refs #526. First version of the retraction wizard, that lists data for items related to a patient, taking a case name or personal number as input, and allows some annotations to be set for histology and RNA items, and the patient type to be changed to "Retracted" or "RetroNo". The item data can be downloaded in a table with tab-separated columns, and a lab protocol for protocol of specific samples/extracts can be created:

1. JSP file index.jsp in resources/ is updated with a new header "Retraction wizard" in section "Personal information wizards". Initially, it will only have one entry, "Mark extracts for retraction", with a link to new JSP file retractionform.jsp in resources/personal/.
2. JSP file retractionform.jsp in resources/personal/ is coupled to Javascript file retractionform.js, and in its "form"-tag has an action attribute set to value "retraction_protocol2.jsp" (all later files also in resources/personal/). The JSP file has an input field for entering a case name or personal number. After initial validation of the case name/personal number, servlet RetractionFormServlet is called with command "GetCaseInfo" to obtain a JSONObject with information on all cases for the patient in question, which is sent to function rf.caseInfoLoaded(response) to be displayed in table form. The form contains checkboxes for setting values for the Flag and AutoProcessing annotations for the histology and RNA items, as well as a checkbox for selecting whether an unchecked checkbox should trigger the corresponding annotation to be reset to null (default is to ignore unchecked checkboxes).
   a. Button "Register" is coupled to function rf.submit(), that calls function checkBoxValues(...) to retrieve string-coded checkbox values and send them together with the input case name/personal number to servlet RetractionFormServlet with command "RegisterRetraction".
   b. Buttons "Preview" and "Download" are both indirectly coupled to function rf.doExport(preview), but with preview set to true and false, respectively. The latter function creates a table with tab-separated column data of the case/patient information, more suitable for import into spreadsheet programs, although containing several sub-tables with separate headers. If attribute preview is false, a dialog will be opened to download the table to a file.
   c. Button "Create protocol" is coupled to function rf.createProtocol(), that will save input case name/personal number and the number of items to be destroyed in hidden input fields in the HTML form, after which frm.submit() is called, which will transfer the action to JSP file "retraction_protocol2.jsp, and it related Javascript file retraction_protocol.js.
3. JSP file retraction_protocol2.jsp in resources/personal/ is coupled to Javascript file retraction_protocol.js. Values for input case name/personal number and the number of items to be destroyed are retrieved from the HTTP response, and retraction_protocol2.jsp creates a template for a table of items to be destroyed, one row per item, and retraction_protocol.js calls servlet RetractionFormServlet with command "GetProtocolInfo" (currently identical to command "GetCaseInfo") to obtain a JSONObject with information on all cases for the patient in question, which is sent to function rp.initializeProtocol(response) to be inserted into the protocol template. The reason for the suffix "2" in the name of JSP file retraction_protocol2.jsp, is that most protocol wizards have an initial JSP file retraction_protocol.jsp, with input fields for information required to retrieve the protocol data, but this role is here taken by retractionform.jsp.
4. New java servlet class/file RetractionFormServlet.java in src/net/sf/basedb/reggie/servlet/ accepts GET requests for commands "GetCaseInfo", "GetProtocolInfo" (currently identical to "GetCaseInfo"), and "ExportRetractData", as well as POST request for command "RegisterRetraction". It accesses the database to retrieve the requested information, or update the contents, and sends the results back in JSON format. Private method Patient fetchPatient(DbControl dc, String caseOrPersonalNumber) calls new public static method Patient findByPersonalNumber(DbControl dc, String pnr, boolean restrictToPatientBioSources) in class Patient with attribute restrictToPatientBioSources set to false, in order to find BioSource items of subtypes RETRACT and RETRO_NO, in addition to PATIENT subtypes.
5. XML servlet configuration file servlets.xml in META-INF/ updated with entry for new servlet RetractionFormServlet.
6. Java class/file Annotationtype.java in src/net/sf/basedb/reggie/dao/ updated in public static final Annotationtype AUTO_PROCESSING by including Item.SAMPLE in list of item types for annotation "AutoProcessing", allowing the annotaiton to be used for histology items.
7. Java class/file Consent.java in src/net/sf/basedb/reggie/dao/ updated by adding new static final String constant FLAG_RETRACTED with value "Retracted".
8. Java class/file Subtype.java in src/net/sf/basedb/reggie/dao/ updated by adding new static final Subtype items RETRACT and RETRO_NO for BioSource items, with values "Retract" and "RetroNo", respectively.
9. Java class/file Patient.java in src/net/sf/basedb/reggie/dao/ updated with new public static method Patient findByPersonalNumber(DbControl dc, String pnr, boolean restrictToPatientBioSources), that allows BioSource items of subtypes RETRACT and RETRO_NO to be found, in addition to PATIENT subtypes.
10. Java class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) to create items Subtype.RETRACT and Subtype.RETRO_NO, if not existing, and to allow the Flag annotation to have value Consent.FLAG_RETRACTED.
11. CSS (Cascading Style Sheet) files retractionform.css in resources/css and retractionexport.css in resources/personal contain style information for the forms.

[olle]

(In ​[2841). Refs #526. Servlet class/file RetractionFormServlet.java in src/net/sf/basedb/reggie/servlet/ updated by suppressing "unchecked" warnings for private methods JSONObject fetchJsonCaseInfo(DbControl dc, String caseOrPersonalNumber, JSONObject json) and JSONObject fetchJsonNextRetractName(DbControl dc, JSONObject json).

[Nicklas Nordborg]

(In [2845]) References #526: Retraction wizard

Remove unused imports.