Issues for Mailing list of the second Phenotype and Genotype Object Model 1.0 (PAGE-OM)Finalization Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 12995: reference to an OMG rooted URL
Issue 12996: The PSM namespaces should be rooted on the OMG spec directory URL
Issue 12997: There are missing attributes 'schemaLocation' in the *.xsd files.
Issue 12998: remove duplicated attributes
Issue 12999: change name of some associations
Issue 13000: duplicated attributes and associations
Issue 13001: Rename the association from Consensus_genomic_genotype to Latent_genotype
Issue 13002: Remove the inheritance from Identifiable in Set_of_haplotypes.
Issue 13003: Rename the association from Multi_variation_assay to Genomic_variation
Issue 13004: redundant association from Enum to Value.
Issue 13005: remove stereotypes
Issue 13006: Do not include the XSD stereotypes for the classes in the PIM.
Issue 13007: Move association
Issue 13008: Rename attribute 'sex' in snp2::Individual to 'gender'.
Issue 13009: several unsufficient cardinalities should be revised
Issue 13010: Add a new inheritance relationship
Issue 13011: Figure 7.5: The description of the Identifiable is not fully correct
Issue 13012: Clarify conformance section
Issue 13023: PAGE-OM: top level XML tag
Issue 13055: abstract Genotype_phenotype_correlation_experiment
Issue 13806: textual descriptions of the model objects are nearly completely absent
Issue 13807: Figures are sometimes unexplained
Issue 13808: Associations in the model not really documented
Issue 13809: no statement that the spec was normative
Issue 13810: Seven concepts
Issue 13811: Diagrams are confusing and hard to read
Issue 13812: The spec occasionally calls out "human genetics" but nowhere says that it limits itself to humans
Issue 13813: The modeling tool used (Sparx EA) is inadequately referenced in several places,
Issue 13814: There is no acronym table
Issue 13815: References to other specs, OMG and external, are very weak and poorly stated
Issue 13816: "accompanied files",
Issue 13817: PAGE-OM package
Issue 14018: PAGE-OM issue: missing cardinalities
Issue 14019: PAGE-OM issue: most attributes should be optional
Issue 14036: PAGE-OM issue: errors in associations

Issue 12995: reference to an OMG rooted URL (page-om-ftf)

Change the following reference to an OMG rooted URL: "For convenience,
the whole PAGE-OM specification can be seen at
http://www.openpml.org/page-om/model/."

Suggested resolution: Change it but not to the OMG rooted URL but to
this one: http://www.pageom.org/models/omg/v_1.0/

Suggested solution: Change namespaces in the generated PSM (XML
Schema) to the following:

* http://www.omg.org/spec/PAGE-OM/20081231/snp
* http://www.omg.org/spec/PAGE-OM/20081231/snp2
* http://www.omg.org/spec/PAGE-OM/20081231/fuge
* http://www.omg.org/spec/PAGE-OM/20081231/page
* http://www.omg.org/spec/PAGE-OM/20081231/bref 

There are missing (even though optional) attributes 'schemaLocation'
in the *.xsd files.

Suggested resolution: In all generated XML Schemata (the PSM model,
the *.xsd files), add the 'schemaLocation' attribute to the import
tags. For example:

<xs:import namespace="http://www.openpml.org/page-om/fuge" schemaLocation="fuge.xsd" />
<xs:import namespace="http://www.openpml.org/page-om/snp" schemaLocation="snp.xsd" />
<xs:import namespace="http://www.openpml.org/page-om/snp2" schemaLocation="snp2.xsd" />

Some classes (listed below in the suggested resolution) that inherit
from Identifiable should not have duplicated attributes (because they
are redundant).

Suggested resolution:

In bref::Bibliographic_reference, remove the second Provider
association.

In bref::Journal, remove the 'name' attribute.
In snp::Organization, remove the 'name' attribute.
In snp::Map, remove the 'name' attribute

There are associations whose names contain spaces (listed below in the
suggested resolution). For some tools, it would be better to replace
them by underscores.

Suggested resolution:

Rename association "derived from" (Consensus_genomic_genotype) to
"derived_from".

Rename association "is treated as" (Gene_variation) to
"is_treated_as".

Rename association "one of" (Genomic_allele) to "one_of".

In some classes (listed below in the suggested resolution), there are
duplicated attributes and duplicated asociation targets in the
(generated) PSM model (in the XML Schem). It is caused by the problem
in the tool (EA) when converting into XML Schema the "diamond
inheritance" in the model.

Suggested resolution:

Remove duplicated attributes from PSM (snp.xsd) of the Sequence tag:
creation_date, delete_date, lsid, modify_date, name.

Remove duplicated association targets from PSM (snp.xsd) of the

Remove duplicated attributes from PSM (snp.xsd) of the Residue_Change
tag: creation_date, delete_date, lsid, modify_date, name.

Remove duplicated association targets from PSM (snp.xsd) of the
Residue_Change tag: Annotation, Publication, Db_Xref, Source.

It is necessary to name the association from
Consensus_genomic_genotype to Latent_genotype as
"latent_consensus_genotype" because there is another association using
already the default name.

Suggested resolution:

Rename the association from Consensus_genomic_genotype to
Latent_genotype.

Probably by mistake, there is a redundant inheritance from
Identifiable in Set_of_haplotypes.

Suggested resolution: Remove the inheritance from Identifiable in
Set_of_haplotypes.

Probably by mistake, there is a redundant association from
Multi_variation_assay to Genomic_variation.

Suggested resolution: Rename the association from
Multi_variation_assay to Genomic_variation. Because it has the same
semantic as the assotiation from Varriation_assay.

Probably by mistake, there is a redundant association from Enum to
Value.

Suggested resolution: Keep the association from Enum to Value, but
name the association between Value and Value as "hierarchical_value".

The PIM (as expressed in the XMI and text descriptions) should not
include XSD specific stereotypes for the UML classes (with the
exception of the basic types package, because PAGE-OM uses a subset of
xsd types for primitive types).

Suggested resolution: Remove these stereotypes, either by finding the
appropriate option in the EA tool, or by manual removing them from the
generated XSD.

The diagrams in the final document should not include the XSD
stereotypes for the classes in the PIM.

Suggested resolution: Because the diagrams are generated by the EA
tool and it may be difficult to force this tool not to display the
stereotypes, and because the diagrams are only illustrative, this
issue is rejected

Because the diagrams are generated by the EA
tool and it may be difficult to force this tool not to display the
stereotypes, and because the diagrams are only illustrative, this
issue was rejected.
Disposition:	Closed, no change

The association between snp2::Frequency and snp2::Panel should be
elsewhere because the frequency of individuals is needed for somatic
mutations and copy number variations.

Suggested resolution: Move the association between snp2::Frequency and
snp2::Panel to an association between snp2::Frequence and
snp2::Abstract_observation_target.

There is a concern about the attribute name 'sex' that does not
represents completely what the PAGE model expresses.

Suggested resolution: Rename attribute 'sex' in snp2::Individual to
'gender'.

There are several unsufficient cardinalities (listed below in the
resolution). They should be revised to serve better their scientific
purpose.

Suggested resolution:

Change cardinality of the association between snp2::Latent_genotype
and snp2::Latent_genotype_specification from '1 to many' to 'many to
many'.
	
Change cardinality of the association between page::Observed_value and
page::Experiment_result from 'many to 1' to 'many to many'.

Change cardinality of the association between
page::Genotype_phenotype_correlation_experiment and
page::Experiment_result from '1 to many' to 'many to many'.

From the users and scientists points of view, it is thought that there
is a missing a direct connection between Genomic_allele and
Genomic_observation. This is very much needed because the Locus
Specific Databases (LSDBs) and diagnosic labs need direct association
from allele to abstract observation target.

Suggested resolution:

Add a new inheritance relationship: The snp2::Genomic_allele should
inherit from snp2::Genomic_observation.
	

The description of the Identifiable is not fully correct. It says (by
the Figure 7.5):

"All classes in the model inherit from Identifiable. In this way,
their instances are uniquely identifiable. Any Identifiable instance
must have either attribute 'id', or attribute 'LSID'. Usually, an 'id'
is used to identify an instance within a known context, and the 'LSID'
is used when cross-referencing to a different context. The 'LSID'
attribute follows syntax as defined in the OMG Life Sciences
Identifiers specification.

But the PAGE model does not include any attribute "id".

Suggested resolution: Replace the text mentioned above by the
following:

"All classes in the model inherit from Identifiable. In this way,
their instances are uniquely identifiable. Any Identifiable instance
must use its "lsid attribute". For this attribute, it is recommended
to use the OMG Life Sciences Identifier specification."

In the Conformance section the following sentence does not make it
clear whether or not the PSM schemas define the "data exchange format"
mentioned:

"Any implementation using or producing given data exchange format is
considered complying with this specification."

Suggested resolution: Replace the text above by:

"Any implementation using or producing data exchange format defined by
the Platform specific model defined by this specification is
considered complying with this specification."

