Create your Domain Model

Session Outline caCORE Build Process Review of UML Modeling Lesson 1: Model a Data Service Lesson 2: Create a UML Model for caBIG™ Compatibility

Session Goals When you complete this session, you will be able to: Distinguish a well-formed domain model vs. a not so well-formed model Provide the packages in which to create different portions of your model Describe the naming conventions appropriate for a UML Model that will be run through the caCORE Build process Use a Modeling Tool to Add a new Class and Attribute to a UML Model Use a Modeling Tool to Create a Value Domain in a UML Model

Create UML Model Metadata Reuse Semantic Annotation Transform UML Model into Metadata SDK Code Generation Compatibility Review Create a Node on the Grid

caCORE Build Process Design System & Draw Model Create your System/Project Model in UML “Logical View” model describes your domain Includes classes, attributes, data types, relationships Use Recommended Naming Conventions Conform to Java naming conventions and terminology standards Use clear Package, Class and Attribute names Use Standard Vocabulary (EVS) Class/attribute need at least one concept from a vocabulary Create Classes and Attribute Definitions as Tagged Values NEW: Class and attribute tagged value = “CADSR_Description” SIW still supports “documentation” and “description” tags Class Associations Must be named with associated class names Multiplicity and direction must be defined Attribute Data Types must already exist in caDSR

UML Modeling Review Why Model? Modeling achieves four aims: 1.Helps you visualize a system 2.Permits you to specify the structure or behavior of a system 3.Guides you in constructing a system 4.Documents the decisions you have made Build models of complex systems because they are difficult to comprehend in their entirety Build models to better understand the system you are developing. The caBIG process and architecture is model driven, it is required for interoperability and silver level compliance.

UML Modeling Review What is UML? UML is a language for Visualizing Specifying Constructing Documenting The artifacts of a software system. UML allows you to build models that are precise, unambiguous and complete There are many UML diagram types caCORE SDK utilizes one UML Class Diagram

UML Modeling Review UML Roles Role of UML in the caDSR A UML Class Diagram is used to transform the classes and attributes of a software system or data set into caDSR metadata. This process is called “Semantic Integration” Role of UML in the caCORE Build Process The same UML Class Diagram used for “Semantic Integration” is also used to generate code for a complete software system This process is called “Code Generation”

UML Modeling Review Sample Class Diagram ClassName attributeName associationName Bi-directional Association Datatype Multiplicity Generalization

Lesson 1: Modeling a Data Service Grid-enablement of Protein Information Resource (gridPIR) PIR is an integrated resource for proteomic research gridPIR is currently a caBIG silver level compliant data service exposes information from 1 of the PIR databases, the UniProt Knowledgebase (UniProtKB) gridPIR’s goal is to provide comprehensive and fully annotated protein sequence and functional information for basic cancer research

Lesson 1: Modeling a Data Service A not-so-recommended approach Modeling the record using existing XML schema. Is this valid? Yes Is this a good model? Not for us Is this a domain information model? No P99999 P99999 P00001 Q6NUR2 Q6NX69 Q96BV4 CYC_HUMAN Cytochrome c CYCS CYC Homo sapiens Human Eukaryota Metazoa Chordata Craniata Vertebrata Euteleostomi Mammalia Eutheria Euarchontoglires Primates Haplorrhini Catarrhini Hominidae Homo …… The valuable information is not exposed (e.g. protein annotation) It needs to be exposed to be advertised and discovered on caGrid

Lesson 1: Modeling a Data Service Reverse Engineering Approach Should You Reverse Engineer an Existing XML Model? You can but it will not guarantee caBIG compatibility. In practice, reverse engineering existing models has seldom worked well in the context of caBIG. Reverse engineering an existing model can help in understanding the domain but in practice it has not always provide a good information model for caBIG’s goals of interoperability. It is often been better to create a new or extensively modified version.

Lesson 1: Modeling a Data Service Considerations Scientific meaning : Design a re-usable domain information model, not an application-specific record model Use cases: Consider search criteria objects (Protein, Gene, Database Cross references) Data related constraints: Include only associations or objects based on your data For example, Gene to Protein, but not Protein to DNA Sequence as UniProt does not have DNA sequence only Xrefs to other data sources for DNA. Semantics: Express semantics, avoid using non-informative “type” attributes For example: name the ProteinFeature subclasses, don’t assign a feature “type”. Reuse: Try to reuse existing models Same “Things” can exist in other caBIG compatible models caCORE SDK constraints: Consider naming conventions, “id” attribute for each class

Lesson 1: Modeling a Data Service Use Cases Retrieving protein information using: Simple search using only one criteria Advanced search criteria constructed using Boolean operators Database identifier search without providing data source Search criteria can be based on: Database identifiers Protein sequence features (annotations) Protein/Gene name Keywords/Organism

