Plaid UMR Guide

New UMR project on the Projects page makes a project with a text layer, a sentence layer, a word layer, and the four layers UMR annotation lives in. Documents come in through Import and export.

A project made in another Plaid app opens here once a maintainer has set it up for UMR: opening its documents sends a maintainer to the setup page, where Set up for UMR adds the UMR layers beside the existing ones. Nothing already in the project changes. Everyone else sees a notice asking for a maintainer.

A project with no text at all is set up in Plaid IGT or Plaid UD first.

Settings → General holds the project’s language as a BCP-47 tag (en, zh, arp). It selects the frame file the concept picker offers senses from (English, Chinese, Arabic and Portuguese are bundled). An exported gloss header carries the language of its own gloss line, not the project’s. The page names the file the saved language gets and how many rolesets are in it. A language with no bundled file is the ordinary case for a language being documented, and its rolesets come from the project’s vocabulary instead (see Vocabulary).

A vocabulary linked to the project in Plaid IGT is a lexicon here. A word that IGT has linked to an entry offers that entry’s headword as its concept, with the entry’s gloss beside it, and typing in the concept picker finds any entry by its form. An entry can also stand for a roleset, which is how a language with no bundled frame file gets one. Write it in Plaid IGT, in the entry editor: the UMR band takes the roleset the entry offers as its concept (lunch-01) and a description per argument (ARG0, the one eating), and the band appears once a UMR project is linked to that vocabulary. A name that is not an ARG, or that another row already has, is marked under its row there, and the entry cannot be saved until it is mended. The concept picker then offers the roleset in place of the headword, and the argument descriptions show beside the roles when you attach one.

A node whose concept was picked from an entry remembers the entry. When the entry’s roleset or headword is changed in Plaid IGT, the node gets a warning (s2v was picked from ver, now ver-02.), counted in its sentence’s header and listed on the Validation tab. Take entry value on the node’s menu, or e, takes the entry’s new concept for that node. Take entry value for all 5 nodes, or Shift+E, takes it for every node of the document picked from that entry, and the row names how many there are. A concept typed over, on the canvas or in Text mode, no longer follows its entry. A node forgets its entry when the entry is deleted from its vocabulary. Unlinking the vocabulary from the project does not count: link it again and the nodes still follow their entries.

Import and export takes .umr files (the UMR 2.0 release format, one file per document) by drop or picker, and Import reads them. Tab reaches the drop zone, and Enter or Space opens the file picker. Each file becomes a document named after the file, with its sentences, words, graphs, alignments, gloss lines and document-level annotation.

When the project already has a document of the file’s name whose words match the file’s, sentence by sentence, and which has no graph yet, the file’s graphs land on that document’s words instead. This is how a document glossed in Plaid IGT gets its UMR annotation from a file. A document of the file’s name that already has a graph, or a graph kept as text, refuses the file: "Okul" already has a graph. When that document’s words differ from the file’s, or it has none, the file becomes a new document of that name, and the report says why: Imported as a new document: …​. A file whose name two documents of the project already share is refused.

A Sentence: line is read as the sentence’s text. Onto a document from Plaid IGT, the document’s own text stays the sentence’s text.

The report lists each note under its file, with its sentence number. A note that recurs across sentences is one line with the count (5 sentences: No sentence id line. …​).

A sentence whose graph the parser cannot read is kept as text and written back unchanged on export, and the sentence’s header says so. Text opens on the kept text, to mend it and apply it. Once the sentence has a node, made there or on the canvas, the graph you see is the one exported and the kept text is not written. Mending such a graph in Text mode keeps the alignment the file gave each node. The document-level relations that name a node of such a sentence are kept with the sentence whose block wrote them and written back there on export, and the report counts them (Sentence 38: 3 document-level relations are held until sentence 37 is mended.). Mending the graph in Text mode makes them relations again, in the same change. A node named like a document-level block (s8s0) is imported with a note to rename it. Older files are read as they are: an obsolete gloss header is written back in its current form, and -1—​1 is read as unaligned.

A document’s Export tab shows it as .umr, to copy or download. Import and export exports every document of the project as a zip.

