# An Introduction to stoRy

#### Paul Sheridan

#### Oshan Modi

#### Mikael Onsjö

#### April 09, 2023

## Background

The Theme Ontology Project is an open access, community-based fiction studies undertaking to * define common literary themes (or “themes” for short), * classify defined themes into a hierarchically structured controlled-vocabulary, and * annotate works of fiction with the themes within a collaborative framework. The LTO refers to the hierarchically structured collection of literary themes (Sheridan, Onsjö, and Hastings 2019). The current developmental version of the LTO contains over 3,000 carefully defined themes. To date over 3,000 stories (e.g., films, novels, TV series episodes, video game plots, etc.) have been annotated with LTO themes. All data is hosted on the Theme Ontology GitHub repository theming. It can be explored on the Theme Ontology website. The `stoRy` package is used to perform various statistical analyses on the data. These tells us interesting things about the kind of stories we humans invent.

## Installation

The package is hosted on CRAN and can be installed by running the command

    library(stoRy)

The developmental version is hosted on GitHub and can be installed using the devtools package:

    # install.packages("devtools")
    # devtools::install_github("theme-ontology/stoRy")

Once installed, the package can be loaded by running the standard library command

    library(stoRy)

## Accessing Documentation

Each function in the package is documented. The command

    help(package = "stoRy")

gives a cursory overview of the package and a complete list of package functions.

Help with using functions is obtained in the usual R manner. For instance, the documentation for the `get_similar_stories` function can be accessed with the command

    ?get_similar_stories

The command

    citation("stoRy")
    #>
    #> To cite the 'stoRy' package in publications use:
    #>
    #>   Paul Sheridan, Oshan Modi, Mikael Onsjö (2023). stoRy: Download,
    #>   Explore, and Analyze Literary Theme Ontology Data. R package version
    #>   0.2.1.
    #>
    #> A BibTeX entry for LaTeX users is
    #>
    #>   @Manual{,
    #>     title = {{stoRy}: Download, Explore, and Analyze Literary Theme Ontology Data},
    #>     author = {Paul Sheridan and Oshan Modi and Mikael Onsjö},
    #>     year = {2023},
    #>     note = {R package version 0.2.1},
    #>   }

prints to console everything needed to cite the package in a publication.

## Quick Start: The Twilight Zone Franchise Demo Data

This section is a good starting point for first time users. Included in the package is a toy dataset, extracted from the latest LTO version, comprising some 2,872 LTO themes and 335 thematically annotated The Twilight Zone American media franchise stories (Wikipedia 2021).

The themes are hierarchically arranged into four domains descended from an abstract root theme:

    literary thematic entity
    ├── the human condition
    ├── society
    ├── the pursuit of knowledge
    └── speculative fiction theme

Contained in the demo data are the following Twilight Zone thematically annotated stories:

- 156 The Twilight Zone (1959) television series episodes

- 3 Twilight Zone: The Movie (1983) film sub-stories

- 110 The Twilight Zone (1985) television series episodes

- 3 Twilight Zone: Rod Serling’s Lost Classics (1994) film sub-stories

- 43 The Twilight Zone (2002) television series episodes

- 20 The Twilight Zone (2019) television series episodes

Users may avail themselves of the demo data to experiment with package functions without having to download any official LTO version data to their local machine.

To begin check that the `demo` LTO version is active

    which_lto()
    #> [1] "demo"

Should it be that another LTO version is actively loaded, switch to the `demo` version

    set_lto(version = "demo")
    #> LTO "demo" is already the active version

Print LTO `demo` version summary information to console

    print_lto()
    #> Version: "demo"
    #> Timestamp: NA
    #> Git Commit ID: NA
    #> Encoding: UTF-8
    #> Theme Count: 2891
    #> Story Count: 335
    #> Collection Count: 6

A detailed description of the demo data included in the package can be viewed by running the command

    ?`lto-demo`