Lesson 1: Modeling a Data Service Naming conventions/caCORE SDK constraints Naming Conventions: Adopt a case convention camelCase is recommended, some caBIG tools like the SIW support camelCase in mapping concepts Avoid using class identifiers in attribute names Abbreviations and acronyms should be avoided Avoid plural class or attribute names unless necessary Add “Collection” to association ends with multiplicity >1 (no longer required but a good practice) caCORE SDK constraints: “id” attribute in classes (only caCORE SDK 3.0) Avoid use of complex data types like “List” and “Collection”

Lesson 1: Modeling a Data Service A So-So Model Good: Classes are scientific real life things) Associations, directionality, classes based on use cases Re-uses classes from available models (caBIO) Bad: Attributes with complex data types (i.e., list, collection) Not all use cases are met Semantics needs improvement Violates some naming conventions

Lesson 1: Modeling a Data Service Improving Semantics Further Break up lists into collections of separate objects so gridPIR can provide searches on: Lineage Taxon names Alternate names for Organism

Lesson 1: Modeling a Data Service Improving Semantics Even Further Important annotations in the protein sequence data are features which are regions or sites of interest in the sequence, including:  Posttranslational modifications  Binding sites  Enzyme active sites  Other functional domains Problems:  Using “type” makes it difficult to discover gridPIR as a protein annotation resource  User needs to know permissible values for “type” to discover and even use the system Solution was to create an individual class for each feature

Lesson 1: Modeling a Data Service Improving Semantics Even Further Protein Sequence Annotation Classes

Lesson 2: Create a UML Model for caBIG™ Compatibility Reuse of existing CDEs The caBIG community has adopted select CDEs as standards and strongly encourages all to use them One of the best and most important steps you can take to promote interoperability is to reuse a Data Element from another caBIG service The Candidate, Proposed and Approved Standards can be found in the CDE Browser The Full Silver to Grid Training provides more information and options on reuse

Lesson 2: Create a UML Model for caBIG™ Compatibility Getting Started UML Modeling Tool Enterprise Architect ( cts/ea/index.html) cts/ea/index.html ArgoUML ( Download the SDKEATemplate.eap (caCORE SDK download package All UML Models should be placed in the Logical View Package System/project domain is drawn in UML Data model describes database schema Logical model describes target domain

Lesson 2: Create a UML Model for caBIG™ Compatibility Getting Started caCORE SDK tools impose modeling guidelines Java naming conventions Package rules gov.nih.nci.project.domain edu.institution.project.domain Element constraints The Data Model is required only for caAdapter, SDK and Code Generation, it is ignored by the SIW and UML Loader Example Only UML class diagram elements may be used Cannot use interface, object, etc.

Lesson 2: Create a UML Model for caBIG™ Compatibility Class Naming Conventions Establish a scope for the convention Determine the authority that establishes a name Develop semantic rules for the source and content of words used in a name Formulate syntax rules for required word order Develop lexical rules covering controlled word lists, name length, character set, and language Set guidelines on uniqueness of names in context Be consistent Adopt a case convention Avoid using class identifiers in attribute names Abbreviations and acronyms should be avoided Avoid technical jargon Never pluralize class or attribute names Add “Collection” to association ends with multiplicity >1

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Classes In the Project Browser, open the Logical Model diagram in the domain folder Select the domain folder, right click -> Add -> Add Element Leave the Type selected as Class Enter the name of the class (remember the naming conventions) Select all check boxes Click OK The Details tab will display to add attributes

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Attributes to Classes Click the Details tab Click the Attributes button Enter the name of the attribute in the name field (adhere to naming convention) Enter the data type in the Type field Type in the java primitive or wrapper class (using the dropdown list can cause problems) Set the Scope to Public (dropdown list) Click Save Click New to enter more attributes Click Close when finished

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Class Definition Tags Select the Class in the Project View Select Element > Tagged Values from the Main Menu Click the new tag icon Enter “CADSR_Description” or “documentation” as the tag name Enter the class definition as the value DO NOT use Notes section for the definition

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Attribute Definition Tags Select the attribute Select Element > Tagged Values from the Main Menu Enter “CADSR_Description” or “description” for the tag name Enter the attribute’s definition in the value field DO NOT use the Notes section for the definition

Lesson 2: Create a UML Model for caBIG™ Compatibility Using Existing CDEs Always search for existing metadata to re-use in your UML model Record the Public ID and Version ( , V3.0) Select the desired attribute in the model view Select Element > Tagged Values from the Main Menu Enter “CADSR_DE_ID” for the tag name, enter the Public ID of the CDE as the value Enter “CADSR_DE_VERSION” for the tag name, enter the Version of the CDE as the value

Lesson 2: Create a UML Model for caBIG™ Compatibility Creating Associations From the Logical Model Diagram, select the source class Drag the up arrow to the target class Select Association, Aggregation or Generalization Right click on the association -> Association Properties Select the Direction (dropdown list)

Lesson 2: Create a UML Model for caBIG™ Compatibility Naming Associations Click the Source Role tab Enter the role name (className) Add “Collection” if >1 Select the Multiplicity from the dropdown Click OK Do the same for the Target Role tab

Lesson 2: Create a UML Model for caBIG™ Compatibility Inheritance and Multiplicity Multiplicity Indicates the number of objects of the class on that end that may be associated with a single object of the class on the other end Inheritance Indicates that a class is a subclass of another The child class inherits all attributes of the parent class Each Inheritance type association in the UML model is mapped to a caDSR Object Class Relationship with the same attributes described for Associations, except for Object Class Relationship Type, which in this case is “IS_A”.

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Packages – Value Domains Value Domains should be located in a separate folder than the other classes, but still in the Logical Model Package.

Lesson 2: Create a UML Model for caBIG™ Compatibility UML Notations Ignored by SIW/UML Model Loader Stereotypes (other than enumeration) Attribute multiplicity (use -1 to represent many) Options in Class and Attribute Details pages Scope Abstract class Cardinality (always use -1 to represent many) Operations in classes

Lesson 2: Create a UML Model for caBIG™ Compatibility Creating Value Domains - 4 Options 1.Use the UML generated DE as is. i.e. ‘Patient Race Category java.lang.String’ 2.Select an existing Value Domain using the SIW during the Semantic Integration Process 3.Create a Value Domain in your UML Model a)Create a UML Class with a stereotype of “CADSR Value Domain” b)Include appropriate class tags c)See caCORE SDK Programmer’s Guide v1.1 for details 4.Reference a large value list (i.e. >100 items) that is externally described somewhere (and is not in EVS) a)Create new non-enumerated VD, with a Reference Document that points to a specific standard (you do not have to actually instantiate a 1000 item pick list) b)Add value list to EVS or point to a parent concept within the external standard c)Classify the new VD to your Project Classification Scheme

