Initial import
Change-Id: I91c66e3ceb8d17e547f2e96bf273beb7a4b76762
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a81c8ee
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,138 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+# For a library or package, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+# However, in case of collaboration, if having platform-specific dependencies or dependencies
+# having no cross-platform support, pipenv may install dependencies that don't work, or not
+# install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..34958f7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,24 @@
+Copyright (c) 2017, IDS Mannheim
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
\ No newline at end of file
diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..7676228
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,89 @@
+# Python Client Support
+Currently, there is no native KorAP client library for Python, yet.
+With [rpy2](https://rpy2.github.io/), however, you can already use the [KorAP client library for R](https://github.com/KorAP/RKorAPClient) from within Python.
+
+## Using the RKorAPClient from within Python
+### Installing Dependencies
+#### Linux
+```shell script
+#### Debian / Ubuntu
+sudo apt install r-base r-base-dev libcurl4-gnutls-dev libssl-dev libxml2-dev libsodium-dev python3-pip python3-rpy2 python3-pandas
+echo 'install.packages("RKorAPClient", repos="http://cran.rstudio.com/")' | R --vanilla
+pip3 install plotly-express
+
+#### Fedora / CentOS / RHEL
+sudo yum install r-base R-devel libcurl-devel openssl-devel libxml2-devel libsodium-devel python3-pandas
+echo 'install.packages("RKorAPClient", repos="http://cran.rstudio.com/")' | R --vanilla
+pip3 install rpy2 plotly-express
+```
+
+#### Other Operating Systems (currently untested)
+- install the RKorAP client as described in it's [installation section](https://github.com/KorAP/RKorAPClient#installation)
+- install [rpy2](https://rpy2.github.io/)
+ ```shell script
+ pip install rpy2
+ ```
+- install [Plotly Express](https://plotly.com/python/plotly-express/) to run the [examples](examples) with visualizations:
+ ```shell script
+ pip install plotly.express
+ ```
+#### Examples
+#### Frequencies over years and countries
+```python
+import rpy2.robjects.packages as packages
+import rpy2.robjects.pandas2ri as pandas2ri
+import plotly.express as px
+pandas2ri.activate()
+
+QUERY = "Hello World"
+YEARS = range(2010, 2019)
+COUNTRIES = ["DE", "CH"]
+
+RKorAPClient = packages.importr('RKorAPClient')
+kcon = RKorAPClient.KorAPConnection(verbose=True)
+
+vcs = ["textType=/Zeit.*/ & pubPlaceKey=" + c + " & pubDate in " + str(y) for c in COUNTRIES for y in YEARS]
+df = RKorAPClient.ipm(RKorAPClient.frequencyQuery(kcon, QUERY, vcs))
+df['Year'] = [y for c in COUNTRIES for y in YEARS]
+df['Country'] = [c for c in COUNTRIES for y in YEARS]
+
+fig = px.line(df, title=QUERY, x="Year", y="ipm", color="Country",
+ error_y="conf.high", error_y_minus="conf.low")
+fig.show()
+```
+[Frequency per million words of “Hello World“ in DE vs. AT from 2010 to 2018 in newspapers and magazines](figures/hello-world.png)
+
+### Accessed API Services
+By using the KorAPClient you agree to the respective terms of use of the accessed KorAP API services which will be printed upon opening a connection.
+
+## Development and License
+
+**Author**: [Marc Kupietz](http://www1.ids-mannheim.de/zfo/personal/kupietz/)
+
+Copyright (c) 2020, [Leibniz Institute for the German Language](http://www.ids-mannheim.de/), Mannheim, Germany
+
+This package is developed as part of the [KorAP](http://korap.ids-mannheim.de/)
+Corpus Analysis Platform at the Leibniz Institute for German Language
+([IDS](http://www.ids-mannheim.de/)).
+
+It is published under the [BSD-2 License](LICENSE).
+
+## Contributions
+
+Contributions are very welcome!
+
+Your contributions should ideally be committed via our [Gerrit server](https://korap.ids-mannheim.de/gerrit/)
+to facilitate reviewing (see [Gerrit Code Review - A Quick Introduction](https://korap.ids-mannheim.de/gerrit/Documentation/intro-quick.html)
+if you are not familiar with Gerrit). However, we are also happy to accept comments and pull requests
+via GitHub.
+
+Please note that unless you explicitly state otherwise any
+contribution intentionally submitted for inclusion into this software shall –
+as this software itself – be under the [BSD-2 License](LICENSE).
+
+## References
+
+- Kupietz, Marc / Margaretha, Eliza / Diewald, Nils / Lüngen, Harald / Fankhauser, Peter (2019): [What’s New in EuReCo? Interoperability, Comparable Corpora, Licensing](https://nbn-resolving.org/urn:nbn:de:bsz:mh39-90261). In: Bański, Piotr/Barbaresi, Adrien/Biber, Hanno/Breiteneder, Evelyn/Clematide, Simon/Kupietz, Marc/Lüngen, Harald/Iliadi, Caroline (eds.): [*Proceedings of the International Corpus Linguistics Conference 2019 Workshop "Challenges in the Management of Large Corpora (CMLC-7)"*](https://ids-pub.bsz-bw.de/solrsearch/index/search/searchtype/collection/id/21038), 22nd of July Mannheim: Leibniz-Institut für Deutsche Sprache, 33-39.
+
+- Kupietz, Marc / Diewald, Nils / Margaretha, Eliza (forthcoming): RKorAPClient: An R package for accessing the German Reference Corpus DeReKo via KorAP. In: Proceedings of the Twelfth International Conference on Language Resources and Evaluation (LREC 2020). Marseille/Paris: European Language Resources Association (ELRA).
+
diff --git a/examples/hello_world.py b/examples/hello_world.py
new file mode 100755
index 0000000..1309f3b
--- /dev/null
+++ b/examples/hello_world.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+import rpy2.robjects.packages as packages
+import rpy2.robjects.pandas2ri as pandas2ri
+import plotly.express as px
+pandas2ri.activate()
+
+QUERY = "Hello World"
+YEARS = range(2010, 2019)
+COUNTRIES = ["DE", "CH"]
+
+RKorAPClient = packages.importr('RKorAPClient')
+kcon = RKorAPClient.KorAPConnection(verbose=True)
+
+vcs = ["textType=/Zeit.*/ & pubPlaceKey=" + c + " & pubDate in " + str(y) for c in COUNTRIES for y in YEARS]
+df = RKorAPClient.ipm(RKorAPClient.frequencyQuery(kcon, QUERY, vcs))
+df['Year'] = [y for c in COUNTRIES for y in YEARS]
+df['Country'] = [c for c in COUNTRIES for y in YEARS]
+
+fig = px.line(df, title=QUERY, x="Year", y="ipm", color="Country",
+ error_y="conf.high", error_y_minus="conf.low")
+fig.show()
diff --git a/figures/hello-world.png b/figures/hello-world.png
new file mode 100644
index 0000000..6e2f27d
--- /dev/null
+++ b/figures/hello-world.png
Binary files differ
