{ "info": { "author": "fabod", "author_email": "", "bugtrack_url": null, "classifiers": [], "description": "# Orbis quickstart\n\nOrbis is a versatile framework for performing NEL evaluation analyses. It supports standard metrics such as precision, recall and F1-score and visualizes gold standard and annotator results in the context of the annotated document. Color coding the entities allows experts to quickly identify correct and incorrect annotations and the corresponding links to the KB that are also provided by Orbis. Due to the modular pipeline architecture used by Orbis different stages in the evaluation process can be easily modified, replaced or added.\n\nResults of our first Orbis based drill-down analyses efforts were presented at the SEMANTiCS 2018 Conference in Vienna [Odoni, Kuntschik, Bra\u015foveanu, & Weichselbraun, 2018](https://www.sciencedirect.com/science/article/pii/S1877050918316089).\n\n## Prerequisites\nTo be able to develop and run Orbis you will need the following installed and\nconfigured on your system:\n- Python 3.7\n- Python Setup Tools\n- A Linux or Mac OS (Windows is untested)\n\n\n## Install\nTo use Orbis, download and install it from PyPI:\n\n```shell\n $ python3 -m pip install -U orbis-eval['all'] --user\n```\n\nThere are more extras options available but we recommend you use the all option. Only use the other options if you really know what you are doing.\n```\n - all: Install all extras for Orbis. Recommended option\n - all_plugins: Install only all plugins for Orbis.\n - all_addons: Install only all addons for Orbis.\n - aggregation: Install only all aggregation plugins for Orbis.\n - evaluation: Install only all evaluation plugins for Orbis.\n - metrics: Install only all metrics plugins for Orbis.\n - scoring: Install only all scoring plugins for Orbis.\n - storage: Install only all storage plugins for Orbis.\n - \"plugin or addon name\": Install only the specified addon or plugin named.\n```\n\nAlternatively Orbis can be install by cloning the Repo and installing it manually. Plugins and addons must be installed seperatly.\n```shell\n $ git clone https://github.com/orbis-eval/Orbis.git\n $ cd Orbis\n $ python3 setup.py install --user\n # or\n $ python setup.py install --user\n```\n\nDepending on your system and if you have Python 2 and Python 3 installed you either need to use ```python3``` (like on Ubuntu) or maybe just ```python```.\n\nYou will promted to set an orbis user folder. This folder will contain the evaluation run queue, the logs, the corpora and monocle data, the output and the documentation. Default location will be ```orbis-eval``` in the user's home folder. An alternative location can be specified.\n\n## Run\nAfter installation Orbis can be executed by running ```orbis-eval```. The Orbis help can be be called by using ```-h``` (```orbis-eval -h```)\nBefore you can run an evaluation, please install a corpus using the repoman addon ```orbis-addons ```.\n\n## Configure evaluation runs\nOrbis uses yaml files to configure the evaluation runs. These config file are located in the queue folder in the Orbis root directory ```Orbis/queue```.\nExecuting Orbis in test mode will run the yaml configs located in the test folder within the queue folder. These test configs are short evaluation runs for different annotators (AIDA, Babelfly, Recognyze and Spotlight).\n\nA YAML configuration file is divided into the seperate stages of the pipeline:\n\n```yaml\n aggregation:\n service:\n name: aida\n location: web\n input:\n data_set:\n name: rss1\n lenses:\n - 3.5-entity_list_en.txt-14dec-0130pm\n mappings:\n - redirects-v2.json-15dec-1121am\n filters:\n - us_states_list_en-txt-12_jan_28-0913am\n\n evaluation:\n name: binary_classification_evaluation\n\n scoring:\n name: nel_scorer\n condition: overlap\n entities:\n - Person\n - Organization\n - Place\n ignore_empty: False\n\n metrics:\n name: binary_classification_metrics\n\n storage:\n - cache_webservice_results\n```\n\n### Aggregation\nThe aggregation stage of orbis collects all the data needed for an evaluation run. This includes corpus, quering the annotator and mappings, lenses and filters used by monocle. The aggregation settings specify what service, dataset and what lenses, mappings and filters should be used.\n\n```yaml\n aggregation:\n service:\n name: aida\n location: web\n input:\n data_set:\n name: rss1\n lenses:\n - 3.5-entity_list_en.txt-14dec-0130pm\n mappings:\n - redirects-v2.json-15dec-1121am\n filters:\n - us_states_list_en-txt-12_jan_28-0913am\n```\n\nThe service section of the yaml config specifies the name of the web service (annotation service). This should be the same (written the same) as the webservice plugin minus the ```orbis_plugin_aggregation_``` prefix.\n\nLocation specifies where the annotations should come from. If it's set to web, then the aggregation plugin will attemt to query the webservice. If location is set to local, then the local cache (located in ```~/orbis-eval/data/corpora/{corpus_name}/copmuted/{annotator_name}/```) will be used assuming there is a cache to be used.\nIf there is no cache, run the evaluation in web mode and add ```- cache_webservice_results``` to the storage section to build a cache.\n\n``` yaml\n aggregation:\n service:\n name: aida\n location: web\n```\n\n\nThe input section defines what corpus should be used (in the example rss1). The corpora name should be written the same as the corpus folder located in ```~/orbis-eval/data/corpora/```.\nOrbis will locate from there on automatically the corpus texts and the gold standard.\n\n```yaml\n input:\n data_set:\n name: rss1\n lenses:\n - 3.5 -entity_list_en.txt-14dec-0130pm\n mappings:\n - redirects-v2.json-15dec-1121am\n filters:\n - us_states_list_en-txt-12_jan_28-0913am\n```\n\nIf needed, the lenses, mappings and filters can also be specified in the input section. These should be located in ```~/orbis-eval/data/[filters|lenses|mappings]``` and should be specified in the section without the file ending.\n\n\n### Evaluation\nThe evaluator stage evaluates the the annotator results against the gold standard. The evaluation section defines what kind of evaluation should be used. The evaluator should have the same name as the evaluation plugin minus the ```orbis_plugin_evaluation_``` prefix.\n\n```yaml\n evaluation:\n name: binary_classification_evaluation\n```\n\n### Scoring\nThe scoring stage scores the evaluation according to specified conditions. These conditions are preset in the scorer and can be specified in the scoring section as well as what entity types should be scored. If no entity type is defined, all are scored. If one or more entity types are defined, then only those will be scored. Additionally ```ignore_empty``` can be set to define if the scorer should ignore empty annotation results or not.\nThe scorer should have the same name as the scoring plugin minus the ```orbis_plugin_scoring_``` prefix.\n\n```yaml\n scoring:\n name: nel_scorer\n condition: overlap\n entities:\n - Person\n - Organization\n - Place\n ignore_empty: False\n```\n\nCurrently available conditions are:\n\n```\n - simple:\n - same url\n - same entity type\n - same surface form\n\n - strict:\n - same url\n - same entity type\n - same surface form\n - same start\n - same end\n\n - overlap:\n - same url\n - same entity type\n - overlap\n```\n\n### Metrics\nThe metrics stage calculates the metrics to analyze the evaluation. The metric should have the same name as the metrics plugin minus the ```orbis_plugin_metrics_``` prefix.\n\n\n```yaml\n metrics:\n name: binary_classification_metrics\n```\n\n### Storage\nThe storage stage defines what kind of output orbis should create. As allways, the storage should have the same name as the storage plugin minus the ```orbis_plugin_storage_``` prefix.\n\n\n``` yaml\n storage:\n - cache_webservice_results\n - csv_result_list\n - html_pages\n```\n\nMultiple storage options can be chosen and the ones in the example above are the recomended (at the moment working) possibilities.\n\n## Test run\nRunning ```orbis-eval -t``` will run the test files located in ```~/orbis-eval/queue/tests```. It is possible to just take one of these YAML files and modify them to your own needs.\n\n### OrbisAddons\nTo run an Orbis addon Orbis provides a CLI that can be accessed by running ```orbis-addons``` or ```orbis-eval --run-addon```. The menu will guide you to the addons and the addons mostly provide an own menu.\n\nOrbis addons can be called directly by appending the Addon name the orbis-addon command:\n```orbis-addon repoman```\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://orbis-eval.github.io/Orbis/", "keywords": "", "license": "GPL2", "maintainer": "", "maintainer_email": "", "name": "orbis-eval", "package_url": "https://pypi.org/project/orbis-eval/", "platform": "", "project_url": "https://pypi.org/project/orbis-eval/", "project_urls": { "Homepage": "https://orbis-eval.github.io/Orbis/" }, "release_url": "https://pypi.org/project/orbis-eval/2.2.2/", "requires_dist": [ "pyyaml (>=4.2b1)", "orbis-plugin-aggregation-aida ; extra == 'aggregation'", "orbis-plugin-aggregation-babelfly ; extra == 'aggregation'", "orbis-plugin-aggregation-dbpedia-entity-types ; extra == 'aggregation'", "orbis-plugin-aggregation-gold-gs ; extra == 'aggregation'", "orbis-plugin-aggregation-local-cache ; extra == 'aggregation'", "orbis-plugin-aggregation-monocle ; extra == 'aggregation'", "orbis-plugin-aggregation-serial-corpus ; extra == 'aggregation'", "orbis-plugin-aggregation-spotlight ; extra == 'aggregation'", "orbis-plugin-aggregation-aida ; extra == 'aida'", "orbis-addon-repoman ; extra == 'all'", "orbis-plugin-aggregation-aida ; extra == 'all'", "orbis-plugin-aggregation-babelfly ; extra == 'all'", "orbis-plugin-aggregation-dbpedia-entity-types ; extra == 'all'", "orbis-plugin-aggregation-gold-gs ; extra == 'all'", "orbis-plugin-aggregation-local-cache ; extra == 'all'", "orbis-plugin-aggregation-monocle ; extra == 'all'", "orbis-plugin-aggregation-serial-corpus ; extra == 'all'", "orbis-plugin-aggregation-spotlight ; extra == 'all'", "orbis-plugin-evaluation-binary-classification-evaluation ; extra == 'all'", "orbis-plugin-metrics-binary-classification-metrics ; extra == 'all'", "orbis-plugin-scoring-nel-scorer ; extra == 'all'", "orbis-plugin-storage-cache-webservice-results ; extra == 'all'", "orbis-plugin-storage-csv-result-list ; extra == 'all'", "orbis-plugin-storage-html-pages ; extra == 'all'", "orbis-addon-repoman ; extra == 'all_addons'", "orbis-plugin-aggregation-aida ; extra == 'all_plugins'", "orbis-plugin-aggregation-babelfly ; extra == 'all_plugins'", "orbis-plugin-aggregation-dbpedia-entity-types ; extra == 'all_plugins'", "orbis-plugin-aggregation-gold-gs ; extra == 'all_plugins'", "orbis-plugin-aggregation-local-cache ; extra == 'all_plugins'", "orbis-plugin-aggregation-monocle ; extra == 'all_plugins'", "orbis-plugin-aggregation-serial-corpus ; extra == 'all_plugins'", "orbis-plugin-aggregation-spotlight ; extra == 'all_plugins'", "orbis-plugin-evaluation-binary-classification-evaluation ; extra == 'all_plugins'", "orbis-plugin-metrics-binary-classification-metrics ; extra == 'all_plugins'", "orbis-plugin-scoring-nel-scorer ; extra == 'all_plugins'", "orbis-plugin-storage-cache-webservice-results ; extra == 'all_plugins'", "orbis-plugin-storage-csv-result-list ; extra == 'all_plugins'", "orbis-plugin-storage-html-pages ; extra == 'all_plugins'", "orbis-plugin-aggregation-babelfly ; extra == 'babelfly'", "orbis-plugin-evaluation-binary-classification-evaluation ; extra == 'binary_classification_evaluation'", "orbis-plugin-metrics-binary-classification-metrics ; extra == 'binary_classification_metrics'", "orbis-plugin-storage-cache-webservice-results ; extra == 'cache_webservice_results'", "orbis-plugin-storage-csv-result-list ; extra == 'csv_result_list'", "orbis-plugin-aggregation-dbpedia-entity-types ; extra == 'dbpedia_entity_types'", "orbis-plugin-evaluation-binary-classification-evaluation ; extra == 'evaluation'", "orbis-plugin-aggregation-gold-gs ; extra == 'gold_gs'", "orbis-plugin-storage-html-pages ; extra == 'html_pages'", "orbis-plugin-aggregation-local-cache ; extra == 'local_cache'", "orbis-plugin-metrics-binary-classification-metrics ; extra == 'metrics'", "orbis-plugin-aggregation-monocle ; extra == 'monocle'", "orbis-plugin-scoring-nel-scorer ; extra == 'nel_scorer'", "orbis-addon-repoman ; extra == 'repoman'", "orbis-plugin-scoring-nel-scorer ; extra == 'scoring'", "orbis-plugin-aggregation-serial-corpus ; extra == 'serial_corpus'", "orbis-plugin-aggregation-spotlight ; extra == 'spotlight'", "orbis-plugin-storage-cache-webservice-results ; extra == 'storage'", "orbis-plugin-storage-csv-result-list ; extra == 'storage'", "orbis-plugin-storage-html-pages ; extra == 'storage'" ], "requires_python": ">3.6", "summary": "An Extendable Evaluation Pipeline for Named Entity Drill-Down Analysis", "version": "2.2.2" }, "last_serial": 5736403, "releases": { "2.1.1": [ { "comment_text": "", "digests": { "md5": "d06b69bcfd553b3cb57d116de2bf87ef", "sha256": "6fefab8ced1f70b62bc51584ed558a5e01fe5a34dbafcbbcecb4ccc6e6f109fb" }, "downloads": -1, "filename": "orbis_eval-2.1.1-py3-none-any.whl", "has_sig": false, "md5_digest": "d06b69bcfd553b3cb57d116de2bf87ef", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 69272, "upload_time": "2019-07-10T09:26:01", "url": "https://files.pythonhosted.org/packages/c0/e9/ff23bbdbf5839159305208a3096e2e7fc8dd5d3617c7e8e3182abd23f3f8/orbis_eval-2.1.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "ac713a27cc30009243f80d26ce418488", "sha256": "cc1d33e6725cb3ba118ab8d2b5808beb054ca3143cd43906ba555792fd1ef36f" }, "downloads": -1, "filename": "orbis_eval-2.1.1.tar.gz", "has_sig": false, "md5_digest": "ac713a27cc30009243f80d26ce418488", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 60534, "upload_time": "2019-07-10T09:26:04", "url": "https://files.pythonhosted.org/packages/5b/62/2d75eecbefdabac77576f5e125cd82304f1b14c8971e1c4519b322156917/orbis_eval-2.1.1.tar.gz" } ], "2.1.2": [ { "comment_text": "", "digests": { "md5": "c21fa31dd6d690e49b556eddb8d421da", "sha256": "0872730f3ecb91cf35ac2e474e2fde5c917f646c5a3701523678c5885476c3f1" }, "downloads": -1, "filename": "orbis_eval-2.1.2-py3-none-any.whl", "has_sig": false, "md5_digest": "c21fa31dd6d690e49b556eddb8d421da", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 75235, "upload_time": "2019-07-11T12:33:49", "url": "https://files.pythonhosted.org/packages/2b/76/9a9d026c39bc2478609b6ad0b37620f1bdc943df8192bac550ccd6f670d7/orbis_eval-2.1.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "922837cfc23a1ed1aace61be40c26607", "sha256": "7e491857a3e94d7a3bfc76293c1a097e0462caeca61139af2331814aef7b3a30" }, "downloads": -1, "filename": "orbis_eval-2.1.2.tar.gz", "has_sig": false, "md5_digest": "922837cfc23a1ed1aace61be40c26607", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 62469, "upload_time": "2019-07-11T12:33:52", "url": "https://files.pythonhosted.org/packages/16/70/92882ae9490ef602ab1d3ca51756fafa97d22d4f1ac8b60576708a853220/orbis_eval-2.1.2.tar.gz" } ], "2.1.3.dev1": [ { "comment_text": "", "digests": { "md5": "bbe147b028ceedda1e9ac29ed9f87c64", "sha256": "3486fbe9932dc9e6d559f705539762bdab4ff93f770fe5d02ea1ce8e45e94964" }, "downloads": -1, "filename": "orbis_eval-2.1.3.dev1-py3-none-any.whl", "has_sig": false, "md5_digest": "bbe147b028ceedda1e9ac29ed9f87c64", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 76449, "upload_time": "2019-08-16T12:20:17", "url": "https://files.pythonhosted.org/packages/e4/78/7ce33bd0f62bda74b4a9154cfeeae3ba0b9c75a6ab16b33d29db649653fa/orbis_eval-2.1.3.dev1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "0977242a8c9f5e1945adcd935d132862", "sha256": "f49d4615ab1ace73e19c8303e921827211184f061797dc2c3a3bc07bd4324ea2" }, "downloads": -1, "filename": "orbis_eval-2.1.3.dev1.tar.gz", "has_sig": false, "md5_digest": "0977242a8c9f5e1945adcd935d132862", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 62807, "upload_time": "2019-08-16T12:20:19", "url": "https://files.pythonhosted.org/packages/40/5f/b9db232bbfdf4a99c9700f7737780c7d380e643c0e3a7a4cd06dc5f9a2f9/orbis_eval-2.1.3.dev1.tar.gz" } ], "2.2": [ { "comment_text": "", "digests": { "md5": "b52559d5c74ff1148cd250fb983dc94e", "sha256": "e18162c373f1c68e04e9221469447748f471b0c3e0bfd99cb3adb5f7b213cab1" }, "downloads": -1, "filename": "orbis_eval-2.2-py3-none-any.whl", "has_sig": false, "md5_digest": "b52559d5c74ff1148cd250fb983dc94e", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 75444, "upload_time": "2019-08-23T10:33:42", "url": "https://files.pythonhosted.org/packages/e8/b8/ee041809bb99c5508ef8c746c47adc55de1c51853ef6cc7f6c5c81ecbf06/orbis_eval-2.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "aabab2f7ad097ef8c4e715f5c6d8848a", "sha256": "6b346408b930c733f44d0143a68e91c1f1e11c4611f294442d0d058791683067" }, "downloads": -1, "filename": "orbis_eval-2.2.tar.gz", "has_sig": false, "md5_digest": "aabab2f7ad097ef8c4e715f5c6d8848a", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 62831, "upload_time": "2019-08-23T10:33:45", "url": "https://files.pythonhosted.org/packages/8c/94/11d63f2afdd0e1699eeaca5b604b1d4f0a5acaee348ee8989274a46b1643/orbis_eval-2.2.tar.gz" } ], "2.2.1": [ { "comment_text": "", "digests": { "md5": "cbc4dab6dfd9cb6bb42306b9f6e90f65", "sha256": "951c214f564d6cb7df0827c2656b21a4f8825e164e2adce1dfc0c1eec7eeb376" }, "downloads": -1, "filename": "orbis_eval-2.2.1-py3-none-any.whl", "has_sig": false, "md5_digest": "cbc4dab6dfd9cb6bb42306b9f6e90f65", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 75808, "upload_time": "2019-08-27T11:46:37", "url": "https://files.pythonhosted.org/packages/8a/a0/68c3d196c55113428674a8a998623940eba87f0a9a88b80be7e271b559c1/orbis_eval-2.2.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "bae6b2720caa69e72fa7895b9fb7c7d9", "sha256": "bdc465c444e5b52e923a767509343d225b5898e76be7176a4973aa0413ffee47" }, "downloads": -1, "filename": "orbis_eval-2.2.1.tar.gz", "has_sig": false, "md5_digest": "bae6b2720caa69e72fa7895b9fb7c7d9", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 63149, "upload_time": "2019-08-27T11:46:40", "url": "https://files.pythonhosted.org/packages/b2/9f/118a0388ebff4cb48583fd31613e87069cde75fd29904948a66f094b4e95/orbis_eval-2.2.1.tar.gz" } ], "2.2.2": [ { "comment_text": "", "digests": { "md5": "0aaa345a896f42de46505d814961f7c0", "sha256": "90e5a938125eaf11d596be2ffa163f3ed832f5aeb7d1e5f0414c05f375ed2e94" }, "downloads": -1, "filename": "orbis_eval-2.2.2-py3-none-any.whl", "has_sig": false, "md5_digest": "0aaa345a896f42de46505d814961f7c0", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 75775, "upload_time": "2019-08-27T12:07:52", "url": "https://files.pythonhosted.org/packages/25/75/59123b0c58718ffe9c9d6af2e577873366881ac74cfc10f297cb9673ec8c/orbis_eval-2.2.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "9f0452bf38ba809320c70bdeffdfecd8", "sha256": "557b897706408bdaf1f677e86dabc2e8bbc62ee7d49ffc81c2dc1ab5b12a246a" }, "downloads": -1, "filename": "orbis_eval-2.2.2.tar.gz", "has_sig": false, "md5_digest": "9f0452bf38ba809320c70bdeffdfecd8", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 63144, "upload_time": "2019-08-27T12:07:55", "url": "https://files.pythonhosted.org/packages/93/ec/35079d9acd6d8184ef8878644925c29e7c62838306cb0c4832b9c69db7eb/orbis_eval-2.2.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "0aaa345a896f42de46505d814961f7c0", "sha256": "90e5a938125eaf11d596be2ffa163f3ed832f5aeb7d1e5f0414c05f375ed2e94" }, "downloads": -1, "filename": "orbis_eval-2.2.2-py3-none-any.whl", "has_sig": false, "md5_digest": "0aaa345a896f42de46505d814961f7c0", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">3.6", "size": 75775, "upload_time": "2019-08-27T12:07:52", "url": "https://files.pythonhosted.org/packages/25/75/59123b0c58718ffe9c9d6af2e577873366881ac74cfc10f297cb9673ec8c/orbis_eval-2.2.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "9f0452bf38ba809320c70bdeffdfecd8", "sha256": "557b897706408bdaf1f677e86dabc2e8bbc62ee7d49ffc81c2dc1ab5b12a246a" }, "downloads": -1, "filename": "orbis_eval-2.2.2.tar.gz", "has_sig": false, "md5_digest": "9f0452bf38ba809320c70bdeffdfecd8", "packagetype": "sdist", "python_version": "source", "requires_python": ">3.6", "size": 63144, "upload_time": "2019-08-27T12:07:55", "url": "https://files.pythonhosted.org/packages/93/ec/35079d9acd6d8184ef8878644925c29e7c62838306cb0c4832b9c69db7eb/orbis_eval-2.2.2.tar.gz" } ] }