Question about Ocean's Archetype Editor

Hello,

I’m trying to figure out which reference model Ocean’s achetype editor follows. I have an example regarding the data type Quantity, see below. There seems to be great differences depending on what reference model the archetypes follow.

Background:
I’m trying to figure out how to get the property of a quantity but this doesn’t seem to be supported by the java kernel I’m using, so I’m asking if anyone has a good idea on how to support this in other ways.

The current problem is that the java adl parser returns a CQuantity object whenever it recognizes the string “quantity”, but when it’s something else, e.g. C_QUANTITY, it returns a CComplexObject.

Idea:
I could solve this by looking up the RM type names and the attribute names to figure out if the ComplexObject represents something that can be interpreted as a Quantity data type. In this way I can support the various known structures of the data type that currently exist. Any suggestions?

By the way, shouldn’t the property attribute represent a CODED_TEXT object that can be linked to a local or external terminology? This seems to be the case according the specifications and it goes all the way back to version 0.9 that I think the current version of the java kernel supports (partly at least). I would really like to know what RM Ocean’s archetypes follows.

Ocean Archetype Editor archetype:

C_QUANTITY <
property = <“Acceleration”>
list = <
[“1”] = <
units = <“cm/s2”>
magnitude = <|< 0.0|>

[“2”] = <
units = <“ft/s2”>
magnitude = <|>= 0.0|>

Ref impl java kernel archetype:

QUANTITY matches {
magnitude matches {|<0.0|}
units matches {“cm/s2”}
}

Acode ADLParser test achetype:

REAL_QUANTITY matches {
property matches {“Acceleration”}
units cardinality matches {1} matches {
UNIT matches {
unit_string matches {“cm/s2”}
magnitude matches {|< 0.0|}
}
UNIT matches {
unit_string matches {“ft/s2”}
magnitude matches {|>= 0.0|}
}
}
}

Regards,

Mattias Forss

Mattias Forss wrote:

Hello,
I'm trying to figure out which reference model Ocean's achetype editor follows. I have an example regarding the data type Quantity, see below. There seems to be great differences depending on what reference model the archetypes follow.

I pretty sure that the reference model is the same in all cases. There is only one definition of DV_QUANTITY in the openEHR reference model, and as far as I know, only one assumed in archetypes.

However, it may look different. There are two ways of representing constraints on Quantity in an archetype. One is to use the 'standard' method of creating C_COMPLEX_OBJECTs which mimic the sructure of the QUANTITY class; the other is to use an instance of C_QUANTITY, which is a custom replacement type which provides a better model of the possible constraint on QUANTITY (while still assuming the same underlying definition of QUANTITY).

To see this difference illustrated, see the C_QUANTITY archetype at http://my.openehr.org/wsvn/knowledge/archetypes/dev/adl/test/clinical_types/?rev=0&sc=0

A detailed explanation for why we do this is in section 10 of http://svn.openehr.org/specification/BRANCHES/Release-1.0-candidate/publishing/architecture/am/adl.pdf

Background:
I'm trying to figure out how to get the property of a quantity but this doesn't seem to be supported by the java kernel I'm using, so I'm asking if anyone has a good idea on how to support this in other ways.

the property attribute is defined only in the type C_QUANTITY. It provides a convenient way to capture the constraint that you want only length or pressure, without saying which unit. If only the property is set in the C_QUANTITY in the archetype, then when the kernel checks to see if an instance of DV_QUANTITY conforms to the C_QUANTITY in the archetype, it is up to the C_QUANTITY to carry out this check in sensible way, i.e. by determining what property the actual units measure.

The current problem is that the java adl parser returns a CQuantity object whenever it recognizes the string "quantity", but when it's something else, e.g. C_QUANTITY, it returns a CComplexObject.

I'm not familiar with the inner workings of the java parser, so I don't understand what is happening here.

Idea:
I could solve this by looking up the RM type names and the attribute names to figure out if the ComplexObject represents something that can be interpreted as a Quantity data type. In this way I can support the various known structures of the data type that currently exist. Any suggestions?
By the way, shouldn't the property attribute represent a CODED_TEXT object that can be linked to a local or external terminology?

