reading-impact-model


Namereading-impact-model JSON
Version 1.0.3 PyPI version JSON
download
home_pagehttps://github.com/marijnkoolen/reading-impact-model
Summary
upload_time2023-06-07 14:22:43
maintainer
docs_urlNone
authorMarijn Koolen
requires_python>=3.10,<4.0
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # reading-impact-model
Reading Impact Model for analyzing reading impact in online book reviews.

- [Explanation of the impact types](./docs/impact.md)
- [Examples of impact types](./docs/examples.md)
- [Installation and Usage](#installation-and-usage)
- [Citing](#citing)
- [Contributors](#contributors)

## The Impact of Fiction

How does your favorite book make you feel?

If you’re an avid reader, this question might be hard to answer. Books can make
us feel extatically happy or deeply sad. Books can inspire us, motivate us, or
make us feel like we are a part of something that matters. As long as stories
have existed, they have made people laugh, and they have made people cry.

In this research project, we are trying to measure the emotional impact of books
and stories, by analyzing the kind of emotional responses that readers express in
online reviews.

The <a href="https://impactandfiction.huygens.knaw.nl">Impact of Fiction</a> is a 
project of the <a href="https://huygens.knaw.nl">Huygens Institute</a> and the
<a href="https://huc.knaw.nl">KNAW Humanities Cluster</a>,
coordinated by Peter Boot (Huygens) and Marijn Koolen (KNAW Humanities Cluster).

## Computational Analysis of Reading Impact

There are millions upon millions of reviews on the internet today. Because of the
staggering number of online reviews available, computational analysis is the ideal
tool for analyzing them. But emotional impact is not easy to detect computationally.
That’s why we’ve created a list of words relating to features from literature
(aspect-terms) and a list of words relating to literature’s emotional impact
(impact-terms) and a set of rules formulated to measure impact in relation to
specific aspects.

Here’s an example:

<table class="rule-example">
    <tbody>
        <tr>
            <td>lovely</td>
            <td>+</td>
            <td>character</td>
            <td>=</td>
            <td>narrative engagement</td>
        </tr>
        <tr>
            <td>[impact-term]</td>
            <td>+</td>
            <td>[aspect-term]</td>
            <td>=</td>
            <td>type of impact</td>
        </tr>
    </tbody>
</table>

By looking at examples from a large set of online reviews, we formulated more than
1300 rules of this kind, measuring different types of impact. For an explanation of
our categories of impact, go to the “Explanation of impact” page.

Here’s another example: In 2020, researchers at the Huygens Institute completed a similar
research project on <a href="https://www.jbe-platform.com/content/journals/10.1075/ssol.20003.boo">Dutch online reviews.</a>
They found, among other things, that
Harry Potter and the Half-Blood Prince scored exceptionally high on use of the
word “magisch” (magical). Any human who knows Harry Potter could guess that this
doesn’t mean an exceptionally high number of reviewers had a magical reading
experience. Rather, in reference to Harry Potter, the word “magical” has little
to do with emotional response because the plot is actually about magic. 

There are lots of other fun and interesting things you could do if you had a clear
sense of the emotional impact of books. For example, this previous study into
Dutch reviews suggested that appreciation of a novel’s style is linked to reflection
on that novel. On the other hand, narrative engagement and mentions of style or
reflection are negatively correlated, meaning that books that are have a very
engaging, often suspenseful narrative are less frequently described as having an
affecting style or inviting reflection. Think of your favorite thriller: is this
true in that case?

## Installation and Usage

You can install the package via pip:

```
pip install reading-impact-model
```

Basic usage of the English language impact model:

```python
from reading_impact_model.matchers.matcher import ImpactMatcher

matcher = ImpactMatcher(lang='en')

matcher.analyse_text('The book has beautiful writing.', doc_id='some_doc_id')
```

Which gives the following output:

```python
[{'doc_id': 'some_doc_id',
  'sentence_index': None,
  'sentence': 'The book has beautiful writing.',
  'reflection': 0,
  'style': 1,
  'attention': 0,
  'humor': 0,
  'surprise': 0,
  'narrative': 0,
  'negative': 0,
  'positive': 1,
  'match_index': 3,
  'impact_term_type': 'term',
  'impact_term': 'beautiful',
  'impact_type': 'Style',
  'match_lemma': 'beautiful',
  'match_word': 'beautiful',
  'condition_match_index': 4,
  'condition_term': 'writing',
  'condition_match_lemma': 'writing',
  'condition_type': 'style',
  'condition_match_word': 'writing'}]
```


There are different matchers that can incorporate syntax parsers to 
add POS and lemma information to word tokens, for improved rule matching.

E.g. the `SpacyMatcher` accepts a Spacy parser (and requires you to have 
installed spacy and an appropriate language model.)
```python
from reading_impact_model.matchers.spacy_matcher import SpacyMatcher
import spacy

nlp = spacy.load('en_core_web_trf') 
matcher = SpacyMatcher(parser=nlp)
```

Which matches the lemma _sentence_ instead of the word _sentences_, which is not in the aspect dictionary.

```python
[{'doc_id': 'some_doc_id',
  'sentence_index': 0,
  'sentence': 'The book contains some beautifully written sentences.',
  'style': 1,
  'surprise': 0,
  'negative': 0,
  'narrative': 0,
  'humor': 0,
  'attention': 0,
  'reflection': 0,
  'positive': 1,
  'match_index': 4,
  'impact_type': 'Style',
  'impact_term': 'beautifully',
  'match_word': 'beautifully',
  'impact_term_type': 'term',
  'match_lemma': 'beautifully',
  'condition_type': 'style',
  'condition_match_word': 'sentences',
  'condition_match_index': 6,
  'condition_match_lemma': 'sentence',
  'condition_term': 'sentence'}]
```

## Citing

If you use this package, please cite the following publications:

- Boot, P., & Koolen, M. (2020). [Captivating, splendid or instructive? 
Assessing the impact of reading in online book reviews.](https://www.jbe-platform.com/content/journals/10.1075/ssol.20003.boo) 
Scientific Study of Literature, 10(1), 35-63. ([pre-pub PDF](https://marijnkoolen.com/publications/2020/boot2020captivating.pdf))
- Koolen, M., Neugarten, J., & Boot, P. (2022). [‘This book makes me 
happy and sad and I love it’. A Rule-based Model for Extracting Reading 
Impact from English Book Reviews.](https://jcls.io/article/id/104/)
Journal of Computational Literary Studies, 1(1).

## Contributors

The `reading-impact-model` package was developed by Marijn Koolen. The rule
set and dictionaries were created by Peter Boot, Julia Neugarten and Marijn
Koolen.

The following people are or have been involved in the Impact & Fiction project:

<ul>
    <li>Peter Boot</li>
    <li>Marijn Koolen</li>
    <li>Joris van Zundert</li>
    <li>Julia Neugarten</li>
    <li>Olivia Fialho</li>
    <li>Willem van Hage</li>
    <li>Ole Mussmann</li>
    <li>Carsten Schnober</li>
</ul>


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/marijnkoolen/reading-impact-model",
    "name": "reading-impact-model",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.10,<4.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "Marijn Koolen",
    "author_email": "marijn.koolen@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/2e/72/f4c47e664670d357ffdba0a0e25ec6d5d55c33e96e68880e43992a24efa4/reading_impact_model-1.0.3.tar.gz",
    "platform": null,
    "description": "# reading-impact-model\nReading Impact Model for analyzing reading impact in online book reviews.\n\n- [Explanation of the impact types](./docs/impact.md)\n- [Examples of impact types](./docs/examples.md)\n- [Installation and Usage](#installation-and-usage)\n- [Citing](#citing)\n- [Contributors](#contributors)\n\n## The Impact of Fiction\n\nHow does your favorite book make you feel?\n\nIf you\u2019re an avid reader, this question might be hard to answer. Books can make\nus feel extatically happy or deeply sad. Books can inspire us, motivate us, or\nmake us feel like we are a part of something that matters. As long as stories\nhave existed, they have made people laugh, and they have made people cry.\n\nIn this research project, we are trying to measure the emotional impact of books\nand stories, by analyzing the kind of emotional responses that readers express in\nonline reviews.\n\nThe <a href=\"https://impactandfiction.huygens.knaw.nl\">Impact of Fiction</a> is a \nproject of the <a href=\"https://huygens.knaw.nl\">Huygens Institute</a> and the\n<a href=\"https://huc.knaw.nl\">KNAW Humanities Cluster</a>,\ncoordinated by Peter Boot (Huygens) and Marijn Koolen (KNAW Humanities Cluster).\n\n## Computational Analysis of Reading Impact\n\nThere are millions upon millions of reviews on the internet today. Because of the\nstaggering number of online reviews available, computational analysis is the ideal\ntool for analyzing them. But emotional impact is not easy to detect computationally.\nThat\u2019s why we\u2019ve created a list of words relating to features from literature\n(aspect-terms) and a list of words relating to literature\u2019s emotional impact\n(impact-terms) and a set of rules formulated to measure impact in relation to\nspecific aspects.\n\nHere\u2019s an example:\n\n<table class=\"rule-example\">\n    <tbody>\n        <tr>\n            <td>lovely</td>\n            <td>+</td>\n            <td>character</td>\n            <td>=</td>\n            <td>narrative engagement</td>\n        </tr>\n        <tr>\n            <td>[impact-term]</td>\n            <td>+</td>\n            <td>[aspect-term]</td>\n            <td>=</td>\n            <td>type of impact</td>\n        </tr>\n    </tbody>\n</table>\n\nBy looking at examples from a large set of online reviews, we formulated more than\n1300 rules of this kind, measuring different types of impact. For an explanation of\nour categories of impact, go to the \u201cExplanation of impact\u201d page.\n\nHere\u2019s another example: In 2020, researchers at the Huygens Institute completed a similar\nresearch project on <a href=\"https://www.jbe-platform.com/content/journals/10.1075/ssol.20003.boo\">Dutch online reviews.</a>\nThey found, among other things, that\nHarry Potter and the Half-Blood Prince scored exceptionally high on use of the\nword \u201cmagisch\u201d (magical). Any human who knows Harry Potter could guess that this\ndoesn\u2019t mean an exceptionally high number of reviewers had a magical reading\nexperience. Rather, in reference to Harry Potter, the word \u201cmagical\u201d has little\nto do with emotional response because the plot is actually about magic. \n\nThere are lots of other fun and interesting things you could do if you had a clear\nsense of the emotional impact of books. For example, this previous study into\nDutch reviews suggested that appreciation of a novel\u2019s style is linked to reflection\non that novel. On the other hand, narrative engagement and mentions of style or\nreflection are negatively correlated, meaning that books that are have a very\nengaging, often suspenseful narrative are less frequently described as having an\naffecting style or inviting reflection. Think of your favorite thriller: is this\ntrue in that case?\n\n## Installation and Usage\n\nYou can install the package via pip:\n\n```\npip install reading-impact-model\n```\n\nBasic usage of the English language impact model:\n\n```python\nfrom reading_impact_model.matchers.matcher import ImpactMatcher\n\nmatcher = ImpactMatcher(lang='en')\n\nmatcher.analyse_text('The book has beautiful writing.', doc_id='some_doc_id')\n```\n\nWhich gives the following output:\n\n```python\n[{'doc_id': 'some_doc_id',\n  'sentence_index': None,\n  'sentence': 'The book has beautiful writing.',\n  'reflection': 0,\n  'style': 1,\n  'attention': 0,\n  'humor': 0,\n  'surprise': 0,\n  'narrative': 0,\n  'negative': 0,\n  'positive': 1,\n  'match_index': 3,\n  'impact_term_type': 'term',\n  'impact_term': 'beautiful',\n  'impact_type': 'Style',\n  'match_lemma': 'beautiful',\n  'match_word': 'beautiful',\n  'condition_match_index': 4,\n  'condition_term': 'writing',\n  'condition_match_lemma': 'writing',\n  'condition_type': 'style',\n  'condition_match_word': 'writing'}]\n```\n\n\nThere are different matchers that can incorporate syntax parsers to \nadd POS and lemma information to word tokens, for improved rule matching.\n\nE.g. the `SpacyMatcher` accepts a Spacy parser (and requires you to have \ninstalled spacy and an appropriate language model.)\n```python\nfrom reading_impact_model.matchers.spacy_matcher import SpacyMatcher\nimport spacy\n\nnlp = spacy.load('en_core_web_trf') \nmatcher = SpacyMatcher(parser=nlp)\n```\n\nWhich matches the lemma _sentence_ instead of the word _sentences_, which is not in the aspect dictionary.\n\n```python\n[{'doc_id': 'some_doc_id',\n  'sentence_index': 0,\n  'sentence': 'The book contains some beautifully written sentences.',\n  'style': 1,\n  'surprise': 0,\n  'negative': 0,\n  'narrative': 0,\n  'humor': 0,\n  'attention': 0,\n  'reflection': 0,\n  'positive': 1,\n  'match_index': 4,\n  'impact_type': 'Style',\n  'impact_term': 'beautifully',\n  'match_word': 'beautifully',\n  'impact_term_type': 'term',\n  'match_lemma': 'beautifully',\n  'condition_type': 'style',\n  'condition_match_word': 'sentences',\n  'condition_match_index': 6,\n  'condition_match_lemma': 'sentence',\n  'condition_term': 'sentence'}]\n```\n\n## Citing\n\nIf you use this package, please cite the following publications:\n\n- Boot, P., & Koolen, M. (2020). [Captivating, splendid or instructive? \nAssessing the impact of reading in online book reviews.](https://www.jbe-platform.com/content/journals/10.1075/ssol.20003.boo) \nScientific Study of Literature, 10(1), 35-63. ([pre-pub PDF](https://marijnkoolen.com/publications/2020/boot2020captivating.pdf))\n- Koolen, M., Neugarten, J., & Boot, P. (2022). [\u2018This book makes me \nhappy and sad and I love it\u2019. A Rule-based Model for Extracting Reading \nImpact from English Book Reviews.](https://jcls.io/article/id/104/)\nJournal of Computational Literary Studies, 1(1).\n\n## Contributors\n\nThe `reading-impact-model` package was developed by Marijn Koolen. The rule\nset and dictionaries were created by Peter Boot, Julia Neugarten and Marijn\nKoolen.\n\nThe following people are or have been involved in the Impact & Fiction project:\n\n<ul>\n    <li>Peter Boot</li>\n    <li>Marijn Koolen</li>\n    <li>Joris van Zundert</li>\n    <li>Julia Neugarten</li>\n    <li>Olivia Fialho</li>\n    <li>Willem van Hage</li>\n    <li>Ole Mussmann</li>\n    <li>Carsten Schnober</li>\n</ul>\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "",
    "version": "1.0.3",
    "project_urls": {
        "Homepage": "https://github.com/marijnkoolen/reading-impact-model",
        "Repository": "https://github.com/marijnkoolen/reading-impact-model"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b01e783d4d0d5f9699a1197fcc3fd373993cffac7e33d54b1d9428f833f7b6c2",
                "md5": "da38f2094fb054750a7bad05fcd6cdd0",
                "sha256": "b36b7139525ca0ff9f7dd248f9528082c366f35fcfcb9be1b63488e100d1eac0"
            },
            "downloads": -1,
            "filename": "reading_impact_model-1.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "da38f2094fb054750a7bad05fcd6cdd0",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10,<4.0",
            "size": 705330,
            "upload_time": "2023-06-07T14:22:37",
            "upload_time_iso_8601": "2023-06-07T14:22:37.093722Z",
            "url": "https://files.pythonhosted.org/packages/b0/1e/783d4d0d5f9699a1197fcc3fd373993cffac7e33d54b1d9428f833f7b6c2/reading_impact_model-1.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2e72f4c47e664670d357ffdba0a0e25ec6d5d55c33e96e68880e43992a24efa4",
                "md5": "1bffbaecf91da017653b3bd264cdbd1b",
                "sha256": "550aacabe0d1be4dc61bda3735113f6d306083cf559199143dc63f0355b4c675"
            },
            "downloads": -1,
            "filename": "reading_impact_model-1.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "1bffbaecf91da017653b3bd264cdbd1b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10,<4.0",
            "size": 785673,
            "upload_time": "2023-06-07T14:22:43",
            "upload_time_iso_8601": "2023-06-07T14:22:43.787715Z",
            "url": "https://files.pythonhosted.org/packages/2e/72/f4c47e664670d357ffdba0a0e25ec6d5d55c33e96e68880e43992a24efa4/reading_impact_model-1.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-06-07 14:22:43",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "marijnkoolen",
    "github_project": "reading-impact-model",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "reading-impact-model"
}
        
Elapsed time: 0.07346s