Document queries for token annotation display mode

[jacobwegner]

Taking a first pass...

This URL links to a preview instance of Explore Homer ATLAS:

https://tinyurl.com/sv-token-align-demo1

Query:

query TextParts($urn: String!, $alignmentSlug: ID) {
  textAlignmentChunks(reference: $urn, alignment_Slug: $alignmentSlug) {
    edges {
      node {
        id
        relations {
          edges {
            node {
              id
              tokens {
                edges {
                  node {
                    id
                    veRef
                    wordValue
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Variables:

{
  "urn":"urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1-1.10",
  "alignmentSlug": "iliad-word-alignment"
}

This will return data similar to:

{
  "data": {
    "textAlignmentChunks": {
      "edges": [
        {
          "node": {
            "id": "VGV4dEFsaWdubWVudENodW5rTm9kZToxNTEyMg==",
            "relations": {
              "edges": [
                {
                  "node": {
                    "id": "VGV4dEFsaWdubWVudENodW5rUmVsYXRpb25Ob2RlOjE1MTIy",
                    "tokens": {
                      "edges": [
                        {
                          "node": {
                            "id": "VG9rZW5Ob2RlOjE=",
                            "veRef": "1.1.t1",
                            "wordValue": "μῆνιν"
                          }
                        }
                      ]
                    }
                  }
                },
                {
                  "node": {
                    "id": "VGV4dEFsaWdubWVudENodW5rUmVsYXRpb25Ob2RlOjE1MTIz",
                    "tokens": {
                      "edges": [
                        {
                          "node": {
                            "id": "VG9rZW5Ob2RlOjM0NzUxMg==",
                            "veRef": "1.1.t1",
                            "wordValue": "The"
                          }
                        },
                        {
                          "node": {
                            "id": "VG9rZW5Ob2RlOjM0NzUxMw==",
                            "veRef": "1.1.t2",
                            "wordValue": "wrath"
                          }
                        },
                        {
                          "node": {
                            "id": "VG9rZW5Ob2RlOjM0NzUyMA==",
                            "veRef": "1.1.t9",
                            "wordValue": "that"
                          }
                        },
                        {
                          "node": {
                            "id": "VG9rZW5Ob2RlOjM0NzUyMg==",
                            "veRef": "1.1.t11",
                            "wordValue": "wrath"
                          }
                        }
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

The data model for token annotations is as follows:

• The TextAlignmentNode is used to track that a curator has aligned texts across one or more texts/versions.

sample: "Iliad Word Level Alignment, grc-2 + eng-3 by jtauber"

• TextAlignmentChunkNode is used to model each "chunk" of the alignment. It maps 1:1 to to the AlignmentRecord generated by Ducat.

sample: "Textual Alignment created with the Ducat tool on: Mon Apr 27 2020 18:40:10 GMT+0800 (AWST).#jtauber"

• TextAlignmentChunkRelation maps one or more tokens in a particular chunk. It maps loosely to the CITE relations (urn:cite2:cite:verbs.v1:aligns).

_sample_relationa: "urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1@ἄειδε[1]" _sample_relationb: "urn:cts:greekLit:tlg0012.tlg001.perseus-eng3:1.1@sing[1]"

To summarize the data returned by the GraphQL query in plain English:

• Retrieve the alignment chunks contained within the Iliad word level alignment for the given reference.

• For each chunk, retrieve the relations (greek / english)

• For each relation, retrieve the tokens

[jacobwegner]

For the initial version, I think we can hardcode $alignmentSlug.

There will be some additional work to do (captured in ) to update other alignments (like the sentence alignment).

Below is a query demonstrating how we would populate the list of available alignments for a given passage:

https://tinyurl.com/sv-token-align-demo1-alignment

Query:

query Alignments($urn: String!) {
  textAlignments(reference: $urn) {
    edges {
      node {
        id
        name
        slug
      }
    }
  }
}

Variables:

{
  "urn":"urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1-1.10"
}

Returns:

{
  "data": {
    "textAlignments": {
      "edges": [
        {
          "node": {
            "id": "VGV4dEFsaWdubWVudE5vZGU6MQ==",
            "name": "Iliad Sentence Alignment",
            "slug": "iliad-sentence-alignment"
          }
        },
        {
          "node": {
            "id": "VGV4dEFsaWdubWVudE5vZGU6Mw==",
            "name": "Iliad Word Alignment",
            "slug": "iliad-word-alignment"
          }
        }
      ]
    }
  }
}

[jacobwegner]

@paltman here are the passage queries we can use until we have a "smarter" endpoint

Greek

{
  passageTextParts(reference: "urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1-1.10") {
    edges {
      node {
        ref
        tokens {
          edges {
            node {
              id
              veRef
              wordValue
            }
          }
        }
      }
    }
  }
}

English:

{
  passageTextParts(reference: "urn:cts:greekLit:tlg0012.tlg001.perseus-eng3:1.1") {
    edges {
      node {
        ref
        tokens {
          edges {
            node {
              id
              veRef
              wordValue
            }
          }
        }
      }
    }
  }
}

[jacobwegner]

@paltman as a starting point for the resolver information, what do you think about the following?

We add metadata.passageReferences which is a list of URNs (same order as the relations nodes):

If there are no alignment chunks for the given passage, we return an empty list:

The developer would then be responsible for crafting two additional queries for the text parts (e.g.):

{
  leftPassage: passageTextParts(reference: "urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1-1.10") {
    edges {
      node {
        ref
        tokens {
          edges {
            node {
              id
              wordValue
            }
          }
        }
      }
    }
  }
  rightPassage: passageTextParts(reference: "urn:cts:greekLit:tlg0012.tlg001.perseus-eng3:1.1") {
    edges {
      node {
        ref
        tokens {
          edges {
            node {
              id
              wordValue
            }
          }
        }
      }
    }
  }
}

Eventually we could make that part of textAlignmentChunks as something like textAlignmentChunks.passages, but at that point, it might be easier to do some token-level annotation.

[jacobwegner]

@paltman here is the latest query with metadata.passageReferences:

Query

query TextParts($urn: String!, $alignmentSlug: ID) {
  textAlignmentChunks(reference: $urn, alignment_Slug: $alignmentSlug) {
    metadata {
      passageReferences
    }
    edges {
      node {
        id
        relations {
          edges {
            node {
              id
              tokens {
                edges {
                  node {
                    id
                    veRef
                    wordValue
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

variables

{
  "urn":"urn:cts:greekLit:tlg0012.tlg001.perseus-grc2:1.1-1.10",
  "alignmentSlug": "iliad-word-alignment"
}