this is true; we watered it down to make people in CEN and HL7 happy, but I no longer believe such compromises are sensible. We will probably change this to a CODED_TEXT.

This seems to be the case according the specifications and it goes all the way back to version 0.9 that I think the current version of the java kernel supports (partly at least). I would really like to know what RM Ocean's archetypes follows.

C_QUANTITY <
property = <"Acceleration">
list = <
  ["1"] = <
   units = <"cm/s2">
   magnitude = <|< 0.0|>
   >
  ["2"] = <
   units = <"ft/s2">
   magnitude = <|>= 0.0|>
   >
  >
>
>

this is a C_QUANTITY instance, expressed in dADL, embedded in the cADL section of an archetype.

Ref impl java kernel archetype:
QUANTITY matches {
     magnitude matches {|<0.0|}
     units matches {"cm/s2"}
}

this is a constraint on the same kind of QUANTITY, but expressed in standard cADL.

Acode ADLParser test achetype:
REAL_QUANTITY matches {
property matches {"Acceleration"}
units cardinality matches {1} matches {
  UNIT matches {
   unit_string matches {"cm/s2"}
   magnitude matches {|< 0.0|}
  }
  UNIT matches {
   unit_string matches {"ft/s2"}
   magnitude matches {|>= 0.0|}
  }
}
}

This one does not match any kind of QUANTITY model in openEHR that I remember; certainly from 0.9 onward, it has not changed much. I think if you ask the Acode guys, you will find that they have used some other model for some reason. (I am even wondering if one of my very early examples of what an archetype might look like in ADL from a few yeras ago might have looked like this, but in fact none of our archetypes or reference models do. It looks more like some HL7-ish example perhaps done for an HL7 meeting).

hope this helps

- thomas beale

Mattias Forss wrote:

Hello,
I'm trying to figure out which reference model Ocean's achetype editor follows. I have an example regarding the data type Quantity, see below. There seems to be great differences depending on what reference model the archetypes follow.

I pretty sure that the reference model is the same in all cases. There is only one definition of DV_QUANTITY in the openEHR reference model, and as far as I know, only one assumed in archetypes.

Thank you for your answer Thomas,

I bet the reference model is the same, but do the Ocean archetype editor fully conform to the reference model? Take a look at the ITEM_TREE class definition for example. You will see that the correct attribute for the physical representation of the tree will be either "representation" for version 0.9 of the specifications or "root" for version 0.95+ of the specifications. However, the Ocean archetype editor does not use neither of these attributes, instead it uses "items" but maybe this is correct if the editor conforms to an earlier version of the specifications than 0.9. Anyone who knows about this?

However, it may look different. There are two ways of representing constraints on Quantity in an archetype. One is to use the 'standard' method of creating C_COMPLEX_OBJECTs which mimic the sructure of the QUANTITY class; the other is to use an instance of C_QUANTITY, which is a custom replacement type which provides a better model of the possible constraint on QUANTITY (while still assuming the same underlying definition of QUANTITY).

This is interesting, but I'm getting slightly confused about the naming here. Could you explain more and tell me the difference between QUANTITY, C_QUANTITY and C_DV_QUANTITY. It is probably a lot easier to grasp for someone like you.

I believe the C_QUANTITY corresponds to the CQuantity (inherits from CDomainType) class in the java reference kernel, and the parser gives me this object if the archetype looks like Q1. Nevertheless, I'm starting to think that this isn't right and that the parser instead should give me the CQuantity object if the archetype looks like Q2. What do you think? By the way, should there exist a class called Quantity in the java kernel or maybe it is sufficient with the CComplexObject (that mimics the structure of the QUANTITY class)?

Q1:

QUANTITY matches {
     magnitude matches {|<0.0|}
      units matches {"cm/s2"}
}

Q2:

C_QUANTITY <
  property = <"Acceleration">
  list = <
   ["1"] = <
    units = <"cm/s2">
    magnitude = <|< 0.0|>
    >
   ["2"] = <
    units = <"ft/s2">
    magnitude = <|>= 0.0|>
    >
   >
  >

