# LibEscansión
> A metrical scansion library for Spanish
[](https://opensource.org/licenses/LGPL-2.1)
[](https://github.com/fsanzl/libEscansion/releases/tag/1.0.1)
[](https://www.python.org/downloads/release/python-311/)
<h2 align="center">libEscansión</h2>
<h3 align="center">A Python library for for metrical scansion of mixed Spanish verses</h2>
*libEscansión* is a state-of-the-art Python library for analysing Spanish mixed verses. It parses the verse to find syllabic nuclei, rhythmic pattern, assonance, and consonance, as well as to provide a phonological transcription of the syllables. It scores 98.64% accuracy against the manually annotated corpus [ADSO 100] with the option *adso=True*, which forces considering interjections as non-stressed to meet ADSO's annotation criteria. This tops the until-now state-of-the-art. Nevertheless, vanilla scansion – i.e., stressing interjections – still outperforms the state-of-the art, achieving 97.01% accuracy. Furthermore, after evaluating the corpus' manual scansion and spelling, we found that the disagreement was in most cases due to an improper spelling or even to non-standard human analysis (unstressed interjections, adverbd in -mente lacking secondary stress, etc.). With a corrected corpus, the agreement reaches 99.13 %, being the resting 0.87% non-erroneus disagreements.
This library is part of the research project [Sound and Meaning in Spanish Golden Age Literature](https://soundandmeaning.univie.ac.at/). It was created as a means to generate a corpus of parsed metres, which is publicicily accessible [here](https://soundandmeaning.univie.ac.at/?page_id=175)
## Installation
```sh
pip install libEscansion
```
## Requeriments
Following libraries are required:
* *stanza* >= 1.7 with Spanish language models
* *fonemas* >= 2.0.18
* *silabeador* >= 1.1.11.post6
## Usage example
The library provides the class *VerseMetre*. It accepts an obligatory string for the verse and an optional list of integers with possibles syllable-counts. If a second argment is not provided, it performs a regular scansion, i.e., with all natural dialoephas.
```python
>>> import libEscansion
>>> verse = verse = libscansion.VerseMetre('Cerrar podrá mis ojos la postrera ', [11,8,7])
>>> verse.count
11
>>> verse.syllables
['θe', 'rAɾ', 'po', 'dɾA', 'mis', 'O', 'xos', 'la', 'pos', 'tɾE', 'ɾa']
>>> verse.nuclei
'eAoAiOoaoEa'
>>> verse.rhyme
'eɾa'
>>> verse.asson
'ea'
>>> verse.rhythm
'-+-+-+---+-'
```
The directory 'utils' contains a file that can be used to test the library against ADSO 100 (or any other corpus of sonnets whasoever as long as they are encoded as XML-TEI with their metres are annotated). In the same directory containing the XML files, type:
```bash
./adso100test.py *xml
```
## Release History
### 1.0.0 (24/07/2023)
- First public version
### 1.0.0pre5 (5/07/2023)
- Solved bug with fewer syllables than expected
### 1.0.0pre4 (20/06/2023)
- Rules diphthong vs perception for triphthong
### 1.0.0pre2 (17/04/2023)
- Solved diaereses identification issue
### 1.0.0pre1
- Initial arrangement of the directory tree, metadata, &c. to make the mess more presentable in public
## How to cite *libEscansión*
Authors of scientific papers including results generated using *libEscansión* are encouraged to cite the following paper.
```bibtex
@article{SanzLazaroF_RHD2023,
author = {Sanz-Lázaro, Fernando},
title = {Del fonema al verso: una caja de herramientas digitales de escansión teatral},
volume = {8},
date = {2023},
journal = {Revista de Humanidades Digitales},
pages = {74-89},
doi = {https://doi.org/10.5944/rhd.vol.8.2023.37830}
}
```
## Meta
Copyright 2023 Fernando Sanz-Lázaro – [@FerdlSanz](https://twitter.com/ferdlsanz) – fsanzl@gmail.com
Distributed under the LGPL 2.1 license. See ``LICENSE`` for more information.
[https://github.com/fsanzl/libEscansion](https://github.com/dbader/)
## Contributing
1. Fork it (<https://github.com/fsanzl/libEscansion/fork>)
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -am 'Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a new Pull Request
## Copyright
Copyright (C) 2023 Fernando Sanz-Lázaro <<fsanzl@gmail.com>>
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library. If not, see <<https://www.gnu.org/licenses/>>.
## References
ADSO 100: Navarro-Colorado, Borja; Ribes Lafoz, María, and Sánchez, Noelia (2015) "Metrical annotation of a large corpus of Spanish sonnets: representation, scansion and evaluation" 10th edition of the Language Resources and Evaluation Conference 2016 Portorož, Slovenia. ([PDF](http://www.dlsi.ua.es/~borja/navarro2016_MetricalPatternsBank.pdf))
<!-- Markdown link & img dfn's -->
[license]: https://img.shields.io/github/license/fsanzl/libEscansion
[license-url]: https://opensource.org/licenses/LGPL-2.1
[version]: https://img.shields.io/github/v/release/fsanzl/libEscansion
[version-url]: https://pypi.org/project/libEscansion/
[python-version]: https://img.shields.io/pypi/pyversions/libEscansion
[python-version-url]: https://pypi.org/project/libEscansion/
[wiki]: https://github.com/yourname/yourproject/wiki
Raw data
{
"_id": null,
"home_page": "https://github.com/fsanzl/libEscansion",
"name": "libEscansion",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Fernando Sanz-L\u00e1zaro",
"author_email": "fsanzl@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/da/88/b25e1d7d6923208acad6696b0f220bea08d60e9e42ca9e286b1a212ec091/libEscansion-1.0.1.post1.tar.gz",
"platform": null,
"description": "# LibEscansi\u00f3n\n> A metrical scansion library for Spanish\n[](https://opensource.org/licenses/LGPL-2.1)\n[](https://github.com/fsanzl/libEscansion/releases/tag/1.0.1)\n[](https://www.python.org/downloads/release/python-311/)\n\n<h2 align=\"center\">libEscansi\u00f3n</h2>\n\n<h3 align=\"center\">A Python library for for metrical scansion of mixed Spanish verses</h2>\n\n\n*libEscansi\u00f3n* is a state-of-the-art Python library for analysing Spanish mixed verses. It parses the verse to find syllabic nuclei, rhythmic pattern, assonance, and consonance, as well as to provide a phonological transcription of the syllables. It scores 98.64% accuracy against the manually annotated corpus [ADSO 100] with the option *adso=True*, which forces considering interjections as non-stressed to meet ADSO's annotation criteria. This tops the until-now state-of-the-art. Nevertheless, vanilla scansion \u2013 i.e., stressing interjections \u2013 still outperforms the state-of-the art, achieving 97.01% accuracy. Furthermore, after evaluating the corpus' manual scansion and spelling, we found that the disagreement was in most cases due to an improper spelling or even to non-standard human analysis (unstressed interjections, adverbd in -mente lacking secondary stress, etc.). With a corrected corpus, the agreement reaches 99.13 %, being the resting 0.87% non-erroneus disagreements.\n\nThis library is part of the research project [Sound and Meaning in Spanish Golden Age Literature](https://soundandmeaning.univie.ac.at/). It was created as a means to generate a corpus of parsed metres, which is publicicily accessible [here](https://soundandmeaning.univie.ac.at/?page_id=175)\n\n\n## Installation\n\n```sh\npip install libEscansion\n```\n\n## Requeriments\n\nFollowing libraries are required:\n\n* *stanza* >= 1.7 with Spanish language models\n* *fonemas* >= 2.0.18\n* *silabeador* >= 1.1.11.post6 \n\n\n\n## Usage example\n\nThe library provides the class *VerseMetre*. It accepts an obligatory string for the verse and an optional list of integers with possibles syllable-counts. If a second argment is not provided, it performs a regular scansion, i.e., with all natural dialoephas.\n\n\n```python \n>>> import libEscansion\n>>> verse = verse = libscansion.VerseMetre('Cerrar podr\u00e1 mis ojos la postrera ', [11,8,7])\n>>> verse.count \n11\n>>> verse.syllables\n['\u03b8e', 'rA\u027e', 'po', 'd\u027eA', 'mis', 'O', 'xos', 'la', 'pos', 't\u027eE', '\u027ea']\n>>> verse.nuclei \n'eAoAiOoaoEa'\n>>> verse.rhyme\n'e\u027ea'\n>>> verse.asson\n'ea'\n>>> verse.rhythm \n'-+-+-+---+-'\n```\nThe directory 'utils' contains a file that can be used to test the library against ADSO 100 (or any other corpus of sonnets whasoever as long as they are encoded as XML-TEI with their metres are annotated). In the same directory containing the XML files, type:\n\n```bash\n./adso100test.py *xml\n```\n\n## Release History\n\n### 1.0.0 (24/07/2023)\n\n- First public version\n\n### 1.0.0pre5 (5/07/2023)\n\n- Solved bug with fewer syllables than expected\n\n### 1.0.0pre4 (20/06/2023)\n\n- Rules diphthong vs perception for triphthong\n\n### 1.0.0pre2 (17/04/2023)\n\n- Solved diaereses identification issue\n\n### 1.0.0pre1\n\n- Initial arrangement of the directory tree, metadata, &c. to make the mess more presentable in public\n\n## How to cite *libEscansi\u00f3n*\n\nAuthors of scientific papers including results generated using *libEscansi\u00f3n* are encouraged to cite the following paper.\n\n```bibtex\n@article{SanzLazaroF_RHD2023, \n author = {Sanz-L\u00e1zaro, Fernando},\n title = {Del fonema al verso: una caja de herramientas digitales de escansi\u00f3n teatral},\n volume = {8},\n date = {2023},\n journal = {Revista de Humanidades Digitales},\n pages = {74-89},\n doi = {https://doi.org/10.5944/rhd.vol.8.2023.37830}\n}\n```\n\n## Meta\n\nCopyright 2023 Fernando Sanz-L\u00e1zaro \u2013 [@FerdlSanz](https://twitter.com/ferdlsanz) \u2013 fsanzl@gmail.com\n\nDistributed under the LGPL 2.1 license. See ``LICENSE`` for more information.\n\n[https://github.com/fsanzl/libEscansion](https://github.com/dbader/)\n\n## Contributing\n\n1. Fork it (<https://github.com/fsanzl/libEscansion/fork>)\n2. Create your feature branch (`git checkout -b feature/fooBar`)\n3. Commit your changes (`git commit -am 'Add some fooBar'`)\n4. Push to the branch (`git push origin feature/fooBar`)\n5. Create a new Pull Request\n\n## Copyright\n\nCopyright (C) 2023 Fernando Sanz-L\u00e1zaro <<fsanzl@gmail.com>>\n\nThis library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.\n\nThis library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.\n\nYou should have received a copy of the GNU Lesser General Public License along with this library. If not, see <<https://www.gnu.org/licenses/>>.\n\n## References\n\nADSO 100: Navarro-Colorado, Borja; Ribes Lafoz, Mar\u00eda, and S\u00e1nchez, Noelia (2015) \"Metrical annotation of a large corpus of Spanish sonnets: representation, scansion and evaluation\" 10th edition of the Language Resources and Evaluation Conference 2016 Portoro\u017e, Slovenia. ([PDF](http://www.dlsi.ua.es/~borja/navarro2016_MetricalPatternsBank.pdf))\n\n\n<!-- Markdown link & img dfn's -->\n[license]: https://img.shields.io/github/license/fsanzl/libEscansion\n[license-url]: https://opensource.org/licenses/LGPL-2.1\n[version]: https://img.shields.io/github/v/release/fsanzl/libEscansion\n[version-url]: https://pypi.org/project/libEscansion/\n[python-version]: https://img.shields.io/pypi/pyversions/libEscansion\n[python-version-url]: https://pypi.org/project/libEscansion/\n[wiki]: https://github.com/yourname/yourproject/wiki\n\n\n",
"bugtrack_url": null,
"license": "LGPL",
"summary": "Metrical scansion for Spanish verses",
"version": "1.0.1.post1",
"project_urls": {
"Homepage": "https://github.com/fsanzl/libEscansion",
"Source": "https://github.com/fsanzl/libEscansion/",
"Tracker": "https://github.com/fsanzl/libEscansion/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a52b030de3b98bda9a5bfb5dfac877bbebda89ac2cdb7ee53fa5028721b31b5",
"md5": "7d7c3ac8320524f68a21481f3f91e0f1",
"sha256": "356544e9e4e6ef7074e2a42d947c0a92c8db05c99944c236e80341a350a74b91"
},
"downloads": -1,
"filename": "libEscansion-1.0.1.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d7c3ac8320524f68a21481f3f91e0f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21001,
"upload_time": "2024-02-03T12:20:49",
"upload_time_iso_8601": "2024-02-03T12:20:49.748692Z",
"url": "https://files.pythonhosted.org/packages/5a/52/b030de3b98bda9a5bfb5dfac877bbebda89ac2cdb7ee53fa5028721b31b5/libEscansion-1.0.1.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da88b25e1d7d6923208acad6696b0f220bea08d60e9e42ca9e286b1a212ec091",
"md5": "74b1929c7c43d594e586ee14b7de66d9",
"sha256": "56090a3b2a76b42f902d9386d03817fbaf88aa3b731f7b9097b9a51b986b4612"
},
"downloads": -1,
"filename": "libEscansion-1.0.1.post1.tar.gz",
"has_sig": false,
"md5_digest": "74b1929c7c43d594e586ee14b7de66d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 23551,
"upload_time": "2024-02-03T12:20:52",
"upload_time_iso_8601": "2024-02-03T12:20:52.163056Z",
"url": "https://files.pythonhosted.org/packages/da/88/b25e1d7d6923208acad6696b0f220bea08d60e9e42ca9e286b1a212ec091/libEscansion-1.0.1.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 12:20:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fsanzl",
"github_project": "libEscansion",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "libescansion"
}
JSON
