{"id":19704243,"url":"https://github.com/dbklim/stressrnn","last_synced_at":"2025-04-29T14:31:16.129Z","repository":{"id":53122871,"uuid":"306460871","full_name":"dbklim/StressRNN","owner":"dbklim","description":"Modified version of RusStress (https://github.com/MashaPo/russtress) — python package for placing stress in Russian text using RNN (BiLSTM) and the \"Grammatical Dictionary\" by A. A. Zaliznyak (from http://odict.ru/).","archived":false,"fork":false,"pushed_at":"2024-08-07T22:20:48.000Z","size":1469,"stargazers_count":33,"open_issues_count":5,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T17:51:13.390Z","etag":null,"topics":["accent","bilstm","emphasis","linguistic","linguistics","lstm","nlp","rnn","russian","russian-accent","russian-stress","russtress","rustress","stress"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbklim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-22T21:18:16.000Z","updated_at":"2025-03-04T13:04:08.000Z","dependencies_parsed_at":"2022-09-08T11:51:45.972Z","dependency_job_id":"6acc8c18-ae45-429d-85ac-dea341946e75","html_url":"https://github.com/dbklim/StressRNN","commit_stats":null,"previous_names":["dbklim/stressrnn"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbklim%2FStressRNN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbklim%2FStressRNN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbklim%2FStressRNN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbklim%2FStressRNN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbklim","download_url":"https://codeload.github.com/dbklim/StressRNN/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251518983,"owners_count":21602244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accent","bilstm","emphasis","linguistic","linguistics","lstm","nlp","rnn","russian","russian-accent","russian-stress","russtress","rustress","stress"],"created_at":"2024-11-11T21:21:33.645Z","updated_at":"2025-04-29T14:31:11.119Z","avatar_url":"https://github.com/dbklim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StressRNN\n\nThis tool based on LSTM predicts stress position in each word in russian text depending on the word context.\nFor more details about the tool see [«Automated Word Stress Detection in Russian»](http://www.aclweb.org/anthology/W/W17/W17-4104.pdf), EMNLP-2017, Copenhagen, Denmark.\n\nThis is a modified version of the [RusStress](https://github.com/MashaPo/russtress) (many thanks to its authors!). The modification fixes some bugs, improves the quality of stress placement and the usability of the project. The neural network and the principles of working with it remained unchanged.\n\n## Modification features\n\nThe modification has the following differences from the original RusStress:\n\n- added stress symbol `'+'`\n- the list of supported stress symbols is limited to `\"'\"` and `'+'` (always added after a stressed vowel)\n- added filtering of neural network responses by accuracy (allows you to cut off stresses, the prediction accuracy of which is lower (\u003c=) than specified)\n- added stress placing in words with 1 vowel\n- improved work with hyphenated words (earlier, stress was placed only on the first part of the word, now it's placed on both parts)\n- implemented skipping words with pre-set stresses (it used to lead to undefined behavior)\n- added replacement of similar Latin symbols with the same Cyrillic ones (for example, `A` -\u003e `А`, `e` -\u003e `е`) (the full list is available in [SAME_LETTERS_EN_RU](https://github.com/Desklop/StressRNN/blob/master/stressrnn/constants.py#L27))\n- fixed bug with some words, in which the stress was placed on a consonant letter, not a vowel (stress index is shift to next vowel or to the previous one, if there are no vowels after stress) (for example, \"дойдете\", \"зряченюхослышащий\") (these words were added to the [exception dictionary](https://github.com/Desklop/StressRNN/blob/master/stressrnn/source_exception_dictionary.txt))\n- added an exception dictionary and the ability to load your own additional exception dictionary when creating a class object\n- added a [default exception dictionary](https://github.com/Desklop/StressRNN/blob/master/stressrnn/exception_dictionary.txt) based on the \"Grammatical dictionary\" by A. A. Zaliznyak from http://odict.ru/ (supplied with the package)\n- compiled all regular expressions to improve performance\n- code refactoring was performed\n- added support for TensorFlow v2.X\n- optimization of work speed: added work with neural network in batch mode (speeds up work by 1.5-2 times)\n- optimization of work speed: added predict using ONNX Runtime (increases work speed of model by 10-30 times on the CPU)\n\nThese changes allow you to use this package in projects such as speech synthesis, without any changes, \"out of the box\".\n\n## Installation\n\nSimple installation with pip (python 3.6-3.10 supported):\n\n```bash\npip3 install git+https://github.com/Desklop/StressRNN\n```\n\nOr installing from sources:\n\n```bash\ngit clone https://github.com/Desklop/StressRNN \u0026\u0026 cd StressRNN\nvirtualenv env_base \u0026\u0026 source env_base/bin/activate\npip install -r requirements.txt\npython3 setup.py bdist_wheel\n```\n\nThen copy .whl package from `/dist` to your project and run:\n\n```bash\npip install stressrnn-0.2.*.whl\n```\n\nFor development, you need to additionally install TensorFlow:\n\n```bash\ngit clone https://github.com/Desklop/StressRNN \u0026\u0026 cd StressRNN\nvirtualenv env_base \u0026\u0026 source env_base/bin/activate\npip install -r requirements_dev.txt\n```\n\n**Full dependencies:** `numpy\u003e=1.16.0 pymorphy2[fast]\u003c=0.9.2 tensorflow\u003c=2.2.2 onnxruntime\u003c=1.15.1 keras2onnx\u003c=1.7` (listed in [requirements_dev.txt](https://github.com/Desklop/StressRNN/blob/master/requirements_dev.txt), only Python 3.6-3.8).\n\n**Dependencies for package use only:** `numpy\u003e=1.16.0 pymorphy2[fast]\u003c=0.9.2 onnxruntime\u003c=1.15.1` (listed in [requirements.txt](https://github.com/Desklop/StressRNN/blob/master/requirements.txt)).\n\n**Note 1:** TensorFlow v2.X is supported, but the work speed using TensorFlow v2.X is about 3-5 times lower than with TensorFlow v1.X.\n\n**Note 2:** ONNX Runtime is used by default. This increases the work speed of package by 10-30 times on the CPU (on Intel i7-10510U, with TensorFlow v1.X test phrase processing time is about 150 ms, with ONNX Runtime — about 1-3 ms).\n\n## Usage\n\nExample of stress placement in your text:\n\n```python\nfrom stressrnn import StressRNN\n\nstress_rnn = StressRNN()\n\ntext = 'Проставь, пожалуйста, ударения'\nstressed_text = stress_rnn.put_stress(text, stress_symbol='+', accuracy_threshold=0.75, replace_similar_symbols=True)\nprint(stressed_text)  # 'Проста+вь, пожа+луйста, ударе+ния'\n```\n\nThe package contains 2 classes: [StressRNN](https://github.com/Desklop/StressRNN/blob/master/stressrnn/stressrnn.py#L40) and [ExceptionDictWrapper](https://github.com/Desklop/StressRNN/blob/master/stressrnn/exception_dictionary_wrapper.py#L24).\n\n---\n\n### [StressRNN](https://github.com/Desklop/StressRNN/blob/master/stressrnn/stressrnn.py#L40) class\n\nThe placement of stress in text using BiLSTM.\n\nAdditionally, the exception dictionary is supported, which must contain a list of words with stresses placed in them using the `\"'\"` or `'+'` symbol after the vowel (1 line = 1 word). The exception dictionary is used before the neural network (if a match was found, the neural network is not used).\n\nThe dictionary looks like this:\n\n```text\n    дре+гер\n    ивано+в\n    ...\n```\n\nThe main dictionary comes with the package and is located in [`stressrnn/exception_dictionary.txt`](https://github.com/Desklop/StressRNN/blob/master/stressrnn/exception_dictionary.txt). You can also add your own dictionary, the values from which will complement the main dictionary (and overwrite the same words, but with different stresses).\n\nAccepts arguments:\n\n1. `f_name_add_exception_dict` - name of additional .txt dictionary with exceptions\n\n**Contains methods:**\n\n```python\nput_stress(self, text: str, stress_symbol:str = '+', accuracy_threshold: float = 0.75, replace_similar_symbols: bool = False, lemmatize_words: bool = False) -\u003e str:\n```\n\nSplit the text into words and place stress on them. The source text formatting is preserved. If some words already have an stress, it will be saved.\n\nThe stress is indicated using the `\"'\"` or `'+'` symbol after the stressed vowel.\n\nThe threshold for the accuracy of stress placement allows you to cut off stresses, the prediction accuracy of which is lower (\u003c=) than specified. The 0.75 threshold reduces the number of incorrectly placed stresses, but increases the number of words that will not be stressed. The 0.0 threshold allows you to place stresses in absolutely all words, but not always correctly.\n\n1. `text` - string with text\n2. `stress_symbol` - stress symbol, only `\"'\"` and `'+'` are supported\n3. `accuracy_threshold` - threshold for the accuracy of stress placement (from `0.0` to `1.0`)\n4. `replace_similar_symbols` - `True`: replacing similar latin symbols with cyrillic ones\n5. `lemmatize_words` - `True`: lemmatize (normalize) each word before searching in exception dictionary\n6. returns text with placed stresses\n\n---\n\n### [ExceptionDictWrapper](https://github.com/Desklop/StressRNN/blob/master/stressrnn/exception_dictionary_wrapper.py#L24) class\n\nException dictionary for correcting stress placement.\n\nThe exception dictionary must contain a list of words with stresses placed in them using the `\"'\"` or `'+'` symbol after the vowel (1 line = 1 word).\n\nThe dictionary looks like this:\n\n```text\n    дре+гер\n    ивано+в\n    ...\n```\n\nThe main dictionary comes with the package and is located in [`stressrnn/exception_dictionary.txt`](https://github.com/Desklop/StressRNN/blob/master/stressrnn/exception_dictionary.txt). You can also add your own dictionary, the values from which will complement the main dictionary (and overwrite the same words, but with different stresses).\n\nAccepts arguments:\n\n1. `f_name_add_exception_dict` - name of additional .txt dictionary with exceptions\n\n**Contains methods:**\n\n```python\nis_in_dict(self, word: str, lemmatize_word: bool = False) -\u003e bool:\n```\n\nChecking if the word is in the dictionary.\n\n1. `word` - string with the word of interest\n2. `lemmatize_word` - `True`: lemmatize (normalize) word before searching in dictionary\n3. returns `True`/`False`\n\n```python\nput_stress(self, word: str, stress_symbol: str, lemmatize_word: bool = False) -\u003e str:\n```\n\nPut stress in a word in accordance with the dictionary. Stress is indicated by stress_symbol after the stressed vowel.\n\n1. `word` - string with the word of interest\n2. `stress_symbol` - stress symbol\n3. `lemmatize_word` - `True`: lemmatize (normalize) word before searching in dictionary\n4. returns word with placed stress\n\n## Updating the default exception dictionary\n\nThe default exception dictionary is based on the \"Grammatical Dictionary\" by A. A. Zaliznyak. To update it, you need to download the latest version from http://odict.ru/ (you need a dictionary without word forms) and run:\n\n```python\npython3 convert_zaliznyak_to_exception_dictionary.py -iz odict.zip -o stressrnn/exception_dictionary.txt\n```\n\n## Datasets\n\nThe repo [contains](https://github.com/Desklop/StressRNN/tree/master/datasets) samples from UD treebanks annotated with word stress for the Russian, Ukranian and Belorusian languages. For more details about the tool see VarDial paper (coming soon).\n\n## Authors\n\n- [Maria Ponomareva](https://github.com/MashaPo) ([RusStress](https://github.com/MashaPo/russtress), ponomarevamawa@gmail.com)\n- [Kirill Milintsevich](https://github.com/501Good) ([RusStress](https://github.com/MashaPo/russtress))\n- [Vladislav Klim](https://github.com/Desklop) ([StressRNN](https://github.com/Desklop/StressRNN), vladsklim@gmail.com, [LinkedIn](https://www.linkedin.com/in/vladklim/))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbklim%2Fstressrnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbklim%2Fstressrnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbklim%2Fstressrnn/lists"}