DocumentReference

Model Documentation

The DocumentReference class is used to create references to any of the reference documents specified in the reporting event's referenceDocuments attribute (as described in the ReferenceDocument section). Document references may be created for any of the following:

documentation of the analysis as specified in the SAP and/or protocol,
output displays in a clinical study report or integrated summary,
program files containing programming code for specific analysis methods, for analyses, or for outputs.

Class Diagram: DocumentReference

The ARS DocumentReference class corresponds with the Define-XML def:DocumentRef element that is referenced in the ARM for Define-XML specification:

ARS DocumentReference Attributes	Corresponding Define-XML def:DocumentRef Attribute/Element
referenceDocumentId	leafID attribute
pageRefs	def:PDFPageRef elements (see below)

A document reference must include the identifier of the reference document (as specified in the referenceDocumentId attribute) to indicate which document is being referenced. If needed, the document reference may also include one or more "page references" (each specified in the pageRefs attribute) to indicate the relevant page or pages within the reference document. A document reference that does not include any page references is areference to the document as a whole. In general, there are two types of document reference:

Documentation document references, which may be created for analysis methods, analyses or outputs by specifying one or more document references in the documentRefs attribute of the AnalysisMethod, Analysis or Output classes respectively. Only one document reference should be created for each document being referenced (referenceDocumentId should be unique within the set of instances of the DocumentReference class included in the documentRefs attribute), but the document reference for a specific document may include multiple page references if it's necessary to reference different pages or sections of the document.
Programming code document references, which may be created for the template programming code associated with analysis methods, or for programming code for analyses or outputs. No more than one document reference may be created for the programming code associated any analysis method, analysis or output and, when included, the document reference is specified in the documentRef attribute of:
- the instance of the AnalysisProgrammingCodeTemplate class specified in the analysis method's codeTemplate attribute
- the instance of the AnalysisOutputProgrammingCode class specified in the programmingCode attribute of the analysis or output.

As programming code document references refer to program files, which usually only contain the set programming code statements for a single analysis method, analysis or output, programming code document references usually do not include page references.

The abstract ARS PageRef class corresponds with the Define-XML def:PDFPageRef element that is referenced in the ARM for Define-XML specification:

ARS PageRef Attributes	Corresponding Define-XML def:PDFPageRef Attribute
refType	Type
label	Title
pageNames	PageRefs
pageNumbers	PageRefs
firstPage	FirstPage
lastPage	LastPage

All page references must include an indication of the page reference type in the refType attribute, and may also include a description of the page reference in the label attribute. Individual pages or sets of pages may be referenced in different ways using any of the specializations of the abstract PageRef class:

PageNameRef where:
- refType is "NamedDestination"
- pageNames contains one or more named destinations (e.g., bookmarks) in the reference document.
PageNumberListRef where:
- refType is "PhysicalRef"
- pageNumbers contains one or more page numbers.
PageNumberRangeRef where:
- refType is "PhysicalRef"
- firstPage contains the page number of the first page in a range of pages
- lastPage contains the page number of the last page in the range of pages.

Multiple page references may be created for a single document reference if more than one type of page reference is required (e.g., reference to both a set of individual page numbers and a range of page numbers), if more than one range of pages needs to be specified, or if the sponsor prefers to assign different labels for page references of the same type.

Example

This example shows a selection of documentation document references specified in the documentRefs attribute of 1 analysis method, 1 analysis, and 2 outputs:

Lines 2-11:	Show the "Summary by group of a categorical variable" analysis method, which has a single documentation document reference indicating that relevant information can be found on pages 9 and 11 of the reference document identified as "CDISCPILOT01_SAP".
Lines 15-32:	Show the "Summary of Change from Baseline by Treatment, Parameter and Visit" analysis, which has document references for 2 reference documents, indicating that: Lines 18-27: In the reference document identified as "CDISCPILOT01_SAP", relevant information can be found on pages 9 and 17. The sponsor created 2 page separate page references in order to assign a specific label to each. Lines 28-32: In the reference document identified as "CDISCPILOT01_CSR", relevant information can be found at the named destination "Table 14-7.02". The sponsor chose not to specify a label for this page reference.
Lines 36-44:	Show the "Summary of Demographics" output, which has a single documentation document reference indicating that relevant information can be found on pages 46 to 48 of the reference document identified as "CDISCPILOT01_CSR".
Lines 45-49:	Show the "Overall Summary of Treatment-Emergent Adverse Events" output, which has a single documentation document reference indicating that relevant information can be found in the reference document identified as "AE_Summary_Table_Shell". No page reference was specified, which indicates that the whole reference document contains relevant information.

YAML Example

methods:
- id: Mth01_CatVar_Summ_ByGrp
  name: Summary by group of a categorical variable
  documentRefs:
  - referenceDocumentId: CDISCPILOT01_SAP
    pageRefs:
    - refType: PhysicalRef
      label: 7. GENERAL CONSIDERATIONS FOR DATA ANALYSES
      pageNumbers:
      - 9
      - 11
  ...
...
analyses:
- id: An08_02_ChgBl_Summ_ByTrt
  name: Summary of Change from Baseline by Treatment, Parameter and Visit
  documentRefs:
  - referenceDocumentId: CDISCPILOT01_SAP
    pageRefs:
    - refType: PhysicalRef
      label: Section 7 (General Considerations)
      pageNumbers:
      - 9
    - refType: PhysicalRef
      label: Section 11.6 (Other Safety Measures)
      pageNumbers:
      - 17
  - referenceDocumentId: CDISCPILOT01_CSR
    pageRefs:
    - refType: NamedDestination
      pageNames:
      - Table 14-7.02
  ...
...
outputs:
- id: Out14-1-1
  name: Summary of Demographics
  documentRefs:
  - referenceDocumentId: CDISCPILOT01_CSR
    pageRefs:
    - refType: PhysicalRef
      label: Table 14-2.01
      firstPage: 46
      lastPage: 48
  ...
- id: Out14-3-1-1
  name: Overall Summary of Treatment-Emergent Adverse Events
  documentRefs:
  - referenceDocumentId: AE_Summary_Table_Shell
  ...

These documentation document references could be represented in tabular format as shown in the following table where:

The type of object for which the document reference is defined is indicated in the "object_type" column, which contains the name of the object's parent reporting event attribute.
Each instance of 1 of the specializations of the PageRef class is shown on a separate row. If there are no page references for a document reference, a single row is shown for the document reference.
Values of the id, name, and referenceDocumentId attributes is are shown on all rows relating to a document referenced for an object.
Values from the pageNumbers and pageNames attributes have been transposed to be shown on a single row, with column names derived from the attribute name with a numeric suffix indicating the value ordinal (e.g., "pageNames1" for the first value of the pageNames attribute, "pageNumbers2" for the second value of the pageNumbers attribute).

$titleHtml

object_type	id	name	referenceDocumentId	refType	label	pageNumbers1	pageNumbers2	pageNames1	firstPage	lastPage
methods	Mth01_CatVar_Summ_ByGrp	Summary by group of a categorical variable	CDISCPILOT01_SAP	PhysicalRef	7. GENERAL CONSIDERATIONS FOR DATA ANALYSES	9	11
analyses	An08_02_ChgBl_Summ_ByTrt	Summary of Change from Baseline by Treatment, Parameter and Visit	CDISCPILOT01_SAP	PhysicalRef	Sections 7 (General Considerations)	9
analyses	An08_02_ChgBl_Summ_ByTrt	Summary of Change from Baseline by Treatment, Parameter and Visit	CDISCPILOT01_SAP	PhysicalRef	11.6 (Other Safety Measures)	17
analyses	An08_02_ChgBl_Summ_ByTrt	Summary of Change from Baseline by Treatment, Parameter and Visit	CDISCPILOT01_CSR	NamedDestination				Table 14-7.02
outputs	Out14-1-1	Summary of Demographics	CDISCPILOT01_CSR	PhysicalRef	Table 14-2.01				46	48
outputs	Out14-3-1-1	Overall Summary of Treatment-Emergent Adverse Events	AE_Summary_Table_Shell