Pro Tip: The demo data, and LTO version data more generally, is internally stored in such a way that prohibits users from modifying it. The following sequence of commands, however, clones the data:

    demo_metadata_tbl <- clone_active_metadata_tbl()
    demo_themes_tbl <- clone_active_themes_tbl()
    demo_stories_tbl <- clone_active_stories_tbl()
    demo_collections_tbl <- clone_active_collections_tbl()

See `?lto-demo` for more details on exploring the output tibble contents.

### 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
    #> # A theme featured in 3 LTO demo version stories
    #> Theme Name: mass hysteria
    #> Description: Allusions of a threat spread through a group causing panic, each
    #>   person's fear reinforcing that of the next and in a vicious circle.
    #> References:
    #>   https://en.wikipedia.org/wiki/Mass_hysteria
    #> Parents: humans in group
    #> Examples: The people of Maple Street gradually transform into an hysterical
    #>   mob when they thought an alien monster was masquerading amongst them
    #>   in "The Twilight Zone" (1959) story "The Monsters Are Due on Maple
    #>   Street" (tz1959e1x22).

    # Print in plain text .th.txt file format:
    theme$print(canonical = TRUE)
    #> # A theme featured in 3 LTO demo version stories
    #> mass hysteria
    #> =============
    #>
    #> :: Description
    #> Allusions of a threat spread through a group causing panic, each person's fear
    #> reinforcing that of the next and in a vicious circle.
    #>
    #> :: References
    #> https://en.wikipedia.org/wiki/Mass_hysteria
    #>
    #> :: Parents
    #> humans in group
    #>
    #> :: Examples
    #> The people of Maple Street gradually transform into an hysterical mob when
    #> they thought an alien monster was masquerading amongst them in "The Twilight
    #> Zone" (1959) story "The Monsters Are Due on Maple Street" (tz1959e1x22).

