AnalysisProgrammingCodeTemplate

The AnalysisProgrammingCodeTemplate class is used in the codeTemplate attribute of an analysis method to define any template programming code that may be used to generate results for all analyses that use the method. Template programming code is usually parameterized to allow analysis-specific information to be passed through to the code. However, if the same code is always executed for all analyses that use the method, or if the method is only used in a single analysis, then parameterization would not be necessary. In general, template programming code may be used in 2 ways:

1. The template code may be copied to the analysis and represented as analysis-specific code in the programmingCode attribute of the analyses. The copy process may or may not involve updating the code.
   1. If the template code is already executable, it may be copied, unmodified, into the analyses that use the method. In this situation, if any parameters are associated with the template code, any of these that require analysis-specific values would also need be copied to the analysis and updated to show the analysis-specific value used for execution of the code for the analysis. The analysis-specific value associated with each of these "runtime parameters" would be applied during execution of the code for the analysis.
   2. If the template code contains "replacement parameters" (i.e., the code contains identifiable placeholder strings that are expected to be replaced with analysis-specific parameter values in order to produce executable, analysis-specific, nonparameterized code), the placeholders in the code for each parameter would be replaced with the analysis-specific values during the copying process. In this situation, sponsors may choose to record the analysis-specific values applied during the copying process as parameter values associated with the resultant analysis-specific programming code. Alternatively, only the template code parameters (which include a specification for the expected analysis-specific value) could be retained.
2. Instead of copying template programming code into every analysis that uses the analysis method, sponsors may choose to implement template programming code by implied reference only. In this situation, the template programming code is not copied into each analysis; it remains defined only in the analysis method, being retrieved for each analysis (via the method identifier) only at the time of execution. If the template programming code is parameterized (with either replacement parameters or with runtime parameters), analysis-specific parameter values would need to be applied to the template code as part of the execution.
   1. If any parameter contains a specification indicating how to obtain the analysis-specific parameter value programmatically (e.g., it contains either a single, prespecified "default" value or a reference to a metadata attribute that provides the analysis-specific parameter value), it does not need to be represented within the analysis definition (although sponsors may choose to copy the parameter to the analysis to have a record of the parameter value being applied during execution).
   2. If a parameter does not contain a specification indicating how to obtain the analysis-specific parameter value programmatically (e.g., it does not have either a single, prespecified "default" or a reference to a metadata attribute that provides the analysis-specific value), the parameter must be copied to the analysis and updated to indicate the analysis-specific value applied during execution.

Provision of programming code for analyses, either directly in an analysis definition or via use of template programming code, is not required; sponsors may choose to include programming code to support their regulatory or operational requirements. When specified, template programming code for each analysis method is represented as an instance of AnalysisProgrammingCodeTemplate class and, in each instance:

• The context attribute is used to specify the name and version of the computer language used for the programming statements.
• The template programming statements may be provided by either:
  • storing the statements directly in the code attribute of the AnalysisProgrammingCodeTemplate class, or
  • referencing a template programming code document in the documentRef attribute of the AnalysisProgrammingCodeTemplate class (see the DocumentReference section for more information about programming code document references).

Template programming statements may contain parameter references, which could be placeholder strings for replacement parameters (e.g., "{dataset_name}", "[BYVAR1]", "<ndp>") or runtime parameter references (e.g., "&varname", "params$clsvar"). The format of parameter references in template programming code may depend on the computer language used either for the programming statements themselves or for the reading and processing ARS metadata. There are no requirements for the format of parameter references within template programming code; sponsors may use any format that facilitates their operational implementation.