The file is written in the 2026 UMR file format: a sentence’s graph in PENMAN with children in the order they were made, an alignment line for every node (0-0 for an unaligned one), and the document-level block with the temporal, modal and coreference triples of that sentence. Each sentence starts with a bare # :: snt1 line. The sentence’s text is written on a Sentence: line after the gloss lines of the words and morphemes, only when it is not the words joined by spaces (Sentence: Ali, eve gitti. under Words: Ali eve gitti). A sentence whose text has more items than its words, such as punctuation standing apart (Tu viens ?) or a word holding a space, has no Sentence: line. The whole file is written in Unicode NFC. The export numbers the sentences 1, 2, 3 in order, except in a document imported from a file whose numbers start elsewhere. There each sentence keeps its file’s number, and a sentence added in Plaid IGT takes its position, or the next number past the highest when that one is taken. No number is written twice. A triple between nodes of two sentences is written in the block of the later one. A re-entrant node is written in full where it is first reached from the root and as a bare variable elsewhere. The file holds one graph a sentence, the root’s. A part of the sentence the root does not reach (a node made with no parent, or what a deleted edge cut off) is shown on the canvas and marked as an error, and the export leaves it out, with its alignment and its document-level relations. The Words line is split on spaces, so a word holding one (two words merged in IGT) is written with _ in its place. A document the file cannot hold, such as one with two nodes of a sentence under one variable, is not exported, and the page lists each problem.

A node shows its variable, its concept, and its attributes as a line of text (aspect performance · polarity -). A node anchored to words sits above them. The anchored words are underlined, and hovering or focusing a node lights them. A node with no anchor (person, name, a -91 roleset) is drawn hollow and sits above its parent. A node a service drafted has a dashed violet border, and one made by a member whose work the project reviews a dashed amber one. The mark goes when you edit the node, which records it as yours, or when you accept it. A relation’s label and a document-level tag carry the same dashed violet or amber border while the relation is unreviewed. The edge’s line does not change. Hovering a marked node or label shows where it came from (Machine-made, unverified), and an accepted one still says so (Machine-made, confirmed). To accept a node as it stands, choose Accept on its menu or press Ctrl+Enter (Cmd+Enter). That accepts the node and its relation to its parent. Accept graph beside a sentence accepts every node and relation of it. A sentence with anything a person made or accepted is kept whole when a draft overwrites. Discard graph beside it deletes the drafted nodes and relations of the sentence that nobody has accepted, after asking. It keeps what a person made, what a member whose work the project reviews made, and what was accepted, and a drafted node that one of those relations hangs from or points to. A drafted relation between two nodes that stay is deleted, unless it leads to a node a person made or corrected. That one stays, still drafted, and so does the node it hangs from. A relation another sentence has onto a deleted node is deleted too. The question says how many of those other sentences lose. History lists it as one change. The root’s concept is underlined.

Tree edges run down from a parent to its children, the relation floating above the child, straight down when the child is under its parent. Every edge carries a head at the end it points to, which is the only thing that says which way a re-entrant or a document-level relation runs. A node with a second way in (a re-entrancy) shows the second edge as a dashed curve, the only dashed line on the canvas, with its relation beside it where it covers no node and no other label. Between rows it leaves and arrives at the same side of the two nodes, and between two nodes of one row it dips under the row. The children of one parent that lie beyond its box share one line across the gap between rows, with a drop to each.

The words carry their number. Under them, the project’s gloss lines: the morphemes and their glosses grouped under the word they belong to, a part of speech per word, and a translation as a row. Each line is named to its left. A node aligns to whole words. A word’s morphemes are shown as plain text under it and stand for their word. A word nobody has segmented in Plaid IGT shows as itself on the Morphemes line, as IGT shows it, and its morpheme gloss is _. The lines of an imported file go under the words wherever the file lets that be told: a line with one item per word, a line whose hyphens and equals signs join its items into as many words as the sentence has (’a- ní- dz- oo- d- záa =go is one word), or a gloss line that pairs item for item with such a Morphemes line. Any other line, and a translation, runs as a row of its own. Which layers feed which lines is set in Settings → UMR settings (see Gloss lines).

The margin to the left of each graph pins the document graph’s constants: author, root, document-creation-time, and any other constant a triple of that sentence names. Only the ones the sentence uses are shown. The rest appear while a node is focused or while you are dragging, which is when you would aim at one. A document-level relation reads on each node it joins as a tag, in this sentence or another: modal relations in dark blue-grey, temporal ones in teal, coreference in brown. The tag reads the triple in its own order, with a dot where the node itself stands: (s3d :before s3b) is ● :before s3b on s3d and s3d :before ● on s3b. A temporal relation says how the second node stands to the first, its reference time, so here s3b is before s3d. The relations of one kind and one direction share a tag (● :overlap s1d s1m), each variable in it its own click. author :full-affirmative, which nearly every event carries, is grey, so that any other modality stands out. A node wears at most five tags and a tag names at most four other nodes. Past that a count (+22) takes their place, which lists them all when clicked. A click on a tag changes its relation. Focusing or hovering a node draws its own relations, each in its tag’s color: a line to the constant, a line to the other node, and for a node of another sentence a line across the sentences between, with the node at the far end outlined. Nothing is drawn for the others, so a long sentence stays readable.