Story thematic annotations are stored as a tibble

    theme$annotations()
    #> # A tibble: 3 × 5
    #>   story_id    date       capacity level  motivation
    #>   <chr>       <chr>      <chr>    <chr>  <chr>
    #> 1 tz1959e1x22 1960-03-04 ""       choice The people of Maple Street gradually t…
    #> 2 tz1959e3x03 1961-09-29 ""       major  We saw the people in a suburban neighb…
    #> 3 tz2002e1x31 2003-02-19 ""       choice The people of Maple Street gradually t…

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"))
    #> # A tibble: 11 × 11
    #>    theme…¹ theme…² descr…³ notes    aliases  template parents  ancest…⁴ examples
    #>      <int> <chr>   <chr>   <list>   <list>   <list>   <list>   <list>   <list>
    #>  1     426 coping… A char… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  2    1454 mass c… We are… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  3    1455 mass h… Allusi… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  4    1456 mass i… For on… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  5    1457 mass m… The va… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  6    1458 mass m… The te… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  7    1459 mass m… The cr… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  8    1460 mass r… Radiat… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #>  9    1461 mass s… The qu… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #> 10    1971 sacrif… A char… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #> 11    2669 weapon… A weap… <tibble> <tibble> <tibble> <tibble> <tibble> <tibble>
    #> # … with 2 more variables: references <list>, source <chr>, and abbreviated
    #> #   variable names ¹​theme_index, ²​theme_name, ³​description, ⁴​ancestors

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
    #> # A story annotated with 12 LTO demo version themes
    #> Story ID: tz1959e1x22
    #> Title: The Monsters Are Due on Maple Street
    #> Date: 1960-03-04
    #> Collections:
    #>   Collection: tvseries: The Twilight Zone (1959)
    #>   Collection: The Twilight Zone Franchise
    #> Description: A power failure causes the residents of a suburban neighborhood
    #>   to suspect one another of being monsters from outer space planning an
    #>   invasion. Directed by: Ronald Winston. Story by: Rod Serling.
    #> Choice Themes:
    #>   mass hysteria: The people of Maple Street gradually transformed into an
    #>     hysterical mob when they thought an alien monster was masquerading amongst
    #>     them.
    #>   mistrust leading to group dysfunction: The Maple Street community descended
    #>     into violent anarchy when they thought an alien monster was masquerading
    #>     amongst them.
    #>   the instinct for violence: The end narration made it clear that this story
    #>     was a commentary on how we humans rapidly turn on each other in times of
    #>     trouble.
    #> Major Themes:
    #>   attack from outer space: Aliens came to conquer Earth by clandestinely
    #>     instigating us to attack each other.
    #>   alien living secretly among us: The Maple Street inhabitants quickly became
    #>     convinced that one family or another must be aliens masquerading as
    #>     people.
    #>   fear of the unknown: Catastrophe ensued on Maple Street because people
    #>     feared that which they could not explain and turned on each other for
    #>     scapegoats.
    #>   neighbor and neighbor: The story follows a group of neighbors who must make
    #>     sense of a mysterious power outage.
    #>   the stupidity of crowds: The Maple Street residents gradually transformed
    #>     into an hysterical mob when they thought an alien monster was masquerading
    #>     amongst them.
    #> Minor Themes:
    #>   coping with insomnia: Les explained that he stargzed in early mornings
    #>     because he'd suffered from insomnia.
    #>   amateur radio: Steve was incriminated by the ham radio set he had been ill-
    #>     advisedly playing with in his basement.
    #>   extraterrestrial being: Two aliens came to Earth to insight a riot on Maple
    #>     Street.
    #>   flying saucer: The aliens departed Earth in a standard issue 1950s style
    #>     flying saucer.

    # In plain text .st.txt file format:
    story$print(canonical = TRUE)
    #> # A story annotated with 12 LTO demo version themes
    #> tz1959e1x22
    #> ===========
    #>
    #> :: Title
    #> The Monsters Are Due on Maple Street
    #>
    #> :: Date
    #> 1960-03-04
    #>
    #> :: Collections
    #> Collection: tvseries: The Twilight Zone (1959)
    #> Collection: The Twilight Zone Franchise
    #>
    #> :: Description
    #> A power failure causes the residents of a suburban neighborhood to suspect one
    #> another of being monsters from outer space planning an invasion. Directed by:
    #> Ronald Winston. Story by: Rod Serling.
    #>
    #> :: Choice Themes
    #> mass hysteria [The people of Maple Street gradually transformed into an hysterical mob when they thought an alien monster was masquerading amongst them.]
    #> mistrust leading to group dysfunction [The Maple Street community descended into violent anarchy when they thought an alien monster was masquerading amongst them.]
    #> the instinct for violence [The end narration made it clear that this story was a commentary on how we humans rapidly turn on each other in times of trouble.]
    #>
    #> :: Major Themes
    #> attack from outer space [Aliens came to conquer Earth by clandestinely instigating us to attack each other.]
    #> alien living secretly among us [The Maple Street inhabitants quickly became convinced that one family or another must be aliens masquerading as people.]
    #> fear of the unknown [Catastrophe ensued on Maple Street because people feared that which they could not explain and turned on each other for scapegoats.]
    #> neighbor and neighbor [The story follows a group of neighbors who must make sense of a mysterious power outage.]
    #> the stupidity of crowds [The Maple Street residents gradually transformed into an hysterical mob when they thought an alien monster was masquerading amongst them.]
    #>
    #> :: Minor Themes
    #> coping with insomnia [Les explained that he stargzed in early mornings because he'd suffered from insomnia.]
    #> amateur radio [Steve was incriminated by the ham radio set he had been ill-advisedly playing with in his basement.]
    #> extraterrestrial being [Two aliens came to Earth to insight a riot on Maple Street.]
    #> flying saucer [The aliens departed Earth in a standard issue 1950s style flying saucer.]