Background:
I'm trying to figure out how to get the property of a quantity but this doesn't seem to be supported by the java kernel I'm using, so I'm asking if anyone has a good idea on how to support this in other ways.

the property attribute is defined only in the type C_QUANTITY. It provides a convenient way to capture the constraint that you want only length or pressure, without saying which unit. If only the property is set in the C_QUANTITY in the archetype, then when the kernel checks to see if an instance of DV_QUANTITY conforms to the C_QUANTITY in the archetype, it is up to the C_QUANTITY to carry out this check in sensible way, i.e. by determining what property the actual units measure.

I'm not getting this... as an example, do you mean that a C_QUANTITY with its property set to "length" is supposed to check if "meters" or "inches" in the DV_QUANTITY conforms to this C_QUANTITY? How is it supposed to do that, it seems to me that the C_QUANTITY then must know what allowable units there can be for the length property. Where are those units supposed to be stored if only the property is set in the C_QUANTITY?

By the way, shouldn't the property attribute represent a CODED_TEXT object that can be linked to a local or external terminology?

this is true; we watered it down to make people in CEN and HL7 happy, but I no longer believe such compromises are sensible. We will probably change this to a CODED_TEXT.

Ok, I suppose you're referring to the Ocean archetype editor now?

Regards,

Mattias

Mattias Forss wrote:

Mattias Forss wrote:

Hello,
I'm trying to figure out which reference model Ocean's achetype editor follows. I have an example regarding the data type Quantity, see below. There seems to be great differences depending on what reference model the archetypes follow.

I pretty sure that the reference model is the same in all cases. There is only one definition of DV_QUANTITY in the openEHR reference model, and as far as I know, only one assumed in archetypes.

Thank you for your answer Thomas,

I bet the reference model is the same, but do the Ocean archetype editor fully conform to the reference model? Take a look at the ITEM_TREE class definition for example. You will see that the correct attribute for the physical representation of the tree will be either "representation" for version 0.9 of the specifications or "root" for version 0.95+ of the specifications. However, the Ocean archetype editor does not use neither of these attributes, instead it uses "items" but maybe this is correct if the editor conforms to an earlier version of the specifications than 0.9. Anyone who knows about this?

Hm, good point. I will bring that up with the Archetype Editor team....

However, it may look different. There are two ways of representing constraints on Quantity in an archetype. One is to use the 'standard' method of creating C_COMPLEX_OBJECTs which mimic the sructure of the QUANTITY class; the other is to use an instance of C_QUANTITY, which is a custom replacement type which provides a better model of the possible constraint on QUANTITY (while still assuming the same underlying definition of QUANTITY).

This is interesting, but I'm getting slightly confused about the naming here. Could you explain more and tell me the difference between QUANTITY, C_QUANTITY and C_DV_QUANTITY. It is probably a lot easier to grasp for someone like you.

Actually, we habitually don't put the DV_ in data types in the archetypes. But the intention is that they are the openEHR data types. We originally used the DV_ in the data types to a) make it clear they were data types, and b) to avoid name clashes with other built-in classes like Boolean or State or whatever. In hindsight, it might have bene better not to have done this, but it doesn't matter really. In the archetypes however, some people object if they see DV_ because they know it means openEHR, whereas if they don't see it, they feel comfortable - even if the implied model is exactly the same!

We are working on getting people to understand that the model on which clinical archetypes are based - if they are to be sharable - must itself be seen as a standardised ontology. Thus the function of the openEHR RM is as a "base domain ontology" for clinical computing, a suitable basis for archetypes. The fact people are able to build so many successful archetypes shows that the underlying model is relatively good for this purpose.

So in the future, it may be that a subset of openEHR will be standardised for this purpose: a domain base ontology for EHR and other clinical computing purposes. In such an ontology, there would be no DV_. Such is the politics and psychology of international standardisation.

C_QUANTITY on the other hand is a class whose instances are constraints on a QUANTITY (DV_QUANTITY).

