Act.text and code.originalText

Text is being put into both originalText and act.text and we need guidelines. Last week's Vocab call (16-May-07) discussed this, resulting from the MnM/Vocab thread "question about Act.code.originalText vs Act.text" and InM/Vocab thread "Meaning of CD.displayName".

Here are some use cases and candidate representations, to prime the discussion.

Text Use Cases

In summary the use cases are:

- Sometimes there is a code

- Sometimes there is text that is orthogonal to that code

- Sometimes a short code is entered into UI that results in a code being found and selected.

- Sometimes a code is derived from narrative text entered, and you want to record that text (or fragment of it) specifically to show the code decision process.

- Sometimes a code would be displayed one way to an expert user (eg CXR for "Chest X-Ray"), but this would need spelling out in full to a less specialist user.

Fuller use cases are below, some more realistic than others (comments on how common they are are welcome).

Note that when the suggested representation is "Act.text" this actually refers to act.text of another act, which is necessary due to the way act.text operates. See supplemental text for details.

Uncoded text use case

1 - Document centric system, supports narrative text only, in form of paragraphs, documents. Little structure, only authors of documents, and time of authoring

Suggested text representation: Act.text

2 - Text statement centric system, supports dated, attributed, possibly categorised and/or cross linked, units of text but no codes.

Suggested text representation: Act.text

3 - Code plus text based system, supports coded entries, and uncoded "text" entries. Entry in question has no code, no attempt is made to code it.

Suggested text representation: Act.text

-- variation: A coded system allows text only entries but has a rule that all entries must be coded. So behind the scenes a dummy code is added such as "text comment". This dummy code may be stripped when a message is sent based on it, and replaced with some other semantic marker.

Suggested text representation: Act.text

4 - System supports coded entries that can also have text associated. However the text is orthogonal to the code. Eg code says penicillin, text says "told patient come back in a week if not better".

Suggested text representation: Act.text

This sounds like supplemental text to me, and should be expressed in a different act. If the code for this act is "penicillin" then act.text should at least include "penecillin". If there is the need for attributes for suplimental text rather than using act relationships -- then that should be done -- lets not overload the definition of act.text just as it seems to have been settled by MnM. Charliemccay 04:29, 30 May 2007 (CDT)

Agreed. By "act.text" I actually did mean "act.text as supplemental text" (comment added at the top now to explain). Act.text of the act itself cannot work for any of these use cases, due to the nature of act.text. It's a great improvement that this nature is now clear, even though it doesn't elegantly match all use cases. Riksmithies 13:15, 30 May 2007 (BST)

Code from text use cases

5 - Coded system, user enters (or clicks/selects) PV as abbreviation for full code 1234="Penicillin". The full string "Penicillin" is not shown to the user. 1234="Penicillin" is entered into notes. System doesn’t record the fact that PV was entered, since this is a user interface issue.

Suggested text representation: Act.code=1234, act.code.displayName="Penicillin" (mandatory), act.code.originalText="[nothing]"

Comment: it would be an unusual system to not offer the full text of "Penicillin" back to the user for confirmation.

6 - Coded system, user enters (or clicks/selects) PV as abbreviation for full code 1234="Penicillin". The full string "Penicillin" is not shown to the user. 1234="Penicillin" is entered into notes. System DOES record the fact that PV was entered.

Suggested text representation: Act.code=1234, act.code.displayName="Penicillin" (mandatory), act.code.originalText="PV"

7 - Coded system, user enters (or clicks/selects) PV as abbreviation for full code 1234="Penicillin". The string "Penicillin" IS shown to the user in response to their "short code"/"query string". User selects "Penicillin" perhaps by clicking or hitting return. System doesn’t record the fact that PV was entered, since this is a user interface issue (user could have entered PenV, peni, penic etc, or just used the mouse, or even voice commands).

Suggested text representation: Act.code=1234, act.code.displayName="Penicillin" (mandatory), act.code.originalText="[nothing]"

8 - Coded system, user enters an encounter record and adds text "diabetic review" and clicks the "reason" check box next to it to indicate reason for encounter being "diabetic review". Actual encounter gets coded with "seen in surgery" or similar code, orthogonal to the reason.

Suggested text representation: Act.code=4567, act.code.displayName="Seen in Surgery" (mandatory), RSON act relationship to another act with has act.text="diabetic review".

Alternative not recommended is: Act.code=4567, act.code.displayName="Seen in Surgery" (mandatory), act.reasonCode.code="[nothing]", act.reasonCode.originalText="diabetic review"

9 - Coded system, user enters (looks up via some shortcut) a code of "diabetic review", then adds supporting short or lengthy text "had chat with patient discussed diet and..."