• The parameters attribute may be used to specify any parameters associated with the template programming code. If parameters are specified, each parameter is specified as an instance of the TemplateCodeParameter specialization of the CodeParameter class, in which:
  • The name attribute contains a short name of the parameter.
  • The description attribute may contain a description of the parameter. If parameter references are retained in programming code that is provided as supporting metadata for analyses (e.g., as ARM for Define-XML metadata), it is recommended that a description is defined for each parameter, and that the name, description and analysis-specific value for each parameter are provided with the programming statements so that the programming statements are understandable without reference to any other documentation.
  • Either:
    • The valueSource attribute contains a reference to a metadata attribute whose value is to be used as the analysis-specific parameter value, either during a template code copying process or at the time of execution. There is currently no defined syntax for metadata attribute references; sponsors may represent metadata element references using any syntax or conventions that facilitate their operational implementation.

However, if ARS metadata is shared, the provider should either

• • • • provide sufficient supporting information so that all metadata element reference can be unambiguously interpreted by the receiver, or
      • record parameter values obtained from metadata references with each analysis.

Or:

• • • The value attribute may be used to prespecify value(s) for use during execution of the analysis:
      • If a single value is specified, this would generally be interpreted as representing a "default" value to be applied in all analyses that use the method, unless the parameter is copied to the analysis and the prespecified value is replaced with another analysis-specific value.
      • If multiple values are specified (which is allowable in the TemplateCodeParameter specialization of the CodeParameter class), these would generally be interpreted as a list of allowable values. In this case, the parameter would need to be copied to the analysis so that the appropriate analysis-value can be selected from the list and recorded for the analysis.
      • If the value attribute has no value (or is not used in the instance of the TemplateCodeParameter class) and the valueSource is also not used, this would generally imply that the parameter should be copied to the analysis so that an analysis-specific value can be specified.

Sponsors may use other conventions for the population and use of the value attribute. However, any conventions used should be applied consistently throughout the reporting event and, if ARS metadata is shared, the provider should either:

• • • • Provide sufficient supporting information so that it is obvious to the receiver how template parameter values are applied during execution of analyses, or
      • Record all analysis-specific parameter values with each analysis.

analysisGroupings:
- id: AnlsGrouping_01_Trt
  name: Treatment
  groupingDataset: ADSL
  groupingVariable: TRT01A
  dataDriven: false
  groups:
  ...
- id: AnlsGrouping_03_AgeGp
  name: Age Group
  groupingDataset: ADSL
  groupingVariable: AGEGR1
  dataDriven: false
  groups:
  ...
methods:
- id: Mth03_CatVar_Comp_PChiSq
  name: Pearson's chi-square test group comparison for a categorical variable
  description: Comparison of groups by Pearson's chi-square test for a categorical
    variable. Maximum of two grouping variables.
  label: Pearson's chi-square test
  operations:
  - id: Mth03_CatVar_Comp_PChiSq_1_pval
    name: P-value
    label: p-value
    order: 1
    resultPattern: X.XXXX
  codeTemplate:
    context: SAS Version 9.4
    code: "proc freq data={dataset};
      table {grp1var}*{grp2var}/chisq;
      exact pchi;
      ods output PearsonChiSq=PCHI{grp2var};
      run;"
    parameters:
    - name: dataset
      description: Input dataset
      valueSource: dataset
    - name: grp1var
      description: First grouping variable
      valueSource: orderedGroupings[1].groupingId.groupingVariable
    - name: grp2var
      description: Second grouping variable
      valueSource: orderedGroupings[2].groupingId.groupingVariable
analyses:
- name: Comparison of Age Group by Treatment
  id: An03_02_AgeGrp_Comp_ByTrt
  methodId: Mth03_CatVar_Comp_PChiSq
  version: 1
  dataset: ADSL
  variable: USUBJID
  analysisSetId: AnalysisSet_02_SAF
  orderedGroupings:
  - order: 1
    resultsByGroup: false
    groupingId: AnlsGrouping_01_Trt
  - order: 2
    resultsByGroup: false
    groupingId: AnlsGrouping_03_AgeGp
  programmingCode:
    context: SAS Version 9.4
    code: "proc freq data=ADSL;
      table TRT01A*AGEGR1/chisq;
      exact pchi;
      ods output PearsonChiSq=PCHIAGEGR1;
      run;"