This repository contains a Python package, totolo, for working with data from the Theme Ontology theming repository.
Install from PyPi:
pip install totolo
Or clone this repository and copy the totolo
directory wherever you need it. No dependencies are required.
#: import package
>>> import totolo
#: get the latest main branch version of the ontology
>>> ontology = totolo.remote()
>>> print(ontology)
<2945 themes, 4475 stories>
#: write it or read it locally
>>> ontology.write("/home/mo/themes")
>>> ontology = totolo.files("/home/mo/themes")
>>> print(ontology)
<2945 themes, 4475 stories>
Explore the themes:
#: go over all the themes and find the ones you want
>>> for theme in ontology.themes():
... if "romantic love" in theme.name:
... print(theme)
b'personal freedom vs. romantic love'[3]
b'romantic love'[3]
#: check the definition of a theme
>>> love = ontology.theme["love"]
>>> love.print()
(...)
Explore the stories:
>>> for weight, theme in story.iter_themes():
... print(f"{weight:<15} {theme.name}")
Choice Themes betrayal
Choice Themes the lust for power
(...)
Convert it to a pandas dataframe:
>>> df = ontology.dataframe()
>>> df
story_id title date theme weight
0 theamericanshortstory01 The Music School 1974 human self-reflection Major Themes
1 theamericanshortstory01 The Music School 1974 murder Major Themes
... ... ... ... ... ...
52453 videogame: Final Fantasy VI (1994) Final Fantasy VI 1994-04-02 feral children in society Minor Themes
52454 videogame: Final Fantasy VI (1994) Final Fantasy VI 1994-04-02 father and son Minor Themes
[52455 rows x 5 columns]
List official versioned releases of the ontology:
list(totolo.remote.versions())
Load the v2023.06 release:
ontology = totolo.remote.version('v2023.06')
Create an excel sheet with all the usages of the theme "loyalty" as well as any child theme of the same:
df = ontology.theme['loyalty'].descendants().dataframe(motivation=True, descriptions=True)
df.to_excel("/mnt/d/repos/themelist-loyalty.xlsx", "loyalty")
Find theme entries in stories according to some criteria. For example, find empty motivations:
empty_motivations = [
(story, weight, part)
for story in ontology.stories()
for weight, part in story.iter_theme_entries()
if part.motivation.strip() == ""
]
If you encounter a bug, please file a minimal reproducible example on GitHub issues. For feature requests and other matters, please post on the GitHub discussions board.
All code in this repository is published with the MIT license.