The PSM (the XML Schema) does not have any top-level tag. Its absence makes it very hard to produce a real-life data in this data exchange format.

Suggested solution: Add a new file, named all.xsd, that includes (imports) all so far defined xsd files, that defines the top level tag "page", and that also defined a list of tags (from the existing PSM) that can be the direct children of the top-level "page" tag. The list has to be yet defined by the FTF members.

Genotype_phenotype_correlation_experiment was defined as abstract
class. This is clearly a mistake.

Suggested resolution: Change class
'Genotype_phenotype_correlation_experiment' to a non abstract one
in the PIM.

All of the model objects seem to be listed, and there are some diagrams, but textual descriptions of the model objects are nearly completely absent. Those that exist are often (but not always) merely copied from the glossary. There is little (often no) semantic descriptions of model objects that would help the reader understand their intent. purpose, or best usage.

Figures are sometimes unexplained and arrangement (ie, poor paging) of the figures and text that does exist lead to misunderstandings on first reading.

There are a lot of associations in the model but not one of them is documented in any fashion beyond listing names and the classes they connect. Cardinalities can be found in the diagrams but direct documentation of the associations and their use is necessary to convey the intent of the specification. Associations should be individually documented to the extent that a reader can determine the characteristics of each association, its name, and the names, multiplicity, and ocnstraints of its ends in a single place in the spec. The reader should not have to harvest association characteristics scattered around figures and text.

I found no statement that the spec was normative. There's a discussion of conformance but it is quite inadequate and I'd bet it's missing some important points. There is discussion about the XML/XMI files being normative, but not the spec. Please review the Conformance section for completeness.

The Introduction describes that the model is packaged into seven concepts that can be used independently. This is a cool idea. But the oganization of the rest of the spec does not support identification of those seven concepts or how they might be isolated so that can be used independently. Naming of the model subdivisions does not even match the stated concepts. Do these seven concepts raise any conformance issues?

Diagrams are confusing and hard to read -- lines overlapping boxes, too many objects in figures, little or no explanations. Graphics conventions (such as box color shading) are not discussed but seem to be meaningful. Perhaps the figures can be broken up into smaller, target fragments that are specific to sets of related class and distributed to relevant locations in the spec?

The spec occasionally calls out "human genetics" but nowhere says that it limits itself to humans. Seems to me it would work for any organism, so "human" references should be removed.

The modeling tool used (Sparx EA) is inadequately referenced in several places, meaning that a causal reader would not necessarily be able to find the correct tool on the internet. At minimum, cite the Sparx URL.

There is no acronym table. For example, two major sections of the model are called "SNP" and "SNP2" but nowhere does the spec say that "SNP" means "Single Nucleotide Polymorphism". There are a number of other examples.

References to other specs, OMG and external, are very weak and poorly stated. A table of referenced external documents would seem essential. There are (strong?) hints that some motel objects specialize objects from other specs but which ones and from where are thoroughly obscure. The spec seems to assume substantial knowledge of other LifeSciences TF specs; this is not necessarily bad, but it should say so explicity and identify the referenced specifications precisely.

In a number of places the spec refers to "accompanied files", meaning the XML and XMI files that come with the specification. The correct phrase for such files should probably be "accompanying files".

I understand that the PAGE-OM package was added in response to Issue #13023. However, the role of the contained class "Page" (Section 7.1.1.1) is thoroughly unclear. Please document the purpose of the Page class and the reason that it contains 69 associations, apparently one to every other class in the model. If you can't clearly document the purpose of this class and its associations, you should remove it. Note also that the name of the class "Page" (Section 7.1.1.1) conflicts with the "PAGE" package (Section 7.1.2); this may not generate a syntax error in most tools, but it is certainly confusing for the human reader.

In page-om model there are some missing cardinalities, which means  
that default cardinality (one-to-one) is used, which is wrong.
For example association between Assayed_genomic_genotype and  
Observation_target

All attributes are now mandatory in the model, but most of them should  
be optional.
For example creation_date in Identifiable.

Association from Frequency to Variation_assay should be many to 0..1
Association from Frequency to Genomic_variation should be many to 0..1
Association from Assayed_genomic_genotype to  
Abstract_observation_target should be many to 1


Reference_genomic_location_in_assembly has redundant relationship to
reference_genomic_assembly.  Remove association


Directionality is wrong between Haplotype_derivation_method and  
Genomic_haplotype.
Reverse directionality


Directionality is wrong between Haplotype_derivation_methods and  
Consesus_genomic_genotype.
Reverse directionality