# Presentation: 415704

## UML Model Development and Registration – Some Things You May not Know

**Session Date: ****	****	****May 4, 2005**
**Session Length:****	****	****30 Minutes**
**Target Audience:****	****	****TBPT Modelers**
**Trainer: ****	****	****	****	****Tommie Curtis ****	****	****	****	****	****	****curtist@mail.nih.gov**
**NCICB Liaison / Expert Curator: ****	****Dianne Reeves ****	****	****	****	****	****	****reevesd@mail.nih.gov**

## Slide 2

## Skills Every Modeler Should Have

- Identify best practices for model/metadata creation
- Recognize well-formed names and definitions
- Understand the Semantic Connector process
- Prepare information for UML Loader registration
- Identify where UML model metadata is being registered in the caDSR
- Create Value Domains and Permissible Values
- Create Comments, Reference Documents, and Related URLs
- Review registered UML metadata
- Approve UML registration to production environment
- Update the model as it changes

## Semantic Integration

**UML Class = ISO Object Class**
- Example: Agent
- ISO Object Classes are mapped to 1 or more concepts from EVS
**UML Class Attribute = ISO Property**
- Example: nSCNumber
- ISO Properties are mapped to 1 or more concepts from EVS
**UML Class + UML Class Attribute = ISO Data Element Concept**
- Agent:nSCNumber
- ISO DEC’s are mapped to 2 or more concepts (from OC + Property)
**UML (Java) Datatype = ISO Value Domain (at least initially)**
- Example: java.lang.Integer
- Enumerated value domains curated after initial UML loading
**UML Class + UML Class Attribute + Datatype/Valid Values = ISO Common Data Element**
- Example: Agent:nSCNumber: java.lang.Integer

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Resources – UML Model Creation

- Time Estimate
- Varies with understanding of UML modeling and modeling tools
- Varies with complexity of the data being modeled
- People
- Model Owner
- VCDE Workspace Mentor
- NCICB UML Loading Staff
- EVS Staff

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Generating XMI for Semantic Interoperability

- Requirements for XMI file:
- XMI 1.1
- UML 1.3
- Unisys/Rose extensions
- Export tagged values
- Include “Logical Model” package
*Exclude diagrams*

## Running the Semantic Connector

- If you know terms/concepts that you will need at not currently in the EVS vocabulary, submit a request to EVS for the addition of the terms prior to running the Semantic Connector.
- Send an email to NCICB@pop.nic.nih.gov with the terms and definitions.
- Include “Terms for EVS” in the subject line.
- Submit the annotated XMI file to NCICB:
- To NCICB@pop.nci.nih.gov
- Include “For semantic connection” in the subject line
- Your model will be run through the Semantic Connector
- A semantic connector report will be generated
- Comma-separated file (CSV)
- Relates terms from diagram to EVS concepts
- Report will be curated, verified and sent to you for approval and submission for loading

**Notes:**
Semantic connector is in the SDK package and can be used as a tool when you are developing your model.  It can be a way of checking availability of terms.

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Semantic Connector Tasks

- Automated Steps
- Match UMLEntity to NCI Thesaurus concept preferred name or synonym
- Divide UMLEntity into space-separated terms at the CamelCase separators – repeat match to NCI Thesaurus preferred name or synonym
- Return match(es) in comma-delimited file
- Update of XMI with annotation terms
- Non-automated Steps
- Addition of new EVS terms/concepts
- Review and selection of terms for model annotation

## Semantic Connector: Report

- Semantic Connector Report BEFORE Human Verification

**Notes:**
The file generated by the semantic connector has a comma-delimited format.  This is what it looks like after import into Excel.

## Semantic Connector: Report

- UMLEntities lacking UMLDescription

**Notes:**
The first thing I’d like to point out is the lack of UMLDescription for many of the UMLEntities.  Most of these seem pretty straight forward (they have face validity).  “clusterId” is rather vague.

## Semantic Connector: Report

- Are the UMLEntity and UMLDescription are consistent with each other?
- Do they match “common meaning”?