A tibble of thematic annotations is obtained by running

    themes <- story$themes()
    themes
    #> # A tibble: 12 × 4
    #>    theme_name                            capacity level  motivation
    #>    <chr>                                 <chr>    <chr>  <chr>
    #>  1 mass hysteria                         ""       choice The people of Maple St…
    #>  2 mistrust leading to group dysfunction ""       choice The Maple Street commu…
    #>  3 the instinct for violence             ""       choice The end narration made…
    #>  4 attack from outer space               ""       major  Aliens came to conquer…
    #>  5 alien living secretly among us        ""       major  The Maple Street inhab…
    #>  6 fear of the unknown                   ""       major  Catastrophe ensued on …
    #>  7 neighbor and neighbor                 ""       major  The story follows a gr…
    #>  8 the stupidity of crowds               ""       major  The Maple Street resid…
    #>  9 coping with insomnia                  ""       minor  Les explained that he …
    #> 10 amateur radio                         ""       minor  Steve was incriminated…
    #> 11 extraterrestrial being                ""       minor  Two aliens came to Ear…
    #> 12 flying saucer                         ""       minor  The aliens departed Ea…

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
    #> [1] "tz1959e1x22"

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()
    #> # A tibble: 2 × 1
    #>   collections
    #>   <chr>
    #> 1 Collection: tvseries: The Twilight Zone (1959)
    #> 2 Collection: The Twilight Zone Franchise

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
    #> # A collection consisting of 156 component stories
    #> Collection ID: Collection: tvseries: The Twilight Zone (1959)
    #> Title: The Twilight Zone
    #> Date: 1959-1964
    #> Description: The Twilight Zone is an American anthology television series
    #>   created and presented by Rod Serling, which ran for five seasons on CBS from
    #>   1959 to 1964. Each episode presents a stand-alone story in which characters
    #>   find themselves dealing with often disturbing or unusual events, an
    #>   experience described as entering "the Twilight Zone," often with a surprise
    #>   ending and a moral. Although predominantly science-fiction, the show's
    #>   paranormal and Kafkaesque events leaned the show towards fantasy and horror.
    #>   The phrase “twilight zone,” inspired by the series, is used to describe
    #>   surreal experiences.
    #> References:
    #>   https://en.wikipedia.org/wiki/The_Twilight_Zone_(1959_TV_series)
    #> Component Story IDs:
    #>   tz1959e1x01
    #>   tz1959e1x02
    #>   tz1959e1x03
    #>   tz1959e1x04
    #>   tz1959e1x05
    #>   tz1959e1x06
    #>   tz1959e1x07
    #>   tz1959e1x08
    #>   tz1959e1x09
    #>   tz1959e1x10
    #> # … with 146 more component stories

    # Print in plain text .st.txt file format:
    collection$print(canonical = TRUE)
    #> # A collection consisting of 156 component stories
    #> Collection: tvseries: The Twilight Zone (1959)
    #> ==============================================
    #>
    #> :: Title
    #> The Twilight Zone
    #>
    #> :: Date
    #> 1959-1964
    #>
    #> :: Collections
    #> Collection: tvseries: The Twilight Zone (1959)
    #>
    #> :: Description
    #> The Twilight Zone is an American anthology television series created and
    #> presented by Rod Serling, which ran for five seasons on CBS from 1959 to 1964.
    #> Each episode presents a stand-alone story in which characters find themselves
    #> dealing with often disturbing or unusual events, an experience described
    #> as entering "the Twilight Zone," often with a surprise ending and a moral.
    #> Although predominantly science-fiction, the show's paranormal and Kafkaesque
    #> events leaned the show towards fantasy and horror. The phrase “twilight zone,”
    #> inspired by the series, is used to describe surreal experiences.
    #>
    #> :: References
    #> https://en.wikipedia.org/wiki/The_Twilight_Zone_(1959_TV_series)
    #>
    #> :: Component Stories
    #> tz1959e1x01
    #> tz1959e1x02
    #> tz1959e1x03
    #> tz1959e1x04
    #> tz1959e1x05
    #> tz1959e1x06
    #> tz1959e1x07
    #> tz1959e1x08
    #> tz1959e1x09
    #> tz1959e1x10
    #> # … with 146 more component stories

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
    #> # A tibble: 6 × 9
    #>   collection_index colle…¹ title date  descr…² compon…³ refere…⁴ themes   source
    #>              <int> <chr>   <chr> <chr> <chr>   <list>   <list>   <list>   <chr>
    #> 1                1 Collec… The … 1959… "The T… <tibble> <tibble> <tibble> ./not…
    #> 2                2 Collec… The … 1985… "The T… <tibble> <tibble> <tibble> ./not…
    #> 3                3 Collec… The … 2002… "The T… <tibble> <tibble> <tibble> ./not…
    #> 4                4 Collec… The … 2019… "The T… <tibble> <tibble> <tibble> ./not…
    #> 5                5 Collec… The … 1983… "Stori… <tibble> <tibble> <tibble> ./not…
    #> 6                6 Collec… All … 1959… "All T… <tibble> <tibble> <tibble> <NA>
    #> # … with abbreviated variable names ¹​collection_id, ²​description,
    #> #   ³​component_story_ids, ⁴​references