I believe the C_QUANTITY corresponds to the CQuantity (inherits from CDomainType) class in the java reference kernel, and the parser gives me this object if the archetype looks like Q1. Nevertheless, I'm starting to think that this isn't right and that the parser instead should give me the CQuantity object if the archetype looks like Q2. What do you think? By the way, should there exist a class called Quantity in the java kernel or maybe it is sufficient with the CComplexObject (that mimics the structure of the QUANTITY class)?

well, I don't know how Acode have built the parser, but I agree with what you say above. In the Eiffel reference ADL parser, Q1 would generate a C_COMPLEX_OBJECT and Q2 would generate a C_QUANTITY.

the property attribute is defined only in the type C_QUANTITY. It provides a convenient way to capture the constraint that you want only length or pressure, without saying which unit. If only the property is set in the C_QUANTITY in the archetype, then when the kernel checks to see if an instance of DV_QUANTITY conforms to the C_QUANTITY in the archetype, it is up to the C_QUANTITY to carry out this check in sensible way, i.e. by determining what property the actual units measure.

I'm not getting this... as an example, do you mean that a C_QUANTITY with its property set to "length" is supposed to check if "meters" or "inches" in the DV_QUANTITY conforms to this C_QUANTITY? How is it supposed to do that, it seems to me that the C_QUANTITY then must know what allowable units there can be for the length property. Where are those units supposed to be stored if only the property is set in the C_QUANTITY?

the C_QUANTITY needs access to shared units tables. I don't know what the Acode code does here, but we have this implemented in the .Net version; the underlying tables can be made available if you want them (in fact, they are probably in the knowledge_tools_dotnet repository somewher,e but I don't know where off-hand; let me know if you need that).

By the way, shouldn't the property attribute represent a CODED_TEXT object that can be linked to a local or external terminology?

this is true; we watered it down to make people in CEN and HL7 happy, but I no longer believe such compromises are sensible. We will probably change this to a CODED_TEXT.

Ok, I suppose you're referring to the Ocean archetype editor now?

Iin the AOM as well.

- thomas

Mattias and Tom

First point Tom has covered - we use the archetype model constraint classes. These can be made TOTALLY openEHR if required, but I think we will do better from an acceptance point of view to go with more generic type names (ie without the DV_). This could be changed in future if people preferred.

The issue about using items as the attribute of ITEM_STRUCTURE (an abstract class) is interesting and one that had not reared its head for those at Ocean working on this. The fact is that we are using the path statements as the glue between the classes in the model. This is how you need them to be when you are applying them - but it is not strictly the reference model classes. This allows a generic statement about constraints on an abstract structure such as ITEM_STRUCTURE as we only need to address items (rather than root, item, items etc).

The path statements generated from this approach apply in the design environment and in the run time data collection environment - there are a lot of advantages in keeping this closely aligned. I believe that the representation feature on ITEM_STRUCTURE used to be called items!

Any comments, Sam

Thomas Beale wrote:

Mattias Forss wrote:

Mattias Forss wrote:

Hello,
I’m trying to figure out which reference model Ocean’s achetype editor follows. I have an example regarding the data type Quantity, see below. There seems to be great differences depending on what reference model the archetypes follow.

I pretty sure that the reference model is the same in all cases. There is only one definition of DV_QUANTITY in the openEHR reference model, and as far as I know, only one assumed in archetypes.

Thank you for your answer Thomas,

I bet the reference model is the same, but do the Ocean archetype editor fully conform to the reference model? Take a look at the ITEM_TREE class definition for example. You will see that the correct attribute for the physical representation of the tree will be either “representation” for version 0.9 of the specifications or “root” for version 0.95+ of the specifications. However, the Ocean archetype editor does not use neither of these attributes, instead it uses “items” but maybe this is correct if the editor conforms to an earlier version of the specifications than 0.9. Anyone who knows about this?

Hm, good point. I will bring that up with the Archetype Editor team…