**Notes:**
The second thing I’d like you to think about is the “Gene” entity and its description.  Are they consistent with each other?  The entity is “Gene” but the description talks about “Gene object”.  This makes it hard to know if this entity should be mapped to the Thesaurus concept “Gene”, as seen here or if it should be mapped to a new concept called “Gene Object”.  Whenever possible the UMLEntity term should match the common meaning, what 95% of people would think of when they hear the term.  This is what we call face validity.

## Semantic Connector: Report

- Multiple matches for one UMLEntity

**Notes:**
Next, please look at the results for the UMLEntities “id” and “title”.  Each matched multiple Thesaurus concepts.  This is because both preferred names and synonyms are searched on.  In Thesaurus, only the concept name and the concept code need be unique.  Preferred names and synonyms can be redundant.  SO, we carry two instances of “title”, one that refers to a person’s title and one that refers to the title of a document.  Both are returned as possible matches and the annotator, me, must decide which is correct.

## Semantic Connector: Report

- Semantic Connector Report AFTER Human Verification – Step 1

**Notes:**
After the first pass at annotation, matches are accepted or rejected and multiple matches are reduced to a single match.  The “Human Verified” column is than changed to “1”.

The types of questions that are asked during the review include:

Is the Entity and Description meaning consistent with an existing, unmatched Thesaurus concept?
Does Entity and Description meaning correspond to a "common usage" term not presently in Thesaurus?
Can the Entity be broken into "meaning units" that can be recombined into a compound term with a meaning consistent with the description; will the meaning units have potential for reuse for UMLEntities or elsewhere in the terminology?
If the Entity lacks a Description, does the Entity seem to correspond to a "common usage" term or can it be broken into multiple common usage terms?
If the UMLEntity is a UMLClass, is it so abstract as to have no outside, concrete meaning?
Failing this, return the Entity to package owner for clarification

## Semantic Connector: Report

- Semantic Connector Report AFTER Human Verification – Step 2

**Notes:**
During the second pass those entities that failed to find a match get mapped.  As you can see here, a single UMLEntity may be mapped to several Thesaurus concepts.  The rule is that there is a primary match and one or more “qualifiers”.

## Problems and Pitfalls

- The needed terms are not registered in NCI Thesaurus
- Multiple matches are found for a single term
- UML Model is changing during the review process
- Model requires multiple passes through the Semantic Connector

## Resources – Semantic Annotation of UML Models

- Time Estimate
- Effected by the availability of terms/concepts in EVS – may need multiple cycles if the terms are initially available
- Increased by model changes
- Requires training in understanding the Semantic Connector reports
- People
- Model Owner
- EVS Reviewer
- VCDE Workspace Mentor

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Content of the UML Loader Package

- UML Loader Submission Form
- Classification Scheme (Project Name) with brief description
- Version Number
- UML Package(s) Alias and Relationships
- Context for Loading
- Workflow Status
- Datatypes Used in Model
- Annotated XMI (terms from the Semantic Connector have been added to the XMI)
- Final Semantic Connector Report
- Point of Contact Name, Email, and Telephone Number
- * Required information

## Submit the Model for UML Loading

- Submit the annotated XMI file to NCICB:
- To NCICB@pop.nci.nih.gov
- Include “For UML Loading” in the subject line

## Running the UML Loader

- Your model will be loaded by NCICB staff using the UML Loader
- The load process will be verified by NCICB staff
- You will receive an email requesting you to review the load in the Stage environment

## Resources – UML Loading

- Time Estimate
- Effected by completeness of UML Load Package and availability of the Point of Contact
- People
- Model Owner
- NCICB UML Loading Staff

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Prepare Submission Package
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Steps for UML Model Review and Curation

- Access into Stage for initial review
- Address questions to NCICB staff/VCDE Workspace Mentor
- Approve model load in Stage
- Load into Production for curation of additional metadata
- Review final metadata in Production
- Release for public use

## Staging Review – Is everything in the model registered?  Visible with current tools