$warningHtml

Example

This example shows a selection of programming code document references specified in the documentRef attribute of the codeTemplate for 1 analysis method, and the programmingCode for 1 analysis and 2 outputs:

Lines 2-7:	Show the code template specified for the "Analysis of variance group comparison for a continuous variable" analysis method, which indicates that relevant R version 4.2.3 program statements can be found in the reference document identified as "anova_R". As there is no page reference, this indicates that the whole reference document contains relevant program statements.
Lines 11-25:	Show the programming code specification for the "Comparison of Age Group by Treatment" analysis, which indicates that relevant SAS version 9.4 program statements can be found in the reference document identified as "PROGRAM_CATALOG_SAS" which, in this example, is a single file containing a combined set of programs, with a bookmark created for each program. The sponsor chose to create two separate page references in order to provide a descriptive label for each.
Lines 29-34:	Show the programming code specification for the "Summary of TEAE by System Organ Class and Preferred Term" output, which indicates that relevant SAS version 9.4 program statements can be found in the reference document identified as "at14-5-01_sas". As there is no page reference, this indicates that the whole reference document contains relevant program statements.

YAML Example

methods:
- id: Mth04_ContVar_Comp_Anova
  name: Analysis of variance group comparison for a continuous variable
  codeTemplate:
    context: R Version 4.2.3
    documentRef:
      referenceDocumentId: anova_R
  ...
...
analyses:
- id: An03_02_AgeGrp_Comp_ByTrt
  name: Comparison of Age Group by Treatment
  programmingCode:
    context: SAS Version 9.4
    documentRef:
      referenceDocumentId: PROGRAM_CATALOG_SAS
      pageRefs:
      - refType: NamedDestination
        label: Pearson chi-square macro definition
        pageNames:
        - PearsonDef
      - refType: NamedDestination
        label: Pearson macro call for age group
        pageNames:
        - PearsonCall-AgeGrp
   ...
...
outputs: 
- id: Out14-3-2-1
  name: Summary of TEAE by System Organ Class and Preferred Term
  programmingCode:
    context: SAS Version 9.4
    documentRef:
      referenceDocumentId: at14-5-01_sas
  ...
...

These programming code document references could be represented in tabular format as shown in the following table where:

The type of object for which the document reference is defined is indicated in the "object_type" column, which contains the name of the object's parent reporting event attribute.
Each instance of 1 of the specializations of the PageRef class is shown on a separate row. If there are no page references for a document reference, a single row is shown for the document reference.
Values of the id, name, and referenceDocumentId attributes is are shown on all rows relating to a document referenced for an object.
Values from the pageNames attribute have been transposed to be shown on a single row, with column names derived from the attribute name with a numeric suffix indicating the value ordinal (e.g., "pageNames1" for the first value of the pageNames attribute).

$titleHtml

object_type	id	name	context	referenceDocumentId	refType	label	pageNames1
methods	Mth04_ContVar_Comp_Anova	Analysis of variance group comparison for a continuous variable	R Version 4.2.3	anova_R
analyses	An03_02_AgeGrp_Comp_ByTrt	Comparison of Age Group by Treatment	SAS Version 9.4	PROGRAM_CATALOG_SAS	NamedDestination	Pearson chi-square macro definition	PearsonDef
analyses	An03_02_AgeGrp_Comp_ByTrt	Comparison of Age Group by Treatment	SAS Version 9.4	PROGRAM_CATALOG_SAS	NamedDestination	Pearson macro call for age group	PearsonCall-AgeGrp
outputs	Out14-3-2-1	Summary of TEAE by System Organ Class and Preferred Term	SAS Version 9.4	at14-5-01_sas

$warningHtml

Page tree

DocumentReference