Nodes in one coreference chain wear a numbered chip in the chain’s color. Clicking the chip goes to the next mention of the chain, in this sentence or another.

The official UMR checks run as you edit. A sentence’s header counts its errors and warnings, except unaligned words, which the Validation tab lists. Clicking the count lists them. A node a check names wears a dot and a ring in red for an error or magenta for a warning, with the message on hover. Besides the official checks, an edge whose two nodes are in different sentences is an error on the node it leaves, and the export leaves it out. The project’s Validation tab lists every problem in every document.

The text, the sentences and the words belong to the whole project, and someone can edit them in Plaid IGT or Plaid UD after the UMR annotation is made. Opening the document here puts right what such an edit left behind, in one entry in the history, named for what it did.

A node anchored to words follows its words. Letters typed at an anchored word’s edge or inside it, a space included, stay in the nodes anchored to it. A node anchored to no word belongs to the sentence it was made in and stands over the whole of it, so an edit anywhere in the text leaves it where it belongs. Two sentences joined into one bring their nodes together in it, where they are two graphs until the annotator joins them, which the sentence’s header counts and the Validation tab lists. A sentence split in Plaid IGT or UD deletes the edges that would join nodes of the two new sentences, in the same step. Opening a document as a maintainer deletes, once for the project, such edges an earlier split left behind. A sentence’s text deleted takes that sentence’s nodes with it, and its history keeps them.

A node whose words are deleted (deleting a word in Plaid IGT keeps its text) becomes a node anchored to no word, drawn hollow, and the history entry names it (1 node lost its word (s3y2)). Tokenizing the text again does not anchor it again. A sentence with no words at all (after Clear tokens in Plaid IGT) is left as it is until it is tokenized again, and its nodes keep their anchors. Its graph is still drawn, with every node unaligned, and can be edited as usual except for Change anchor, which needs a word.

When sentences are added or removed before a sentence, its variables take its new number and keep the rest of the name (s2v in what is now sentence 1 is s1v). Variables are not renumbered in a document whose first # :: snt number, as imported, is not 1, such as an excerpt that starts at snt5. Its variables stay as the file named them. A graph kept as text is mended under the names it has, even when sentences were added or removed before it since the import. The next time the document is opened, its variables take the sentence’s number.

When a sentence is typed in before an existing one in Plaid IGT, the existing sentence keeps its imported lines: its number, its gloss and metadata lines, and its document-level relations. The history entry of the next opening names the repair: moved the stored lines of 1 sentence to the sentence they describe.

An addition cut off partway (a closed tab, a lost connection) leaves nothing behind once the document is opened again. A node picked from a vocabulary entry that has since been deleted no longer names it. No repair is made while a service run or an approved assistant plan is writing to the document. It is made the next time the document is opened. A repair cut off partway is named Repair on open (interrupted) in the history, and the next opening finishes it. When someone saves while a repair is being made, it starts again by itself. If it fails again, or the server does not answer, a message asks you to reload the page.

Every one of the actions below can be reached without the keyboard.

A click on a node focuses it, and a double-click on one of its parts edits that part: the concept, the variable, or an attribute chip. A second single click only keeps the node focused. A document-level tag, the +N count, a relation’s label and the chain chip act on a single click. Click a relation’s label to change the relation, or drag it onto another node to move the subtree there.

Everything else is on the node’s own menu, which opens on a right-click anywhere on the node or with the ⋯ button at its top right, and from the keyboard with the Menu key or Shift+F10. The menu lists every action with the key that does the same thing, and greys out the ones that do not apply (a root has no relation to a parent). Add a child on the menu waits for the next click: the child’s word, an existing node to make the child, or empty space for a child with no word. Cancel in the sentence header leaves it.

A relation that takes a value does not take a node: :aspect and the other attributes with a set of values, :li, :list-item, :wiki, a name’s :op1, :op2 and so on, and :ARG2 of have-polarity-91. A new edge there, made, moved or relabeled, is refused with ':aspect' takes a value, not a node. So is a concept change that would put a node there, such as and with a node under :op1 changed to name. The assistant and Draft refuse it too. An edge an imported file brought there is kept, and the Validation tab lists it.

While u or Add a child waits for its click, the arrows still move and Escape leaves it. Other keys do nothing until it ends, except the digits, Backspace and Enter of u. The list of m and r closes on Escape, and ends the wait with it.

Enter commits what was typed. An option is taken instead only when the arrows moved to it, it was clicked, or its value is exactly what was typed. The option under the pointer is shaded lighter than the one the arrows moved to, and is not a choice. The list also shows options whose description holds the typed text, so an argument can be found by what it means, but Enter never takes one of those on its own: typing place gives :place, not the :ARG1 described as "place or thing escaped". In the relation pickers, the start of a relation is enough (ARG gives :ARG0, the colon optional). A concept is any word, so it is never finished for you: rat stays rat. Escape cancels.