- Object Classes (SDK, p. 84)
- Are all Classes represented by Object terms?
- Data Element Concepts (SDK, p 29, 112)
- Are all Class/Attribute pairs represented by DECs?
- Do all DECs have Object Classes and related EVS term CUIs?
- Data Elements (SDK, p. 55, 113)
- Are all Attributes in the model registered?
- Are there Attributes that are not in the model registered?
- Naming and Definitions (SDK, p. 112 – 113)
- Are Alternate, Preferred, and Long Name formatted correctly?
- Do all Objects, Data Element Concepts and Data Elements have Alternate Definitions?
- Datatypes (SDK, p. 55)
- Does the Representation term in the Data Element match the datatype in the model?

**Notes:**
Data Element Concepts 
The relationship between a class and one of its attributes is represented by a caDSR Data Element Concept.  A DEC is based on a caDSR Object Class that corresponds to the UML Class and a caDSR Property that corresponds to the UML class attribute.  UML Loader creates a DEC based on the details if it does not already exist.  If it exists, it is re-used and an appropriate classification is assigned.
Related EVS Terms 
All UML classes and attributes are mapped to EVS concept codes.  It is the association with concept codes that permits unambiguous interpretation of UML model objects and mapping between objects in different domains.  The resulting data elements will be more sharable and interoperable.
Data Elements
You want to ensure that all attributes from the model are in the caDSR and you also want to look for attributes that are in the caDSR but not in the loaded model.
Naming
Because semantic interoperability, special care in selecting a class and attribute names are essential.  The caCORE follows that formatting convention for JAVA APIs in that a class starts with an uppercase letter and an attributes starts with a lowercase letter.  Names contain no underscores.  If the name contains two words, the second word is capitalized, with no spaces between words.  If an attribute contains two words, the second word is capitalized with no space between words.

DEC definitions
Definitions are derived from the Object class preferred definition and Property preferred definition.  A colon is used as a separator character between the two values.

DE definitions 
Definitions are  derived from the DEC preferred definition and the Value Domain definition.  The separator character is a colon.

Datatypes
You also want to ensure that the representation term match the datatype in the model.

## Staging Review – Is everything in the model registered?  Not visible with current tools.

- Relationships (SDK, p. 58)
- Are all Associations and Generalization (or Inheritance) relationships represented correctly?
- Specification of Multiplicities (SDK, p. 30, 117)
- Are all instances recorded correctly?
- Direction (SDK, p. 30)
- Are all directional associations specified as entered in the model?
- Role Names for Associations between Classes (SDK, p. 59)
- Are Roles named correctly?

**Notes:**
Currently these items are registered in the caDSR but are not visible with in the user interface.

Relationships
To recap the following are allowable relationships.  Association, Aggregation, and Generalization or Inheritance Relationships.  Aggregations and compositions are allowed in the model but treated the same as simple Associations.
Multiplicities
A UML relation can have a label providing additional semantic information, as well as numerical ranges such as 1..n at its endpoints, called multiplicity.  These cardinality constraints indicate that the relationship is one-to-one, one-to-many, many-to-one, or many-to-many, according to the ranges specified and their placement.
Directionality
UML relations can either be uni-directional or bi-directional.
Role Names
Role name is the same as the Class but starts with a lowercase letter
If multiplicity is more than 1, the Role name must end with the word Collection.

## Problems and Pitfalls

- Model Classes/Attributes not registered in caDSR
- Missing from submitted model
- Not entered in model correctly
- Semantic information not recorded in XMI file
- caDSR has Classes/Attributes not seen in model
- Inconsistent naming
- Should not have been exported in XMI file
- Missing Definitions
- Missing Objects, Properties, and/or Representations
- Improper Datatypes
- Used Datatype not registered in caDSR
- Wrong Datatype selected during registration

## Finding the Metadata

**Notes:**
This is a snap shot from EA.  The domain, Agent and the associated attributes.

## Admin Tool Search for Object Class

**Notes:**
You can begin comparing the model to what is in EA to what is in the tools.  Here is a look at the Admin tool.  Begin by searching on the Object Class for agent.