However, it may look different. There are two ways of representing constraints on Quantity in an archetype. One is to use the ‘standard’ method of creating C_COMPLEX_OBJECTs which mimic the sructure of the QUANTITY class; the other is to use an instance of C_QUANTITY, which is a custom replacement type which provides a better model of the possible constraint on QUANTITY (while still assuming the same underlying definition of QUANTITY).

This is interesting, but I’m getting slightly confused about the naming here. Could you explain more and tell me the difference between QUANTITY, C_QUANTITY and C_DV_QUANTITY. It is probably a lot easier to grasp for someone like you.

Actually, we habitually don’t put the DV_ in data types in the archetypes. But the intention is that they are the openEHR data types. We originally used the DV_ in the data types to a) make it clear they were data types, and b) to avoid name clashes with other built-in classes like Boolean or State or whatever. In hindsight, it might have bene better not to have done this, but it doesn’t matter really. In the archetypes however, some people object if they see DV_ because they know it means openEHR, whereas if they don’t see it, they feel comfortable - even if the implied model is exactly the same!

We are working on getting people to understand that the model on which clinical archetypes are based - if they are to be sharable - must itself be seen as a standardised ontology. Thus the function of the openEHR RM is as a “base domain ontology” for clinical computing, a suitable basis for archetypes. The fact people are able to build so many successful archetypes shows that the underlying model is relatively good for this purpose.

So in the future, it may be that a subset of openEHR will be standardised for this purpose: a domain base ontology for EHR and other clinical computing purposes. In such an ontology, there would be no DV_. Such is the politics and psychology of international standardisation.

C_QUANTITY on the other hand is a class whose instances are constraints on a QUANTITY (DV_QUANTITY).

I believe the C_QUANTITY corresponds to the CQuantity (inherits from CDomainType) class in the java reference kernel, and the parser gives me this object if the archetype looks like Q1. Nevertheless, I’m starting to think that this isn’t right and that the parser instead should give me the CQuantity object if the archetype looks like Q2. What do you think? By the way, should there exist a class called Quantity in the java kernel or maybe it is sufficient with the CComplexObject (that mimics the structure of the QUANTITY class)?

well, I don’t know how Acode have built the parser, but I agree with what you say above. In the Eiffel reference ADL parser, Q1 would generate a C_COMPLEX_OBJECT and Q2 would generate a C_QUANTITY.

the property attribute is defined only in the type C_QUANTITY. It provides a convenient way to capture the constraint that you want only length or pressure, without saying which unit. If only the property is set in the C_QUANTITY in the archetype, then when the kernel checks to see if an instance of DV_QUANTITY conforms to the C_QUANTITY in the archetype, it is up to the C_QUANTITY to carry out this check in sensible way, i.e. by determining what property the actual units measure.

I’m not getting this… as an example, do you mean that a C_QUANTITY with its property set to “length” is supposed to check if “meters” or “inches” in the DV_QUANTITY conforms to this C_QUANTITY? How is it supposed to do that, it seems to me that the C_QUANTITY then must know what allowable units there can be for the length property. Where are those units supposed to be stored if only the property is set in the C_QUANTITY?

the C_QUANTITY needs access to shared units tables. I don’t know what the Acode code does here, but we have this implemented in the .Net version; the underlying tables can be made available if you want them (in fact, they are probably in the knowledge_tools_dotnet repository somewher,e but I don’t know where off-hand; let me know if you need that).

By the way, shouldn’t the property attribute represent a CODED_TEXT object that can be linked to a local or external terminology?

this is true; we watered it down to make people in CEN and HL7 happy, but I no longer believe such compromises are sensible. We will probably change this to a CODED_TEXT.

Ok, I suppose you’re referring to the Ocean archetype editor now?

Iin the AOM as well.

  • thomas

If you have any questions about using this list,
please send a message to d.lloyd@openehr.org

  • If you have any questions about using this list, please send a message to d.lloyd@openehr.org

Sam Heard wrote:

Mattias and Tom

First point Tom has covered - we use the archetype model constraint classes. These can be made TOTALLY openEHR if required, but I think we will do better from an acceptance point of view to go with more generic type names (ie without the DV_). This could be changed in future if people preferred.