### 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
    #> # A tibble: 10 × 6
    #>    theme_name                                        k k_bar     n n_bar      tp
    #>    <chr>                                         <int> <int> <int> <int>   <dbl>
    #>  1 husband and wife                                 52    85   156  3035 0.0280
    #>  2 ironic twist of fate                             32    60   156  3035 0.0198
    #>  3 what if I told the truth and nobody would be…    20    32   156  3035 0.0105
    #>  4 obsession                                        12    29   156  3035 0.00956
    #>  5 poetic justice                                   15    26   156  3035 0.00857
    #>  6 coping with aging                                10    23   156  3035 0.00758
    #>  7 loneliness                                       13    22   156  3035 0.00725
    #>  8 escape from reality                               9    21   156  3035 0.00692
    #>  9 extraterrestrial being                           12    21   156  3035 0.00692
    #> 10 father and daughter                              14    21   156  3035 0.00692

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

    result_tbl <- get_featured_themes()
    result_tbl
    #> # A tibble: 10 × 6
    #>    theme_name                                        k k_bar     n n_bar      tp
    #>    <chr>                                         <int> <int> <int> <int>   <dbl>
    #>  1 husband and wife                                109   178   335  6264 0.0284
    #>  2 ironic twist of fate                             48    88   335  6264 0.0140
    #>  3 mother and son                                   46    63   335  6264 0.0101
    #>  4 father and son                                   40    58   335  6264 0.00926
    #>  5 friendship                                       34    58   335  6264 0.00926
    #>  6 remorse                                          31    51   335  6264 0.00814
    #>  7 what if I told the truth and nobody would be…    30    49   335  6264 0.00782
    #>  8 father and daughter                              32    45   335  6264 0.00718
    #>  9 be careful what you wish for                     19    41   335  6264 0.00655
    #> 10 murder                                           25    41   335  6264 0.00655

