--- title: "Getting Started with sumer" output: rmarkdown::html_vignette: toc: true toc_depth: 3 vignette: > %\VignetteIndexEntry{Getting Started with sumer} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", dev = "ragg_png" ) ``` ## 1. Introduction The `sumer` package provides tools for translating and analyzing Sumerian cuneiform texts. It converts between different text representations, offers dictionary lookup, and includes an interactive translation tool. Modern scholars typically work with Sumerian texts in **transliterated** form -- a phonetic rendering in Latin characters. For example, the Sumerian word for king is transliterated as `lugal`. However, translation does not depend on pronunciation. The meaning of a sign depends on the sign itself, not on how it is read aloud. Even when there is reason to believe that words with similar pronunciations have similar meanings, dictionaries can be based solely on the cuneiform characters. The same cuneiform sign can have several different readings (transliterations), but it always has exactly one sign name and one cuneiform character. ```{r} library(sumer) ``` ## 2. Representations of Cuneiform Signs Each cuneiform sign has three representations: | Representation | Example | Description | |-------------------|---------------------|----------------------------------------------------| | Transliteration | `lugal` | Phonetic transcription in lowercase letters | | Sign name | `LUGAL` | Canonical name in uppercase letters | | Cuneiform | 𒈗 | Unicode character (U+12000 to U+12500) | The package works internally with cuneiform characters and sign names. Transliteration serves as a convenient input method. **Note on display:** Cuneiform characters require a font supporting the Unicode Cuneiform block (U+12000--U+12500). In RStudio, the AGG graphics backend should be enabled (Tools > Global Options > General > Graphics > Backend > AGG). ### 2.1 Retrieving sign information The function `info()` retrieves all available information about a sign or sign sequence: ```{r} info("lugal") ``` For compound expressions, all contained signs are analyzed: ```{r} info("d-en-lil2") ``` Each sign (d, en, lil2) is shown with its sign name (AN, EN, KID) and cuneiform character. The `alternatives` column lists all possible readings -- for instance, EN can also be read as `ru12` or `uru16`. ### 2.2 Conversion between representations Two functions convert entire texts: ```{r} # Transliteration -> Cuneiform as.cuneiform("lugal-e") as.cuneiform(c("d-en-lil2", "an-ki")) # Transliteration -> Sign names as.sign_name("lugal-e") as.sign_name(c("d-en-lil2", "an-ki")) ``` Within a word, hyphens (`-`) separate syllables; dots (`.`) separate sign names; spaces separate words. ## 3. Dictionary Lookup ### 3.1 Loading a dictionary The package includes a built-in dictionary: ```{r} dic <- read_dictionary() ``` The vignette "Translating Sumerian Texts" describes how you can create your own dictionary. ### 3.2 Forward lookup: Sumerian -> English ```{r} look_up("lugal", dic) ``` The output shows the sign name, cuneiform character, translations with frequency counts and grammatical types, and entries for individual signs and substrings. For compound expressions, all partial combinations are looked up as well: ```{r} look_up("d-suen", dic) ``` ### 3.3 Reverse lookup: English -> Sumerian To find the Sumerian sign for an English term, use `lang = "en"`: ```{r} look_up("Agga", dic, "en") ``` The reverse lookup searches all translations and displays matching entries with their sign names and cuneiform characters. ## 4. The Type System Each dictionary entry has a **grammatical type** in addition to its translation. These types describe the function of a sign in a sentence. Since the same sign can serve different functions depending on context, it may have multiple entries with different types. ### 4.1 Basic types There are three basic types: | Type | Name | Description | Example | |---------|-------------|-------------------------------------------------|--------------------------| | **S** | Substantive | Noun phrases and substantives | "king", "Earth" | | **V** | Verb | Verbs and verbal expressions | "create", "go" | | **A** | Attribute | Modifying clauses | "who is strong" | You can see the different types of a sign with `look_up()`: ```{r} look_up("an", dic) ``` The sign AN appears both as a noun (S: "sky/heaven") and as an operator that transforms other expressions -- which brings us to the next topic. ### 4.2 Operators In addition to basic types, there are **operators**. An operator takes one or two expressions of a certain type as arguments and produces an expression of a (possibly different) type. The notation describes where the arguments stand and what type is produced: ```{r, echo = FALSE} op_df <- data.frame( Notation = c("Sx->V", "xS->S", "Sx->A", "Sx->S", "xV->V", "Vx->V", "SSx->V"), Alternative = c("S\u2612\u2192V", "\u2612S\u2192S", "S\u2612\u2192A", "S\u2612\u2192S", "\u2612V\u2192V", "V\u2612\u2192V", "SS\u2612\u2192V"), Meaning = c("Takes an S to the left, produces a V", "Takes an S to the right, produces an S", "Takes an S to the left, produces an A", "Takes an S to the left, produces an S", "Takes a V to the right, produces a V", "Takes a V to the left, produces a V", "Takes two S to the left, produces a V") ) knitr::kable(op_df, col.names = c("Notation", "Alternative notation", "Meaning")) ``` The `x` marks the position of the operator itself. In `Sx->V`, the argument S stands to the left of the operator; in `xS->S`, the argument stands to the right. Some operators with two arguments (like `SSx->V`) take both arguments from the same side. The symbols `x` and `->` have the alternative Unicode representations `☒` and `→` that may appear in dictionary entries and line files. In translations, the placeholder **S** (or **V**) stands for the argument. For example, an operator `xS->S` with the translation "community of S" means: take the noun to the right of this sign and insert it where the S placeholder stands. For operators with two arguments of the same type, the placeholders are numbered: `S1` and `S2`. Let us trace through a concrete example. Consider the expression `un-ma-gi` from "Enki and the World Order" (line 16), which consists of three signs: ```{r, echo = FALSE} ex_df <- data.frame( Syllable = c("un", "ma", "gi"), Sign = c("\U00012327", "\U00012220", "\U00012100"), Type = c("\u2612S\u2192S", "S", "S\u2612\u2192S"), Translation = c("community of S", "container", "the permanent S") ) knitr::kable(ex_df, col.names = c("Syllable", "Cuneiform Sign", "Type", "Translation")) ``` We build up the noun phrase step by step: 1. **𒈠** is a simple noun (S): "container". 2. **𒄀** is an operator `S☒→S` that takes the S to its left. It binds 𒈠 and replaces the placeholder: "the permanent **container**". The result is again an S. 3. **𒌧** is an operator `☒S→S` that takes the S to its right. It binds the result from step 2: "community of **the permanent container**". The result is again an S. Note that operators with arguments at the right-hand side bind stronger than operators with arguments at the left-hand side. The final noun phrase is: "community of the permanent container" (type S). In this context, "community" refers to the people and "permanent container" refers to the land of Sumer. The expression `un-ma-gi` thus means "the people of Sumer". In the dictionary, such context-dependent meanings are recorded using the notation **"literal meaning {specific meaning}"**. The dictionary entry for this expression would be: "community of the permanent container {people of Sumer}". The literal meaning documents the compositional structure, while the specific meaning in curly braces gives a contextual interpretation. ### 4.3 Verb types A simple verb (type **V**) stands on its own -- for example, "to be used as a resource". It combines directly with a subject noun phrase (S + V -> SEN) to form a sentence. Many Sumerian verbs, however, take a noun phrase as their object. The type **Vt** describes such a **transitive verb**: it takes an S as its object and produces a complex intransitive verb (V). The translation contains an S placeholder for the object, for example "to equip S". The resulting V must then be combined with a subject (S) to form a complete sentence (SEN). `Vt` is a generalization of `Sx->V` that also works correctly when the verb has prefixes or suffixes. In Sumerian, verbs are often preceded by **verb prefixes** -- signs that modify the verb's meaning (expressing modality, aspect, or other nuances). A verb prefix has the type `☒V→V`: it takes a verb to its right and produces a modified verb. Since each prefix produces a V, multiple prefixes can chain together. They bind from right to left, wrapping around the core verb like layers. Conversely, a **verb suffix** has the type `V☒→V` and binds from left to right. Prefixes and suffixes can co-occur. Consider the verb chain `gan-ig-la` from line 8 of "Enki and the World Order": ```{r, echo = FALSE} vt_df <- data.frame( Syllable = c("gan", "ig", "la"), Sign = c("\U000120f6", "\U00012145", "\U000121b7"), Type = c("\u2612V\u2192V", "\u2612V\u2192V", "Vt"), Translation = c("may V", "V with the task of establishing sustenance of human existence", "to equip S") ) knitr::kable(vt_df, col.names = c("Syllable", "Cuneiform Sign", "Type", "Translation")) ``` The verb builds up from the core outward: ``` 𒃶 𒅅 𒆷 ☒V→V ☒V→V Vt "may V" "V with the task ..." "to equip S" └────────────────────────────┘ 𒅅(𒆷) = "equip S with the task ..." └──────────────────────┘ 𒃶(𒅅(𒆷)) = "may equip S with the task ..." ``` 𒆷 (`Vt`: "to equip S") is the core verb. 𒅅 (`☒V→V`) wraps it with additional meaning. 𒃶 (`☒V→V`) adds modality. The final composed verb is: "may equip S with the task of establishing sustenance of human existence" (`Vt`). This complex verb still has its S placeholder -- it will be filled when the verb meets its object during sentence composition. ### 4.4 Composition rules When two expressions stand side by side and neither is an operator, they are combined by **composition rules**: | Left | Right | Result | Translation pattern | |------|-------|--------|----------------------------------------------| | S | S | S | "X of/with Y" | | S | A | S | "X Y" (juxtaposition) | | S | V | SEN | "X Y" (subject + verb, "to" stripped) | | SEN | SEN | SEN | "X. Y" (sentences joined with period) | The type **SEN** stands for a complete sentence. It arises when a noun phrase (S) meets a verb (V). For example, if "separated groups" (S) is followed by "to be created" (V), the composition strips the "to" and produces the sentence "Separated groups be created." (SEN). This raw composition must then be finished by hand -- in this case, adjusting the verb form to produce "Separated groups are created." These rules, together with the operator types from the previous sections, are sufficient to translate entire Sumerian sentences from their individual parts. Since in Old Sumerian texts, signs decode phrases rather than syllables, this implies that the Old Sumerian language is actually not a natural language. It is a formal language that can be pronounced in any natural language that is sufficiently complex. ## 5. Text Analysis ### 5.1 N-gram analysis A good first step when working with a new text is to search for frequently recurring sign combinations (n-grams). Such patterns are valuable clues: if a certain sequence of cuneiform signs appears repeatedly, it is likely a fixed term, a compound word, or an idiomatic expression. The package includes the example text "Enki and the World Order": ```{r} path <- system.file("extdata", "project", "enki_and_the_world_order.txt", package = "sumer") text <- readLines(path, encoding = "UTF-8") ``` The function `ngram_frequencies()` finds recurring combinations: ```{r} freq <- ngram_frequencies(text, min_freq = c(6, 4, 2)) head(freq, 10) ``` The `min_freq` parameter controls the minimum frequency for different n-gram lengths. The default value `c(6, 4, 2)` means: single signs must occur at least 6 times, pairs at least 4 times, and all longer combinations at least 2 times. The analysis works from the longest combinations down to the shortest. When a long combination is identified as frequent, duplicated occurrences are masked so that shorter sub-combinations are not falsely counted as frequent just because they are part of the longer combination. With `mark_ngrams()`, the identified patterns are marked in the text with curly braces: ```{r} text_marked <- mark_ngrams(text, freq) cat(text_marked[1:5], sep = "\n") ``` You can also search for a specific pattern in the annotated text: ```{r} term <- "IGI.DIB.TU" pattern <- mark_ngrams(term, freq) pattern result <- text_marked[grepl(pattern, text_marked, fixed = TRUE)] cat(result, sep = "\n") ``` ### 5.2 Grammar probabilities To understand the structure of a sentence, it is helpful to know which grammatical role each individual sign is likely to play. The function `sign_grammar()` looks up each sign of a string in the dictionary and counts how often it occurs with each grammatical type (see Section 4): ```{r} sg <- sign_grammar("a-ma-ru ba-ur3 ra ta", dic) ``` The raw frequencies can be refined into posterior probabilities with a Bayesian model. `grammar_probs()` combines the dictionary counts with a prior distribution -- computed internally with `prior_probs()`, or supplied through the `prior` argument: ```{r} gp <- grammar_probs(sg, dic) ``` For signs with many dictionary entries, the observed frequencies dominate; for rare signs, the result falls back to the prior distribution. The position of a sign in the sequence is currently not taken into account for calculating probabilities. The function `plot_sign_grammar()` presents the results as a stacked bar chart: ```{r, fig.width = 7, fig.height = 4} plot_sign_grammar(gp, sign_names = TRUE) ``` Each bar represents a sign position in the sentence. The colours are grouped by the result of the type: green for a plain noun (`S`) and orange for the adjectival operator `Sx->S`; grey for whole sentences (`SEN`) and the other noun-deriving operators; blue shades for attributes (`A`) and attribute-producing operators; and red shades for verbs (`V`) and verb operators. A tall bar in a particular colour indicates that the sign likely has that grammatical function. The chart can also be saved to a file: ```{r, eval = FALSE} plot_sign_grammar(gp, output_file = "grammar.png") ``` ### 5.3 Grammatical structure of a cuneiform text Once you have assigned grammatical types to each sign, the function `grammatical_structure()` shows how the parts are grouped according to the operator binding and composition rules. The output uses typed brackets to indicate the role of each group: `()` for substantives (S), `<>` for verbs (V), `[]` for attributes (A), and `{}` for sentences (SEN). Consider the expression `mec3-ki-aj2-ga-ce-er ce du`: ```{r} x <- "mec3-ki-aj2-ga-ce-er-ce-du" x <- paste0(info(x)$reading, collapse = "-") x expr <- split_sumerian(x)$signs type <- c("S", "S", "Sx->A", "xS->A", "S", "Sx->S", "S", "Sx->V") grammatical_structure(x, type, expr) ``` The following figure shows the same result with colour coding: ```{r, echo = FALSE, out.width = "100%"} img_path <- system.file("extdata", "grammatical_structure.png", package = "sumer") if (file.exists(img_path)) knitr::include_graphics(img_path) ``` The figure shows that the sentence has the typical structure of an Old Sumerian sentence with the subject (mec3) at its beginning, followed by some specifications of the subject (here in square brackets), followed by the object (ce), and the verb (du) that absorbs the object. This example demonstrates that many Sumerian proper names are self-explanatory. The term "mec3-ki-aj2-ga-ce-er" stands for the proper name "Meskiagasher", but can also be read as a noun phrase. This visualization makes the grammatical structure explicit and can help verify that the type assignments produce a sensible grouping. ## 6. Equivalence Classes The grammatical types of Section 4 describe how one specific dictionary reading behaves. But a sign is often securely attested in only one or two readings, and a single reading does not reveal the sign's full grammatical potential. The **equivalence classes** address this. They summarize grammatical meanings that are permitted if at least one of the meanings is attested in the dictionary, so that knowing a sign's class makes the full range of admissible readings available even from sparse evidence. However, not all meanings are equally likely. Writers were often accustomed to favoring certain meanings. For example, an expression formed from a transitive verb can serve either as a verb or as a relative clause, and the expression itself does not tell which -- that depends on whether it stands at the end or in the middle of a sentence. Likewise, a noun `S` can be pressed into service as a verb "to be `S`". Such alternations cannot be read off a single dictionary entry; the equivalence class captures them. > **Scope.** The equivalence-class system was developed on the basis of several Sumerian mythological texts. It is at present unclear to which other texts -- of different genre, period, or region -- it carries over. The classes should therefore be understood as a working tool calibrated on that corpus, not as an established grammatical standard. A class name `nXm` encodes the number of arguments to the left (`n`) and to the right (`m`) of the sign, with the result type `X` (`S` for a noun, `A` for an attribute) of the canonical representative. Three further classes stand outside this scheme: the verb operators `VP` (verb prefix) and `VS` (verb suffix), the whole-sentence class `SEN`, and the catch-all class `R` for everything else. The function `classify()` assigns each dictionary reading to one of these classes according to the following criteria: ```{r, echo = FALSE} cls_df <- data.frame( Name = c("0S0", "", "", "", "", "", "0S1", "1S0", "0S2", "1S1", "2S0", "0A0", "", "", "0A1", "", "1A0", "", "", "0A2", "1A1", "2A0", "", "VP", "VS", "SEN", "R"), Type = c("S", "", "", "", "", "", "☒S→S", "S☒→S", "☒SS→S", "S☒S→S", "SS☒→S", "A", "", "", "☒S→A", "", "S☒→A", "", "", "☒SS→A", "S☒S→A", "SS☒→A", "", "☒V→V", "V☒→V", "SEN", ""), Criteria = c( "type S", "☒S→S ending in \"of S\"/\"for S\"", "V of the form \"to be [noun]\"", "☒S→V of the form \"to be [noun] of S\"", "A of the form \"who is [noun]\"", "S☒→S of the form \"who is [noun]\"", "☒S→S not ending in \"of S\"/\"for S\"", "S☒→S, not in 0S0, head-changing (changes the head noun)", "☒SS→S", "S☒S→S not beginning with \"S1\"", "SS☒→S not beginning with \"S1\"", "type A, not in 0S0", "type V, not in 0S0", "S☒→S, not in 0S0, used adjectivally (head unchanged)", "☒S→A (introduced relative clause)", "S☒S→S beginning with \"S1\"", "S☒→A (relative clause)", "S☒→V or Vt (transitive verb)", "SS☒→S beginning with \"S1\"", "☒SS→A (introduced complex relative clause)", "S☒S→A (for completeness only)", "SS☒→A (complex relative clause)", "SS☒→V (complex transitive verb)", "☒V→V (verb prefix)", "V☒→V (verb suffix, for completeness only)", "a whole-sentence reading (lexicalised compound)", "everything else (not matched above)"), Example = c( "king", "king of S", "to be king", "to be king of S", "who is king", "S, who is king", "great one who creates S", "city of S", "life-fire that binds S1 to S2", "one who is defended from S1 by S2", "binding S1 to S2", "who is good", "to be good", "good S", "who relies on S", "S1 who relies on S2", "that is defined by S", "to be defined by S", "S1 that is defined by S2", "who binds S1 and S2 together", "", "that equips S1 with S2", "", "to not V", "", "The king is a catalyst for change", "Which SEN?"), check.names = FALSE, stringsAsFactors = FALSE ) # Render as HTML and give the Type column a little more width via an explicit colgroup tbl <- as.character(knitr::kable(cls_df, format = "html")) colg <- paste0("