Using libschwa-java without annotations

[reckart]

I looked into interfacing libschwa-java with UIMA based only on the UIMA type-system information, bypassing the JCas classes (and consequently the libschwa-java Java annotations).

I would like to create a DocSchema manually and fill it with information obtained from a UIMA type system. But this appears not to be possible because the necessary methods are missing or are private. The only way to create a DocSchema is by using the create() method which takes an annotated Java class.

Maybe I am missing something? Do you have an example somewhere of using libschwa-java without the annotations by manually constructing a schema?

[timdawborn]

Hey Richard,

Creating docrep annotation types on the fly not being backed by a corresponding Java class is not something we've wanted to do before now. The Python docrep API has a way to do it but it achieves this by creating classes at runtime (being a dynamic language). Can you point me to either the UIMA documentation or the appropriate class(es) to do with how you use the UIMA type system bypassing the JCas classes? I'll see if there's an easy mapping between how it's implemented there and how it could be implemented here. I suspect there will be.

[reckart]

There are two UIMA classes the may contain type system information:

• TypeSystemDescription - basically a in-memory representation of the type system description XML files
• TypeSystem - the actual type system being used in a CAS created from a TypeSystemDescription

It is reasonably easy to convert one representation into the other, e.g.

• CasCreationUtils.createCas(typeSystemDescription, null, null).getTypeSystem() -> TypeSystem
• TypeSystemUtil.typeSystem2TypeSystemDescription(aJCas.getTypeSystem()) -> TypeSystemDescription

The TypeSystem may have the more convenient API though for the present purpose.

[reckart]

Btw. what leaves me wondering most is how to convert nicely between the byte-offsets used in docrep and the character-offsets used in UIMA - but I assume you have some straight solution for that? ;)

[timdawborn]

Thanks for the UIMA links. I'll have a think about it over the next couple of days and get back to you.

As for the character offsets issue, maybe you can answer the question I've not had satisfactorily answered by other UIMA users :) How do you use character offsets when the source document isn't plain text? E.g. a MS Word document or something.

Obviously we won't be able to convert cleanly from character offsets to byte offsets if information is missing, such as the original encoding of the document. In cases like this, what I've done in the past is create a "fake" original document which is essentially the tokens space-concatenated together and create offsets over that.

[reckart]

When the source document is not plain text, we extract the plain text within a UIMA reader component at the beginning of the pipeline and store it in the CAS. The rest of the pipeline only sees the plain text then.
Mind that in some cases we do not even have a clearly defined "source document" for what we put inside a CAS. The source data may be spread over multiple original files and be aggregated into a single CAS by the reader. It may also be the case that we generate multiple CASes from a single source file, e.g. because it contains multiple documents.

Of course you might want to use UIMA in a forensic context where you are not actually analyzing text but rather raw data. In such a case, a use might simply abuse the "begin" and "end" fields of the UIMA Annotation type to store byte offsets, time offsets (for media) or whatever else. In such a case, the user would not be able to use the getCoveredText() method of Annotation. An alternative approach would be to define a custom type, e.g. ByteAnnotation inheriting from AnnotationBase which would re-define "begin" and "end" and possibly provide a method like getCoveredSlice() returning a byte[].

A practical example: During the OIAF4HLT workshop, it was mentioned that in the context of the EUMSSI the Annotation type's "begin" and "end" features were actually used to store milliseconds pointing into a video/audio stream.

[timdawborn]

Right. So the notation of "character offsets" isn't always actually character offsets. If that's the case, is there still a good reason (apart from the historical reason) to favour character offsets over byte offsets?

[jnothman]

I assume that this was one of the design objectives of the "SOFA" notion in UIMA: to represent one or more versions of the document in which the span abstraction (i.e. document as a linear space) is meaningful. IIRC, the SOFA tag has a text attribute for the case that spans can be understood literally as offsets into a string. I guess then the decision of character vs byte offsets is still equivocal.

[reckart]

If the a SOFA content is set using setDocumentText() then the expectation is that Annotation.begin/end are character offsets, because getCoveredText(begin, end) is implemented basically as getDocumentText().substring(begin, end).

If the SOFA content is set using setSofaDataArray() or setSofaDataURI(), then Annotation.getDocumentText() cannot be used.

[reckart]

So, the span-abstraction provided by the UIMA type Annotation is text-based and character-based by design (at least what Java calls a character).

People can ab-use this abstraction and avoid the use of certain methods that are text-based and character-based and use the information provided by the integer begin and end fields differently.