### 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
    #> # A tibble: 10 × 10
    #>    theme_name                  k k_bar     n n_bar     K K_bar     N N_bar score
    #>    <chr>                   <int> <int> <int> <int> <int> <int> <int> <int> <dbl>
    #>  1 World War II               12    14   156  3035    12    14   335  6264 10.2
    #>  2 attitude of superiority    10    16   156  3035    11    17   335  6264  9.39
    #>  3 ironic twist of fate       32    60   156  3035    48    88   335  6264  8.94
    #>  4 acute anxiety               5    10   156  3035     5    10   335  6264  7.25
    #>  5 coping with being wash…     5    10   156  3035     5    10   335  6264  7.25
    #>  6 android                     6    15   156  3035     7    17   335  6264  7.18
    #>  7 boss and employee          14    17   156  3035    16    20   335  6264  7.12
    #>  8 the lust for gold          10    20   156  3035    13    25   335  6264  6.71
    #>  9 sadism                      5     9   156  3035     5     9   335  6264  6.53
    #> 10 the lust for power          4     9   156  3035     4     9   335  6264  6.53

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
    #> # A tibble: 10 × 10
    #>    theme_name                  k k_bar     n n_bar     K K_bar     N N_bar score
    #>    <chr>                   <int> <int> <int> <int> <int> <int> <int> <int> <dbl>
    #>  1 ironic twist of fate       26    26   156  1067    38    38   335  2199  4.61
    #>  2 attitude of superiority     6     6   156  1067     6     6   335  2199  4.35
    #>  3 coping with aging           9     9   156  1067    11    11   335  2199  3.65
    #>  4 acute anxiety               5     5   156  1067     5     5   335  2199  3.62
    #>  5 life in the American W…     5     5   156  1067     5     5   335  2199  3.62
    #>  6 what if I had amnesia       5     5   156  1067     5     5   335  2199  3.62
    #>  7 human vs. inexplicable…     8     8   156  1067    10    10   335  2199  3.11
    #>  8 the lust for gold           8     8   156  1067    10    10   335  2199  3.11
    #>  9 android                     6     6   156  1067     7     7   335  2199  2.94
    #> 10 coping with an obnoxio…     4     4   156  1067     4     4   335  2199  2.90

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
    #> # A tibble: 10 × 5
    #>    story_id     title                                  descript…¹  score commo…²
    #>    <chr>        <chr>                                  <chr>       <dbl> <list>
    #>  1 tz2002e1x31  The Monsters Are on Maple Street       "In an up… 0.550  <chr>
    #>  2 tz1959e2x28  Will the Real Martian Please Stand Up? "State tr… 0.223  <chr>
    #>  3 tz1959e3x03  The Shelter                            "An alert… 0.209  <chr>
    #>  4 tz1985e1x15b A Small Talent for War                 "An alien… 0.143  <chr>
    #>  5 tz2019e1x07  Not All Men                            "The peop… 0.138  <chr>
    #>  6 tz1985e1x24a A Day in Beaumont                      "After wi… 0.133  <chr>
    #>  7 tz1959e1x20  Elegy                                  "In the l… 0.124  <chr>
    #>  8 tz1959e5x09  Probe 7, Over and Out                  "An astro… 0.0980 <chr>
    #>  9 tz2019e1x04  A Traveler                             "A police… 0.0907 <chr>
    #> 10 tz2019e2x07  A Human Face                           "An alien… 0.0879 <chr>
    #> # … with abbreviated variable names ¹​description, ²​common_themes

The theory and methods implemented in the `get_enriched_themes` 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]]

## Download and Configure LTO Version Data

The package works with data from these LTO versions

    lto_version_statuses()

### 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.

## References

Onsjö, Mikael, and Paul Sheridan. 2020. “Theme Enrichment Analysis: A Statistical Test for Identifying Significantly Enriched Themes in a List of Stories with an Application to the Star Trek Television Franchise.” Digital Studies/Le Champ Numérique 10 (1): 1.
Sheridan, Paul, Mikael Onsjö, Claudia Becerra, Sergio Jimenez, and George Dueñas. 2019. “An Ontology-Based Recommender System with an Application to the Star Trek Television Franchise.” Future Internet 11 (9).
Sheridan, Paul, Mikael Onsjö, and Janna Hastings. 2019. “The Literary Theme Ontology for Media Annotation and Information Retrieval.” In Proceedings of the Joint Ontology Workshops 2019.
Wikipedia. 2021. “The Twilight Zone — Wikipedia, the Free Encyclopedia.” https://en.wikipedia.org/w/index.php?title=The%20Twilight%20Zone&oldid=1042023157.