How to Read this Document

The ARS User Guide (ARS-UG) is intended to be used in conjunction with the ARS Model documentation. The Model was developed using the LinkML framework (https://linkml.io/linkml/index.html) and resides in the ARS repository (https://github.com/cdisc-org/analysis-results-standard) in GitHub, a website and cloud-based service to store and manage code, where it can be accessed for free and without the need to create a user account. In addition to the original definition of the Model, the ARS repository also contains supporting information that has been generated from the Model definition using LinkML utilities. Included in the supporting information is a set of human-readable documentation files describing the components of the Model. For ease of accessibility, this Model documentation can also be viewed as an HTML representation at https://cdisc-org.github.io/analysis-results-standard/. While the HTML visualization provides detailed documentation of the structure of the Model, the ARS-UG is intended to provide expanded information about the purpose and use of each of the components of the Model, as well as implementation examples.

The Model includes a set of classes used to describe aspects of analyses and outputs. Each class is defined as a set of attributes, and is analogous to a table in a relational database; for a simple class, each attribute would correspond with a column in the table and each occurrence, or "instance", of the class would be represented as a row in the table. In the ARS Model, attribute characteristics are defined in standalone "slot" definitions, and these slot definitions are then referenced as attributes in class definitions. Each class attribute acquires the set of characteristics defined for the corresponding slot, including:

• Range: an indication of how the attribute will be populated, which is recorded as a reference to any of the following:
  • A simple data type (e.g., string, integer)
  • An enumeration, which defines a set of permissible values for the attribute (equivalent to controlled terminology)
  • Another class, indicating that the attribute contains 1 or more instances of the referenced class.
• Required: an indication of whether the attribute must be populated
• Multivalued: an indication of whether the attribute may contain more than 1 value or instance of the referenced class. 

LinkML allows modeling that makes use of techniques such as "inheritance," where the attributes of a template class may be may be included another class. For more information about inheritance, see the LinkML documentation (available at https://linkml.io/linkml/schemas/inheritance.html). Some of these techniques have been used in the definition of the ARS Model to ensure consistency of class definitions, apply data constraints, and facilitate the representation of ARS data in various data formats. To simplify the descriptions of the use and representation of analysis and output definitions in ARS format, some of the details of more complex modeling techniques may not be included in this user guide. However, all details are available in the HTML Model documentation.

Section 2, Analysis Results Model, contains class-specific pages describing structure and use of the class. Each of these pages contains:

• A link to the corresponding HTML Model documentation
• A high-level description of the purpose of the class and where it is used within the definition of a reporting event
• A diagram showing the structure of the class and its relationships with other classes. The Mermaid tool has been used to define and render these diagrams. Either of 2 types of diagram is used on each page:
  • A Class Diagram is used when it is necessary to illustrate the inheritance of attributes between classes. Refer to the Mermaid documentation for class diagrams (available at https://mermaid.js.org/syntax/classDiagram.html) for information about components of class diagrams.
  • An Entity Relationship (ER) Diagram is used in all other cases. Refer to the Mermaid documentation for ER diagrams (available at https://mermaid.js.org/syntax/entityRelationshipDiagram.html) for more information about the components of ER diagrams.
• A description of each of the attributes of the class and how they are populated
• At least 1 implementation example, showing how the attributes of the class may be populated for 1 or more instances of the class, or how instances of the class may be referenced in other parts of the model. These examples always include example data represented in YAML and may also include the same example data represented in tabular format. YAML is a text-based "human-readable data serialization language"—i.e., a compact and understandable way to represent hierarchical data. In YAML, data is represented as attribute/value pairs; the attribute name is shown first, followed by a colon and then the value.
  • If the attribute contains a single simple value (e.g., a number of a text string), this is represented on the same line as the attribute name; for example:
    

    textAttribute: Some text value here
    numericAttribute: 1.2

  • If the attribute contains an instance of another class, the attributes of the contained class are shown indented below the containing attribute; for example:
    

    complexAttribute:
      textSubAttribute: Value for first attribute of the contained class
      numericSubAttribute: 0
      complexSubAttribute:
        textSubSubAttribute: xxx
        numericSubSubAttribute: 8.5

  • If the attribute contains a list of values, each value in the list is shown indented below and preceded by a hyphen; for example:
    

    textListAttribute:
    - first text value
    - second text value
    numericListAttribute:
    - 18
    - 24
    - 6.5
    complexListAttribute:
    - textSubAttribute: text value for first attribute of first entry in list
      numericSubAttribute: 1.0
    - textSubAttribute: text value for first attribute of second entry in list
      numericSubAttribute: 2.0

Additional information about YAML can be found in Wikipedia (https://en.wikipedia.org/wiki/YAML). Note that in the implementation examples, an ellipsis (...) is used in YAML only to indicate deliberately excluded data.