Suggested text representation: Act.code=5678, act.code.displayName="Diabetic Review" (mandatory), COMP act relationship to another act with has act.text="had chat with patient discussed diet and...".

Alternative not recommended is: Act.code=5678, act.code.displayName="Diabetic Review" (mandatory), act.code.originalText="had chat with patient discussed diet and..."

After the fact coding

10 - User dictates or hand writes text "had chat with patient reviewed diabetes control and...". Later a medical secretary codes this into a system, adding a code of "Diabetic Review", based on their understanding of the text. The full text is not entered, and remains in paper/tape form only.

Suggested text representation: Act.code=5678, act.code.displayName="Diabetic Review" (mandatory), act.code.originalText="had chat with patient reviewed diabetes control and...."

Comment: The system may not natively support "original text for a code", so if the text was entered at all it would likely be in a general clinical comment field. How would the user then indicate that this text was used for the code selection?

11 - Coded system, user enters into the system an uncoded comment "had chat with patient reviewed diabetes control and....". Later, a medical secretary reviews this and adds a code for "diabetic review" to the same entry/record.

Suggested text representation: Act.code=5678, act.code.displayName="Diabetic Review" (mandatory), act.code.originalText="reviewed diabetes control" (to indicate which words were considered), plus COMP act relationship to another act which has act.text="had chat with patient reviewed diabetes control and....".

Possible other representation is to put all the text into original text and none into component/act.text, or to put all into both.

A third possible representation (only available if the system is constructed to store edits to existing records as separate actions) is to have the main user's text in act.text, with a component act relationship to a secondary act (different author and author time) that has the coded version, Act.code=5678, act.displayName="Diabetic Review" (mandatory), act.code.originalText="reviewed diabetes control"

Discussion

Note that none of the above use the construct act.code.code="[nothing]", act.code.originalText="the text". This is therefore deprecated in the view proposed above. If there is no code involved (perhaps not even an attempt to find a code), there seems no rationale for using code.originalText, other than the fact that this is sometimes convenient in the RIM. The answer to "what if there is no code" is therefore "yes, there really is no code at all, only text, which goes in act.text".

Sometimes code.originalText is employed because the text is used to somehow generate the code. But sometimes it seems to be used because you have text, but a datatype that only accepts a code. This appears to be a separate use case.

There are RIM attributes that carry a particular semantic meaning eg reasonCode. To give a textual reason to an encounter, say, you could use act.reasonCode.originalText, and have no value in act.reasonCode.code. This seems to be text masquerading as a code, and if act.reasonCode allowed an ST or ED datatype it would be better to put text in with no reference to codes at all.

agree that act.reasonCode[code="nothing"].originalText is semantically equivalent to allowing act.reasonCode to be of type CD or ST -- I do not beleive that the clarity of introducing such a union type justifies the price of disruption that this would cause if implemented as a feature wherever CD could be used (since it is rare that at the global standards level we know that a suitable codesystem will always be available). Charliemccay 05:20, 30 May 2007 (CDT)

(Incidentally, reasonCode is not in the Clinical Statement pattern, since that tries to have a single way to achieve each representation (RSON act relationship in this case), even though it often standardises on the more verbose, more flexible version.)

