An Introduction to stoRy

Example: Initialize a Theme

The social phenomenon of dangers, be they real or imagined, spreading through a community as a result of rumors and fear is explored in numerous works of fiction, including several Twilight Zone episodes.

The LTO captures hysteria of this kind with the theme mass hysteria. To explore "mass hysteria" theme ("demo" version) initialize the Theme class object

theme <- Theme$new(theme_name = "mass hysteria")

The theme entry can be printed to console in two ways

# Print stylized text:
theme

# Print in plain text .th.txt file format:
theme$print(canonical = TRUE)

Story thematic annotations are stored as a tibble

theme$annotations()

See ?Theme for more on Theme class objects.

A Note on Finding Themes: LTO developmental themes are easily explored using the theme search box on the project website. Chances are that any theme found in the developmental version will also exist in the demo version. So searching for themes on the website offers a practical approach to finding interesting themes to initialize in an R session.

Pro Tip: Demo version themes are explorable in tibble format. For example, here is one way to search for "mass hysteria" directly in the demo themes:

# install.packages("dplyr")
suppressMessages(library(dplyr))
# install.packages("stringr")
library(stringr)
demo_themes_tbl <- clone_active_themes_tbl()
demo_themes_tbl %>% filter(str_detect(theme_name, "mass"))

Notice that all themes containing the substring "mass" are returned. The dplyr package is required to run the %>% mediated pipeline.

Example: Initialize a Story

Thematically annotated stories are initialized by story ID. For example, run

story <- Story$new(story_id = "tz1959e1x22")

to initialize a Story class object representing the "mass hysteria" featuring classic Twilight Zone (1959) television series episode The Monsters Are Due on Maple Street.

Story thematic annotations along with episode identifying metadata can be printed to console

# In stylized text format:
story

# In plain text .st.txt file format:
story$print(canonical = TRUE)

A tibble of thematic annotations is obtained by running

themes <- story$themes()
themes

See ?Theme for more on Theme class objects.

A Note on Finding Story IDs: The project website story search box offers a quick-and-dirty way of locating LTO developmental version story IDs of interest. Since story IDs are stable, developmental version The Twilight Zone story IDs can be expected to agree with their demo data counterparts.

Pro Tip: A demo data story ID is directly obtained from an episode title as follows:

title <- "The Monsters Are Due on Maple Street"
demo_stories_tbl <- clone_active_stories_tbl()
story_id <- demo_stories_tbl %>% filter(title == !!title) %>% pull(story_id)
story_id

The dplyr package is again required to run the %>% mediated pipeline.

Example: Initialize a Collection

Each story belongs to at least one collection (i.e. a set of related stories). The Monsters Are Due on Maple Street, for instance, belongs to the two collections

story$collections()

To initialize a Collection class object for The Twilight Zone (1959) television series, of which The Monsters Are Due on Maple Street is an episode, run:

collection <- Collection$new(collection_id = "Collection: tvseries: The Twilight Zone (1959)")

Collection info is printed to console in the same way as with themes and stories

# Print stylized text:
collection

# Print in plain text .st.txt file format:
collection$print(canonical = TRUE)

A Note on Finding Collection IDs: As with stories, LTO developmental version collections can be explored from the project website story search box. Developmental and demo version collection IDs should generally match up. This is in particular the case with Twilight Zone collection IDs.

Pro Tip: Demo version collections can be directly explored in the usual way

demo_collections_tbl <- clone_active_collections_tbl()
demo_collections_tbl

Example: Find the Topmost Featured Themes in a Collection

To view the top 10 most featured themes in the The Twilight Zone (1959) series run:

collection <- Collection$new(collection_id = "Collection: tvseries: The Twilight Zone (1959)")
result_tbl <- get_featured_themes(collection)
result_tbl

To view the top 10 most featured themes in the demo data as a whole run

result_tbl <- get_featured_themes()
result_tbl

Example: Find the Topmost Enriched Themes in a Collection

To view the top 10 most enriched, or over-represented themes in The Twilight Zone (1959) series with all The Twilight Zone stories as background run

test_collection <- Collection$new(collection_id = "Collection: tvseries: The Twilight Zone (1959)")
result_tbl <- get_enriched_themes(test_collection)
result_tbl

To run the same analysis not counting minor level themes run

result_tbl <- get_enriched_themes(test_collection, weights = list(choice = 1, major = 1, minor = 0))
result_tbl

The theory and methods implemented in the get_enriched_themes function are described in (Onsjö and Sheridan 2020).

Example: Find Similar Stories to a Story of Interest

To view the top 10 most thematically similar Twilight Zone franchise stories to The Monsters Are Due on Maple Street run

query_story <- Story$new(story_id = "tz1959e1x22")
result_tbl <- get_similar_stories(query_story)
result_tbl

The theory and methods implemented in the get_similar_stories function are described in (Sheridan et al. 2019).

Example : Find Clusters of Similar Stories

Cluster The Twilight Zone franchise stories according to thematic similarity by running

set.seed(123)
result_tbl <- get_story_clusters()
result_tbl

The command set.seed(123) is run here for the purpose of reproducibility.

Explore a cluster of stories related to traveling back in time

cluster_id <- 3
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Explore a cluster of stories related to mass panics

cluster_id <- 5
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Explore a cluster of stories related to executions

cluster_id <- 7
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Explore a cluster of stories related to space aliens

cluster_id <- 10
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Explore a cluster of stories related to old people wanting to be young

cluster_id <- 11
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Explore a cluster of stories related to wish making

cluster_id <- 13
pull(result_tbl, stories)[[cluster_id]]
pull(result_tbl, themes)[[cluster_id]]

Example: Download and Configure the Latest LTO Version

To download and cache the latest versioned LTO release run

configure_lto(version = "latest")

This can take awhile.

Load the newly configured LTO version as the active version in the R session:

set_lto(version = "latest")

To double check that it has been loaded successfully run

which_lto()

Now that the latest LTO version is loaded into the R session, its stories and themes can be analyzed in the same way as with the "demo" LTO version data as shown above.