An IMHO cleaner approach would be to define alternative types in projects that need them that provide span abstractions over different spaces.

Within a single CAS you could then have multiple SOFAs, e.g. one for the raw byte data of a Word document and one for the extracted plain text data from the document. You could also define a type allowing you to link the annotations over the plain text and annotations over the raw data.

However, those UIMA users that I have had contact with so far are rarely interested in the raw original data and rather in the information content. Hence, using the standard Annotation type over text is typically fine. The analysis result is typically not overlaid on the original data anyway, but rather extracted, abstracted and stored differently, e.g. as facts in a database or simply aggregated over to create a statistical model of the data.

[jnothman]

Perhaps more to the point, when that mapping layer is useful, it can generally remain independent of annotation engines and need not be communicated with the document.

[reckart]

@timdawborn: I would consider favoring character offsets over byte offsets a matter of convenience and purpose:

For a binary format where you want to do fast seeks, the byte offsets make sense because you can quickly skip over large sections of UTF-8 encoded text (where a character may consist of multiple bytes).

For an application working on the actually encoded information, using character offsets is more convenient because you can use the standard String-manipulation methods and do not have to worry about the wire-encoding (e.g. ISO8859-1, UTF-8, UTF-16 BE/LE, ... etc.). It allows to do fast seeks in in-memory String representations.

A question may be whether the two purposes may be nicely separated, e.g. having byte-based offset pointers in the wire format that allow fast seeking while maintaining the annotation pointers into text data character based.

In any case, a reader component could transform the byte offsets into character offsets as it constructs the CAS text from the wire data and a consumer component could do it the other way around. It adds a little bit of extra complexity but it shouldn't be a real problem I suppose. I was just wondering if you had a smarter option, e.g. if I missed something and docrep actually offers some layer in which offsets are character-based instead of offset-based.

[timdawborn]

I think you've slightly misunderstood how docrep uses the byte slices, @reckart. A token class for example might look like this:

@dr.Ann
public class Token extends AbstractAnn {
  @dr.Field public ByteSlice span;
  @dr.Field public String raw;
}

When initially constructing the Token objects from the original document, we store the Unicode version of the string (raw) as an attribute of the annotation itself, as well as where it originally came from in the document (span). Remember that docrep does not store the original document, so any information you want to keep around as part of your annotations you need to explicitly extract.

For any on-document annotations we typically keep a ByteSlice of what this annotation object maps to on the original document so that if we ever wanted to reverse it back onto the original document, we are able to do so. E.g. doing some kind of visualisation.

A concrete example of byte slices and extracted text (if you have libschwa installed):

$ echo 'Hello, world!' | schwa-tokenizer --printer docrep | dr less | cat
0: {    # Document
  __meta__: {
  },
  tokens: { # Token (4)
    0x0: {
      span: [0x0, 0x5], # byte slice (0, 5)
      raw : "Hello",    # str (5B, 5 code point(s))
    },
    0x1: {
      span: [0x5, 0x6], # byte slice (5, 6)
      raw : ",",    # str (1B, 1 code point(s))
    },
    0x2: {
      span: [0x7, 0xc], # byte slice (7, 12)
      raw : "world",    # str (5B, 5 code point(s))
    },
    0x3: {
      span: [0xc, 0xd], # byte slice (12, 13)
      raw : "!",    # str (1B, 1 code point(s))
      norm: "!",    # str (1B, 1 code point(s))
    },
  },
  sentences: {  # Sentence (1)
    0x0: {
      span: [0x0, 0x4], # slice into tokens (0, 4)
    },
  },
  paragraphs: { # Paragraph (1)
    0x0: {
      span: [0x0, 0x1], # slice into sentences (0, 1)
    },
  },
},

[reckart]

@timdawborn Ok, I see. So I assume docrep is agnostic to the semantics of the span slice.

If I wanted to keep the document text inside the docrep, I could as well define my types as something like this, right?

@dr.Doc
public class Document extends AbstractDoc {
  @dr.Field public String text;
}

@dr.Ann
public class Token extends AbstractAnn {
  @dr.Field public Document doc;
  @dr.Field public Slice<Integer> span;

  public String getCoveredText() {
    return doc.text.substring(span.start, span.stop);
  }
}

[timdawborn]

You are correct that the spans do not hold any formal semantics. Annotation types do not have to have a span attribute. A concrete example: a number of the models in the OntoNotes 5 conversion do not contain a span attribute.

If your document was plain text, yes, that is one way you could do it.