Text in a sentence’s header shows the sentence’s graph as PENMAN in place of the canvas. Every node of the sentence is in the text: the root’s graph first, then each part the root does not reach as a graph of its own below it. The text is parsed as you type, and the first problem shows under it. Ctrl+Enter (Cmd+Enter) applies, as Apply does. Apply compares the text with the stored graph, node by variable and edge by relation and target, and writes the difference as one operation: a node that is new in the text is made unaligned (anchor it on the canvas afterwards), a node missing from the text is deleted with what only it reached, a changed root moves the root. An empty text deletes every node of the sentence. Apply writes the whole text at once: if it fails, nothing of it is applied. An apply too large to write in one step that fails partway says what was saved and what was not. The line under the text names every concept Apply changes, by variable (s9x changes from sleep-01 to cat, s9y from cat to sleep-01.). Nodes are matched by variable, so exchanging two variables exchanges their concepts, and each node keeps its words and document-level relations. Apply refuses what the canvas refuses: a new node’s variable that is malformed or used elsewhere in the document, a relation UMR does not have, a new edge that closes a cycle through anything but :quote, a new node under a relation that takes a value (s1a: ':li' takes a value, not a node.), and a value the official validator cannot read, with the reason. A value a node already has from an import is kept as it is. A variable typed over is read as a rename when one variable goes and one arrives and they are plainly the same node: the same concept, under the same parents by the same relations, or both the sentence’s root. The node keeps its anchor, its edges and its document-level relations, and the line under the text says which name changed. Anything less clear-cut, two variables typed over at once or a concept changed along with the name, is a node deleted and a node made, and the line names what Apply would delete that way. Cancel, or Text again, with unapplied changes asks first.

A document’s Compare tab scores its graphs against another document of the same text, two annotators' copies or a draft against its corrected version, with the AnCast metric (the comparison service, services/umr_ancast.py). Pick the other document and run Compare. The report is written on the document and the tab shows it: the document scores (sentence graphs, modal, temporal, coreference and the comprehensive score), and sentence by sentence both graphs side by side. The report names the person who ran the comparison. A group neither document annotates has no score and reads n/a. The sentence number and each marked variable open Annotate on that sentence or node. A sentence edited on either side since the comparison is marked Changed since this comparison. Run Compare again to rescore it.

AnCast pairs each node with a node of the other graph where it can. In the graphs, a node with no counterpart has a dashed blue outline, and a node paired with a node of another concept (leave-11 against leave-02, meal against lunch) a solid rose one. Under the graphs the pairs are listed, those of different concepts first with both concepts. A pair marked left over was made only because both nodes were left once the rest were paired, and says nothing about whether they are the same node.

A copy of a document for a second annotator is made on the document’s Details tab with Copy document, choosing Text only. The copy has the words and glosses and no UMR graphs, and History lists it as one entry. If the graphs cannot be taken off the copy, the copy is not made. Text and UMR graphs copies everything. Everyone in the project can open both copies.

The Assistant button in the header opens the same assistant in a panel beside whatever you are looking at. A handle on the right edge of the window, halfway down, opens it too. The panel stays where it is as you move around, and the page narrows to make room for it. It can be dragged wider or narrower and hidden again, and its width and whether it is open are remembered. A narrow window has no room for it, and neither the button, the handle nor the panel is offered there.

One conversation runs per project. The panel picks up the last one you had in the project you are in and keeps it as you move from document to document. A question asked on a document is about that document: name no document and that is the one it reads, though it can still look at the rest of the project when the question calls for it. Ask, beside Text and Comment on a sentence, puts that sentence into the question, and you can take it out again before sending.

Typing @ in the message box names something without leaving the message: the sentences of the document you have open (s3), and the documents of the project. Sentences are matched on what they say, so @ followed by a word finds the sentence that contains it. Arrow keys move through the list, Enter takes the one that is highlighted, and Escape closes the list and leaves what you typed.

A plan approved in the panel re-reads the document, so the canvas shows the result without losing your place.

The panel’s header shows how much of the model’s limit the last turn used, with the counts behind it on hover. A conversation fills up as it grows, because every turn sends the whole thread again. Past 85 percent the panel says so, and a new conversation starts with room again. Where the model’s limit is not known the count is shown without a percentage, unless the assistant was started with its limit stated.

The assistant is a service that your server’s operator runs and picks the model for (plaid-umr-agent, installed from a checkout of the source tree). When none is connected there is nothing to open, so the tab, the button, the handle and Ask are not shown. Conversations already saved are unaffected and open from their own links.