## Object Class Search

**Notes:**
You will see the list of Related Data Element Concepts for Agent.  You will notice that the long name is the same list of attributes from the model.  The definition is the thesaurus definition.  You will also see the Public ID, Version, Workflow Status, and Context.  If you take the first Public ID number 2216122 and search on the Data Element Concept (next slide).

## Resources – UML Model Review

- Time Estimate
- Varies with complexity of model
- Requires training in usage of tools
- People
- Model Owner
- Curator
- NCICB UML Loading Staff
- VCDE Workspace Mentor

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Content of the Submission Package

- UML Model File (EA Preferred), include diagram
- Final Semantic Connector Report
- Enumerated Permissible Value Lists with Value Meanings
- Point of Contact Name, Email, and Telephone Number
- Data Dictionary
- User Documentation
- * Minimum required information

## Steps for Curation

- Replace initial Value Domains with enumerated Value Domains as needed
- Add Explanatory Comments
- Associate Reference Documents, Files, or URLs

## Problems and Pitfalls

- Generic value domains are assigned during registration
- Supplemental materials for permissible values not available
- Datatypes are not available, mapping or addition of new types may be needed before curation
- List of values may be entered or referenced

## Adding Supplemental Information

- Requires Manual Curation using the Admin Tool
- Comments
- Reference Documents
- Related URL’s

## Resources – Manual Curation of Additional Metadata

- Time Estimate
- Varies with the number of items to be entered
- Includes time for changes and corrections
- Depends of availability of supporting information
- Requires training in usage of curation tools
- People
- Model Owner
- Curator
- QA Reviewer
- VCDE Mentor

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Final Production Review – Is everything in the model registered?  

- Review 2-4 Classes and Attributes to ensure correct registration
- Check all editorial changes to verify correct completion
- Review all new Value Domains and Permissible Values
- Ensure that the model displays in the Browser tree
- Notify caDSR team of acceptance of the model registration

**Notes:**
Review 2-4 Classes and Attributes to ensure correct registration – the metadata registration in Production should be the same as was seen in Staging, however, a quick check should be done to verify.

Check all editorial changes to verify correct completion – data changes will be made in Production and must be reviewed there to ensure they were all made correctly.

Review all new Value Domains and Permissible Values – new Value Domains and associated Permissible Values will be created in Production and must be reviewed there to ensure everything was created correctly.

Ensure that the model displays in the Browser tree – in order for the model to display in the Browser tree the Classification Scheme where it is registered must be in the Released workflow status.  Models may not be released prior to final review by the model owner so checking will need to be done in Curation or Admin.

Notify caDSR team of acceptance of the model registration – the model owner will give final approval on the metadata content to the caDSR team.

## Problems and Pitfalls

- The model may not have transferred correctly from Stage to Production
- Editorial changes may not have been made or were made incorrectly
- New Value Domains may not have been correctly created
- Permissible Values may be missing or incorrectly assigned

## Resources – Model Owner Approval

- Time Estimate
- Varies with complexity of model
- Requires training in the usage of tools
- People
- Model Owner
- NCICB UML Loading Staff
- Curator
- QA Reviewer
- VCDE Mentor

## UML Model Creation, Registration, and Curation

- Create Model
- Run Semantic Connector
- Semantic Annotation of UML Models
- Run UML Loader
- Review Stage/Production Registration
- Curate Additional Metadata
- Model Owner Approval
- Model Maintenance and Versioning

## Resources – UML Maintenance

- Time Estimate
- Varies with frequency and complexity of model change
- People
- Model Owner
- EVS staff
- NCICB UML Loading staff
- VCDE Workspace Mentor
- Curator

## Thank you to various team members who contributed to this presentation

**Overview - George Komatsoulis**** **
**UML Model Creation - Nafis Zebarjadi **
**Semantic Connector Review – Nicole Thomas**
**UML Loader**** - ****Ram Chilukuri**
**Data Review and Curation – Brenda Maeske**

## Questions?