MetaphraseTM Editing API
v1a3

Summary

Metaphrase is a database of Concepts, each of which have a number of elements attached to them: a Concept ID, one or more Semantic Types, one or more Atoms, and any number of Definitions and Relationships. An update interface, then, needs to support the following actions:

Note about the old version: The notion of a [Concept] Candidate has been dropped. Responsibility for tracking unformalized problem list items has been moved to the problem list record system, and the database update model has been made much more flexible.

All edit transactions will be logged on the server.

Index

EV1 (add element)
EV1 takes a Concept ID and an element, and adds the element to the specified Concept. "OK" will be returned if successful, otherwise "?Invalid Concept ID" will be returned if the specified concept could not be found, otherwise "?Invalid Element" will be returned if the element was incorrectly specified. The element may be any of the following (the fields are "\t"-separated):
ATOM	<source>/<termgp>/<code>	<term>
STY	<TUI>
DEF	<definition>
<rel type>	<Concept ID>	<rel attribute>	<source>

EV2 (delete element)
EV2 is an "undo" for EV1; it takes the same arguments, and gives the same returns, with one exception--a call which would remove the only Atom of a concept, or the only Semantic Type of a "UMLS" or "reviewed" concept, will return "?Remove disallowed" and fail (you should use EV4 to delete concepts). When successful, the specified element is simply removed from the database.

EV3 (create Concept)
EV3 takes an Atom, and returns a new Concept ID if successful, or "?Invalid Concept", indicating that the Atom was invalid. The newly created Concept will have "unreviewed" status.

EV4 (delete Concept)
EV4 takes a Concept ID, and returnes "?Invalid Concept ID" if the identified concept is not found, otherwise the elements of the concept (necessarily including at least one Atom) are returned (in the same format as for V2) and the concept is deleted.

EV5 (next unreviewed Concept)
EV5 takes an optional filter, and returns the Concept ID (in the first line, with the form "CUI\t<Concept ID>\n") followed by a description (à la V2) of the next Concept in the review ring.

EV6 (set Concept status)
EV6 takes a Concept ID and a string status, either "reviewed" or "unreviewed". It returns "?Invalid Status" if the status is not either "reviewed" or "unreviewed", otherwise it returns "?Invalid Concept ID" if the identified concept could not be found, otherwise "?Noop" is returned if the identified concept already has the given status, otherwise "?Invalid Concept" is returned if the identified concept is a not a local concept. Otherwise:

  • If the status is "reviewed", "?No Semantic Type" is returned if the given Concept has no Semantic Types attached, otherwise the Concept is removed from the Concept ring, the status is updated to "reviewed", and "OK" is returned.

  • If the status is "unreviewed", it updates the status to "unreviewed" and puts it in the Concept ring, and "OK" is returned.

EV7 (load enhancements)
EV7 takes a stream of two types of "\n\n"-separated records: "CON\t<Concept ID>\t<status>\n" followed by "\n" separated Concept elements, and "SRC\t<source>\t<description>\n". E.g., the stream:

CON	C0020564	UMLS
ATOM	MAYOT/TE/795	Cardiomegaly

CON	C28100065	reviewed
STY	T080
ATOM	MAYOQ/PT/301	Strong family history
ATOM	MAYOQ/LV/301	Strong family history of
ATOM	MAYOQ/AB/301	Strong family Hx
RB	C0241889	isa	MAYO

SRC	MAYOQ	Mayo clinical qualifiers. Rochester (MN): Mayo Clinic; 1996,1997.

defines data for two concepts, the first a Metathesaurus concept, the second an externally created, reviewed concept, and a single source MAYOQ. In case of an error, none of the data will be loaded (the possible error messages will be enumerated later); if successful, "OK" will be returned.

EV8 (dump enhancements)
Not yet implemented.
EV8 takes a ["|"-separated] list of sources and returns the given sources, the concepts which contain elements from the given sources, and those concept elements, for loading by EV7. See EV7 for the output format.

EV9 (create Source)
EV9 creates a new source in the database. The text sent is exactly what will appear in V0 (after the "SRC\t" tag), see V0 for the format description. "?Invalid Source Definition" will be returned if there is a syntax error, otherwise "?Invalid SAB" will be returned if the SAB (source abbreviation) isn't 2-7 alphanumeric characters, otherwise "OK" will be returned and the source created.

EV10 (reserved for delete Source)
EV10 is reserved for Source deletion, to be specified later.

EV11 (list precedence)
EV11 takes no arguments, and returns lines of the form "<SAB>/<termgp>" in precedence order (highest precedence first). This precedence is used to determine the preferred atom for each synonym class and the preferred name for each concept.

EV12 (set precedence)
EV12 takes two arguments of the form "<SAB>/<termgp>", the first is a new source/termgroup to be inserted in the precedence list just before (ahead of) the second argument. "?Invalid source/termgroup" will be returned if there is a syntax error in the first argument, otherwise "?Invalid SAB" will be returned if the SAB (source abbreviation) isn't 2-7 alphanumeric characters, otherwise "?Invalid termgroup" will be returned if the termgroup isn't 2 alphanumeric characters, otherwise "?Source/termgroup not found" will be returned if the second argument was not found in the precedence list, otherwise "OK" will be returned, and the precedence list updated.

Note that it is not an error to specify a precedence before the corresponding source has been created (via EV7 or EV9), since the precedence must be defined for every source/termgroup which appears in an enhancements file before the enhancements can be loaded.

EV13 (create hierarchical element)
Not yet implemented.
EV13 takes a source and a hierarchical element (a [possibly null] code, name, hcode, and [possibly null] rela), and returns "?Invalid Element" if the element was not specified correctly, otherwise it returns "?Invalid parent" if the parent hcode (explicit in the hcode) could not be found [in the given source], otherwise it returns "?Hcode exists" if the given [new] hcode is found to already exist, otherwise the new element is created and added to the context of the parent [and siblings], the context of the new element is created, the corresponding PAR, CHD and SIB relationships are generated, and "OK" is returned.

EV14 (delete hierarchical element)
Not yet implemented.
EV14 takes a source and hcode, and returns "?Invalid hcode" if the identified hierarchical element is not found, otherwise it deletes the element from the appropriate contexts, deletes the given context, and deletes the corresponding PAR, CHD and SIB relationships. If the hierarchical element has children, then all of its descendants will also be deleted.

EV15 (update hierarchical element)
Not yet implemented.
EV15 takes a source and [existing] hcode, and a hierarchical element (a [possibly null] code, name, hcode, and [possibly null] rela), and returns "?Invalid Element" if the element was not specified correctly, otherwise it returns "?Invalid hcode" if the [existing] hcode could not be found [in the given source], otherwise it returns "?Invalid parent" if the [implict] new parent hcode could not be found, otherwise it returns "?Hcode exists" if the given [new] hcode is found to already exist, otherwise the name, hcode, rela, and code of the identified [existing] hierarchical element are updated to the given values, and "OK" is returned. This function is necessary to allow hierarchical elements to be edited after children have been added, without having to delete all the children and then recreate them. It can also be used to move an entire subtree (by specifying an hcode under a different parent), in which case the hcodes of all its descendants will also change.

EV16 (copy subtree)
Not yet implemented.
EV16 behaves the same as EV15, except that it copies the subtree insted of modifying it.

If you have questions please send them to Kevin Keck at LTI.