The issue about using items as the attribute of ITEM_STRUCTURE (an abstract class) is interesting and one that had not reared its head for those at Ocean working on this. The fact is that we are using the path statements as the glue between the classes in the model. This is how you need them to be when you are applying them - but it is not strictly the reference model classes. This allows a generic statement about constraints on an abstract structure such as ITEM_STRUCTURE as we only need to address items (rather than root, item, items etc).

The path statements generated from this approach apply in the design environment and in the run time data collection environment - there are a lot of advantages in keeping this closely aligned. I believe that the representation feature on ITEM_STRUCTURE used to be called items!

It probably did. But we should stick to the reference model - it should now be "root" for ITEM_TREE. In the near future, this kind of alignment & checking will be done with a software module that reads a schema expression of the openEHR RM (or an internationally standardised version of the parts of the model from COMPOSITION down) and picks up errors in the archetypes.

- thomas

Hello everyone

With version 1.0 becoming a reality, we have been reviewing all the archetyped classes. It is clear that there has been some drift from the original class (e.g. HISTORY → EVENT_SERIES, TREE → ITEM_TREE etc) and attribute names (items → root in ITEM_TREE) which have not all been taken up in the current archetypes.

In the archetype editor, I have worked to keep the tool compatible with former representations, writing new names and attributes as they have been agreed and fixed in the model. Further, the path statements e.g. /at0000/data[at0001]/…etc are crucial to implementation and need to be fixed. Changing these means that all software working with archetypes needs to be updated - and there is a bit about these days.

I have reviewed the model (OBSERVATION and EVENT_SERIES in particular) and found the following changes:

The first issue is that an EVENT_SERIES (was HISTORY) has events - this attribute is called ‘items’ in 1.0 rather than ‘events’ as it is in the archetype editor. An EVENT’s data is called ‘item’ in release 1.0, rather than ‘data’ as it is in the Ocean archetypes. I have changed the editor to read either but to write only the 1.0 names, which should not cause anyone problems with the editor, but may with other software. Any software using paths needs to be upgraded if you use the 0.99.4 editor code which is the current version source undergoing testing on the openEHR website.

The different ITEM_STRUCTURES have a different attribute for the contents - ITEM_SINGLE has ‘item’, ITEM_LIST has ‘items’ - these are as in the archetype. ITEM_TREE has root - I have suggested that this be renamed to items - and have a one to * relationship with ITEMs. Tom is reviewing this. The documentation here does give ‘items’ as the path attribute, so this would be consistent.

I will talk more about ITEM_TABLE later.

The net result of these changes to the Editor is that it is backwardly compatible (ADL 1.2) and now almost totally in tune with release 1.0.

Cheers, Sam

Thomas Beale wrote:

Sam Heard wrote:

Mattias and Tom

First point Tom has covered - we use the archetype model constraint classes. These can be made TOTALLY openEHR if required, but I think we will do better from an acceptance point of view to go with more generic type names (ie without the DV_). This could be changed in future if people preferred.

The issue about using items as the attribute of ITEM_STRUCTURE (an abstract class) is interesting and one that had not reared its head for those at Ocean working on this. The fact is that we are using the path statements as the glue between the classes in the model. This is how you need them to be when you are applying them - but it is not strictly the reference model classes. This allows a generic statement about constraints on an abstract structure such as ITEM_STRUCTURE as we only need to address items (rather than root, item, items etc).

The path statements generated from this approach apply in the design environment and in the run time data collection environment - there are a lot of advantages in keeping this closely aligned. I believe that the representation feature on ITEM_STRUCTURE used to be called items!

It probably did. But we should stick to the reference model - it should now be “root” for ITEM_TREE. In the near future, this kind of alignment & checking will be done with a software module that reads a schema expression of the openEHR RM (or an internationally standardised version of the parts of the model from COMPOSITION down) and picks up errors in the archetypes.

  • thomas

If you have any questions about using this list,
please send a message to d.lloyd@openehr.org

  • If you have any questions about using this list, please send a message to d.lloyd@openehr.org