Lesson 2: Create a UML Model for caBIG™ Compatibility Creating a Value Domain in Your Model Create a UML Class with a stereotype of “caDSR Value Domain” or “enumerated” Note: All Value Domains should be put into one package (separate from regular domain objects) Include the following Class Tags (NOTE: this information can be selected using the SIW) CADSR_ValueDomainDefinition CADSR_ValueDomainDatatype caDSR_ValueDomainType CADSR_ConceptualDomainPublicID CADSR_ConceptualDomainVersion Optional semantic tags are given in the SIW Technical Guide

Lesson 2: Create a UML Model for caBIG™ Compatibility Example of a Value Domain Specification

Lesson 2: Create a UML Model for caBIG™ Compatibility UML Class Properties Stereotype Value Domain Name

Lesson 2: Create a UML Model for caBIG™ Compatibility Add PVs for Enumerated VDs Value Meanings are specified as Attributes of a “CADSR Value Domain” Value Meaning Descriptions are added as ‘description’ tags Semantics for Value Meanings are added during the SIW process caDSR Value Meaning will be the Concept Preferred Name If no concept is selected, the supplied ‘description’ tagged value is used Map each attribute to one or more EVS concepts Attribute name = value Concept name(s) = value meaning Concept definition(s) = value meaning description

Lesson 2: Create a UML Model for caBIG™ Compatibility Value Domain Tags

Lesson 2: Create a UML Model for caBIG™ Compatibility Adding Value Meanings for a Value Domain Create a > Class Value Meanings are specified as Attributes of a > Class Model Owner Value Meaning Descriptions are added as ‘description’ tags Semantics for Value Meanings are added during the SIW process, the Value Meaning in caDSR will be the Concept Preferred Name if the VM is associated with a concept, if not, the model supplied ‘description’ tagged value is used

Lesson 2: Create a UML Model for caBIG™ Compatibility Pointing a UML Attribute to a Value Domain If an Attribute in the model uses a Value Domain that is created as part of the model, add a tag named CADSR Local Value Domain specifying the name of the Value Domain. For Example: The Value Domain ‘ProteinType’ would be linked by adding the tag name of CADSR Local Value Domain to the ‘type’ attribute in the ‘Protein’ class with the value of ‘ProteinType’

Exercise Use the step by step instructions to Open an existing model file in Enterprise Architect Add a Class and Attribute to the existing diagram Name Associations Add a Value Domain

Conclusion In a model driven architecture, the model development is the most important step caBIG silver-level compatible services are expected to expose domain information models Reusing portions of existing silver-level compatible service models is helpful in achieving compatibility Use caBIG best practices and knowledge of caBIG tool features (or limitations) to guide your modeling