Act.code.originalText can work as a way to put uncoded text into an act, and it is less verbose that using act.text, with less baggage around renderings and being affected by other attributes (see Act.text and Supplemental_text. This seems to be another kludge however, a workaround for there not being a RIM attribute called something like act.supportingText (with act.text really being act.representation).

when you are using text questions of rendering are not avoidable baggage, but central to the definition. If you send act.supportingText the receiver still needs to know whether this should be rendered before or after the rest of the act semantics, or more likely on one or other side of the code phrase. The advantage of using act.code.orginalText is that the scope of this attribute wrt the other attributes of Act is already (well?) defined. Act.text is also well defined now -- it is the complete representation of the act. I would support a proposal for act.prependedText and act.appendedText, but not for act.supportingText (unless that was defined to be rendered after the code, and so effectivly act.appendedText. Charliemccay 05:20, 30 May 2007 (CDT)

My point here is that act.text does have an awkward nature. It is basically for a full act rendering, end of story. However people also want to use it as "supplemental" text, and it can be, at a push, by putting it in its own attached act that has no other attributes. The rendering of that text-only act is therefore the same as the text (as soon as you add attributes it breaks).

But this really seems like two use cases, act.rendering (formerly act.text) and act.supportingText (formerly act.text on the end of an act relationship).

The existing rule about rendering would still apply, the rendering includes everthing else, supportingText and all, so there is no before and after to worry about.

There is still the question of how to render when there is no act.text/act.rendering sent, but we already have this problem (eg do I render date then code then author, or author then code then date). Riksmithies 13:35, 30 May 2007 (BST)

The use of a pre-/post-coordinated term in a code doesn't appear to make any difference to the scenarios above. "Code" can be taken to be a "code group" in any form with or without qualifiers.

Displaying the results

There are several phases of operation to consider:

- original data entry

- possible secondary coding stage

- re-display in original system (not a messaging issue, but possibly illuminating)

- re-display in another system once messaged

In all the cases above, what would want to be shown to a user as part of a summary patient record?

A rule of thumb (only applicable if the suggested guidance was as proposed above - Rik) could be :

- Always show act.text - this is always a full rendering so nothing else is needed.

- Otherwise show act.code.displayName, since this is what was "meant" (according to suggested representations above)

- Never display act.code.code (or other attributes not mentioned like codeSystem)

- Show act.code.originalText only if there is no act.code.code (but this construct may be deprecated)

- Never display act.code.originalText otherwise, since this is just audit data, either long text from which a code was condensed (can go in act.text of child act), or short text that may mean little to another user (eg CXR).

In Talk:Definition of act.text#GP2GP implementation guidence for the clinical statement (observation) it is specified that act.text should be displayed, OR a display may be built up from the coded components of the Act and specific component relationships. This is the level of explicit definition that is needed -- and a conformant application may display the information is a different way, but then it is the receivers responsibility to ensure that this will not cause confusion -- so for example the reasonCode may be omitted, or rendered using a locally understood color code, if and only if those responsible for the receiving application are confident that in context this is acceptable. The sender can expect that the meaning of the attributes sent will be made available to the receiver (human or otherwise). Charliemccay 05:20, 30 May 2007 (CDT) - Agree Riksmithies 13:35, 30 May 2007 (BST)

Also in the GP2GP guidelines we said that for human readers the orgininalText is what SHOULD be shown (if present) for coded attributes, since this is what the original human expressed and so is closest to what they wanted to say. If effective communication is the objective then showing the originalText is best, if human validation of the coded information is what is wanted, then the displayText is appropriate. I think that in most cases we should be allowing humans to see the originalText in picklists and "single line" views of the act -- and both oringinalText and displayText when the act has been selected within the UI and is the focus of attention and there is more screen/paper real-estate available. Establishing such rendering guidelines will I think help to clarify the exact meaning and use of the attributes, and make our interoperablility specifications much more useful (ie rendering rules are not baggage, but a pillar of the definition of the attributes).Charliemccay 05:20, 30 May 2007 (CDT)

Agree with the sentiment here but think that the current lack of guidance (in general, not in GP2GP of course) means you can't be sure what's in originalText and what may be duplicated or extra in displayText, supplementalText etc. What is in originalText may not be all that the human expressed, or even a decent summary. For instance in the "alternative not recommended" bit of use case 9, where they meant the Diabetic review bit also. If we can decide how to cover all the representations going into the message what to display should follow, but we can't make rules on this until then. Agree that rendering isn't baggage, but act.text does still have baggage since it is trying to do too much, rendering and more. Riksmithies 13:59, 30 May 2007 (BST)

When there is text that could have been coded in some (hypothetical) coding scheme, but is expressed as text, then it seems reasonable to put this in act.code.originalText – I think the value of having act.code as an attribute with well defined scope should not be lost just because a coding scheme does not directly support the scope – this is the charm of saying that act.code.originalText is the primary content of act.code. I think that the price of sometimes having an act.code.originalText without an act.code.code is a price worth paying. The domain of concepts that act.code should carry can then be defined independently of whether these concepts are expressed in code or text or both. Much as for CDA, the originalText must be taken as definitive and the code as an approximation to it. Thus act.code is a misnomer and it should be called act.meaning (but I am *NOT* proposing such a name change).

The question as to when an act should be broken out into components (eg Diabetic review as a parent act, with components for what happened during the review) then becomes a question as to whether it is useful to be able to treat these as separate statements in user interfaces (rendering again) or decision support (less significant if just dealing with text). Charliemccay 08:19, 30 May 2007 (CDT)

Further suggestion -- the problem here is that oringinalText and displayText both are defined in terms of what the sender has experienced, not what it is anticipated that the reciever needs or will do with what they receive -- and yet the latter is what is critical to successful ineroperability -- so maybe there is a need for a new attribute act.code.rendering which should be populated if the default behaviour (of rendering the originalText, or if that is not present the displayText) would be unhelpful (so the default becomes render CD.rendering, or if that is not present CD.originalText, or if that is not present CD.displayText)Charliemccay 08:19, 30 May 2007 (CDT)