| Name | pyBKTR JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Python implementation of the Scalable Spatiotemporally Varying Coefficient Modelling with Bayesian Kernelized Tensor Regression |
| upload_time | 2024-08-21 02:57:43 |
| maintainer | None |
| docs_url | None |
| author | Mengying Lei, Aurelie Labbe, Lijun Sun |
| requires_python | <4,>=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pyBKTR
## Intro
This project is a *Python* implementation of the BKTR algorithm presented by Mengying Lei, Aurélie Labbe & Lijun Sun (2023).
The article presenting the algorithm can be found [here](https://arxiv.org/abs/2109.00046).
BKTR stands for Scalable Spatiotemporally Varying Coefficient Modelling with Bayesian Kernelized Tensor Regression.
It allows to model spatiotemporally varying coefficients using a Bayesian framework.
We implemented the algorithm and more in a *Python* package that uses [PyTorch](https://pytorch.org/) as a tensor operation backend.
For information, an alternative *R* implementation of the algorithm can be found [here](https://github.com/julien-hec/BKTR). The *Python* implementation is synchronized with this repository and development is done in parallel. The synchronization of features will be done at a subrevision level (x.y.0).
An article presenting the *R* package in details is currently in preparation and should be available soon. The documentation for the *R* package is a work in progress and will be made available in the coming weeks.
## Installation
### Install from PyPI
The package is available on PyPI and can be installed using pip:
```bash
pip install pyBKTR
```
### Install from source
To install the package from source and use the latest release, you can clone the repository and install it using pip and the repository url:
```bash
pip install git+https://github.com/julien-hec/pyBKTR.git
```
### Notes
If you obtain an error message when installing the package, it may be due to the installation of the `torch` package.
The `torch` package is a dependency for the `pyBKTR` package and there is a good chance that it could be responsible for encountered installation errors.
Because of its ability to perform tensor operations on the GPU, it can sometimes be more complicated to install than other Python packages.
Some of the most common problems are related to the CUDA version, the GPU driver version, that can be incompatible with a specific version of `torch`.
We provide some guidance for the installation of `torch` below.
#### Installing torch alone
A simple way to see if `pyBKTR` installation problems come from the `torch` installation is to try to install torch alone first:
```bash
pip install torch
```
#### More information on torch installation
If you obtain an error message, we encourage you to refer to the [pytorch installation documentation](https://pytorch.org/get-started/locally/).
This documentation provides a lot of information on how to install `torch` on different platforms and with different configurations.
It allows for example to install `torch` with or without GPU support if you have GPU drivers issues.
#### Getting started with Colab
If you want to get started quickly with `pyBKTR` on Google Colab, you can use the following examples
- BKTR on Light BIXI Data with CPU ([Colab](https://colab.research.google.com/drive/13er8x9GfD4IsERb1WbbkTsk3UEpOEqdK?usp=sharing) & [GitHub](https://github.com/julien-hec/bktr-examples/blob/main/BKTR-installations/Python_BKTR_CPU.ipynb))
- BKTR on Light BIXI Data with GPU ([Colab](https://colab.research.google.com/drive/1eXlGv1gATiJbhvwsa_ro2h5o1aD38sxa?usp=sharing) & [GitHub](https://github.com/julien-hec/bktr-examples/blob/main/BKTR-installations/Python_BKTR_GPU.ipynb))
## Simple Example
To verify that everything is running smooth you can try to run a BKTR regression on the BIXI data presented in the package. (The data is already preloaded in the package in the `BixiData` class)
The following code will run a BKTR regression using sensible defaults on the BIXI data and print a summary of the results. To use a subset of the BIXI dataset as a simple example, we can also use the `is_light` argument during the `BixiData` initialization to only load a subset of the data (25 stations and 50 days).
```python
from pyBKTR.bktr import BKTRRegressor
from pyBKTR.examples.bixi import BixiData
bixi_data = BixiData(is_light=True)
bktr_regressor = BKTRRegressor(
data_df=bixi_data.data_df,
spatial_positions_df=bixi_data.spatial_positions_df,
temporal_positions_df=bixi_data.temporal_positions_df,
burn_in_iter=200,
sampling_iter=200
)
bktr_regressor.mcmc_sampling()
print(bktr_regressor.summary)
```
## Contributing
Contributions are welcome. Do not hesitate to open an issue or a pull request if you encounter any problem or have any suggestion.
## Dev Notes
### Dev environment setup
If you wish to contribute to this project, we strongly recommend you to use the precommit setup created in the project. To get started, simply follow these instructions.
First, install the project locally with the development resources. If you use zsh, you might need to put single quotes around the path `'.[dev]'`
```bash
pip install .[dev]
```
Then, install the git hook scripts.
```bash
pre-commit install
```
Finally, everything should work fine if when run the pre-commit hooks.
```bash
pre-commit run --all-files
```
### Documentation Generation
You should already have the dev environment setup
Pandoc needs to be installed on your local machine, follow the instructions in the following link
https://pandoc.org/installing.html
From the docs folder run the following line to regenerate the static doc
```bash
sphinx-apidoc -f -o . .
```
then
```bash
make html
```
### Publish to PyPI
First build the package locally
```bash
python3 -m pip install --upgrade build
python3 -m build
```
Then upload to PyPI
```bash
python3 -m pip install --upgrade twine
twine upload dist/*
```
Using the proper credentials, the package should be uploaded to PyPI and be available for download.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyBKTR",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Mengying Lei, Aurelie Labbe, Lijun Sun",
"author_email": "Julien Lanthier <julien.lanthier@hec.ca>",
"download_url": "https://files.pythonhosted.org/packages/50/43/2504874725b88f47b415523cf02757427a022e57646ee178486226c7b13f/pybktr-0.2.0.tar.gz",
"platform": null,
"description": "# pyBKTR\n\n## Intro\nThis project is a *Python* implementation of the BKTR algorithm presented by Mengying Lei, Aur\u00e9lie Labbe & Lijun Sun (2023).\nThe article presenting the algorithm can be found [here](https://arxiv.org/abs/2109.00046).\n\nBKTR stands for Scalable Spatiotemporally Varying Coefficient Modelling with Bayesian Kernelized Tensor Regression.\nIt allows to model spatiotemporally varying coefficients using a Bayesian framework.\nWe implemented the algorithm and more in a *Python* package that uses [PyTorch](https://pytorch.org/) as a tensor operation backend.\n\nFor information, an alternative *R* implementation of the algorithm can be found [here](https://github.com/julien-hec/BKTR). The *Python* implementation is synchronized with this repository and development is done in parallel. The synchronization of features will be done at a subrevision level (x.y.0).\n\nAn article presenting the *R* package in details is currently in preparation and should be available soon. The documentation for the *R* package is a work in progress and will be made available in the coming weeks.\n\n## Installation\n\n### Install from PyPI\nThe package is available on PyPI and can be installed using pip:\n```bash\npip install pyBKTR\n```\n\n### Install from source\nTo install the package from source and use the latest release, you can clone the repository and install it using pip and the repository url:\n```bash\npip install git+https://github.com/julien-hec/pyBKTR.git\n```\n\n### Notes\nIf you obtain an error message when installing the package, it may be due to the installation of the `torch` package.\nThe `torch` package is a dependency for the `pyBKTR` package and there is a good chance that it could be responsible for encountered installation errors.\nBecause of its ability to perform tensor operations on the GPU, it can sometimes be more complicated to install than other Python packages.\nSome of the most common problems are related to the CUDA version, the GPU driver version, that can be incompatible with a specific version of `torch`.\nWe provide some guidance for the installation of `torch` below.\n\n#### Installing torch alone\nA simple way to see if `pyBKTR` installation problems come from the `torch` installation is to try to install torch alone first:\n```bash\npip install torch\n```\n\n#### More information on torch installation\nIf you obtain an error message, we encourage you to refer to the [pytorch installation documentation](https://pytorch.org/get-started/locally/).\nThis documentation provides a lot of information on how to install `torch` on different platforms and with different configurations.\nIt allows for example to install `torch` with or without GPU support if you have GPU drivers issues.\n\n\n#### Getting started with Colab\nIf you want to get started quickly with `pyBKTR` on Google Colab, you can use the following examples\n- BKTR on Light BIXI Data with CPU ([Colab](https://colab.research.google.com/drive/13er8x9GfD4IsERb1WbbkTsk3UEpOEqdK?usp=sharing) & [GitHub](https://github.com/julien-hec/bktr-examples/blob/main/BKTR-installations/Python_BKTR_CPU.ipynb))\n- BKTR on Light BIXI Data with GPU ([Colab](https://colab.research.google.com/drive/1eXlGv1gATiJbhvwsa_ro2h5o1aD38sxa?usp=sharing) & [GitHub](https://github.com/julien-hec/bktr-examples/blob/main/BKTR-installations/Python_BKTR_GPU.ipynb))\n\n\n## Simple Example\nTo verify that everything is running smooth you can try to run a BKTR regression on the BIXI data presented in the package. (The data is already preloaded in the package in the `BixiData` class)\n\nThe following code will run a BKTR regression using sensible defaults on the BIXI data and print a summary of the results. To use a subset of the BIXI dataset as a simple example, we can also use the `is_light` argument during the `BixiData` initialization to only load a subset of the data (25 stations and 50 days).\n\n```python\nfrom pyBKTR.bktr import BKTRRegressor\nfrom pyBKTR.examples.bixi import BixiData\n\nbixi_data = BixiData(is_light=True)\nbktr_regressor = BKTRRegressor(\n data_df=bixi_data.data_df,\n spatial_positions_df=bixi_data.spatial_positions_df,\n temporal_positions_df=bixi_data.temporal_positions_df,\n burn_in_iter=200,\n sampling_iter=200\n)\nbktr_regressor.mcmc_sampling()\nprint(bktr_regressor.summary)\n```\n\n## Contributing\nContributions are welcome. Do not hesitate to open an issue or a pull request if you encounter any problem or have any suggestion.\n\n\n## Dev Notes\n### Dev environment setup\nIf you wish to contribute to this project, we strongly recommend you to use the precommit setup created in the project. To get started, simply follow these instructions.\n\nFirst, install the project locally with the development resources. If you use zsh, you might need to put single quotes around the path `'.[dev]'`\n```bash\npip install .[dev]\n```\n\nThen, install the git hook scripts.\n```bash\npre-commit install\n```\n\nFinally, everything should work fine if when run the pre-commit hooks.\n```bash\npre-commit run --all-files\n```\n\n### Documentation Generation\nYou should already have the dev environment setup\n\nPandoc needs to be installed on your local machine, follow the instructions in the following link\nhttps://pandoc.org/installing.html\n\n\nFrom the docs folder run the following line to regenerate the static doc\n```bash\nsphinx-apidoc -f -o . .\n```\nthen\n```bash\nmake html\n```\n\n### Publish to PyPI\nFirst build the package locally\n```bash\npython3 -m pip install --upgrade build\npython3 -m build\n```\n\nThen upload to PyPI\n```bash\npython3 -m pip install --upgrade twine\ntwine upload dist/*\n```\nUsing the proper credentials, the package should be uploaded to PyPI and be available for download.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python implementation of the Scalable Spatiotemporally Varying Coefficient Modelling with Bayesian Kernelized Tensor Regression",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/julien-hec/pyBKTR/issues",
"Homepage": "https://github.com/julien-hec/pyBKTR"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f6ec4f2e0ec4e90a79b4f51d01df943afb6bc7ab6e86aaa46fac60a6b86a8a4",
"md5": "4cbc89502a1972a65ef5dbd7310adc51",
"sha256": "2ae02e7f5e84be0ee180b1c366402d563ef340bf2831845cedaf75bf020e46c0"
},
"downloads": -1,
"filename": "pyBKTR-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4cbc89502a1972a65ef5dbd7310adc51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 221924,
"upload_time": "2024-08-21T02:57:41",
"upload_time_iso_8601": "2024-08-21T02:57:41.010406Z",
"url": "https://files.pythonhosted.org/packages/7f/6e/c4f2e0ec4e90a79b4f51d01df943afb6bc7ab6e86aaa46fac60a6b86a8a4/pyBKTR-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50432504874725b88f47b415523cf02757427a022e57646ee178486226c7b13f",
"md5": "7c5d54f1c08432f1e47574ab80795079",
"sha256": "0fc0be9fd6de32cfd83e45461433d77c583a1f92d7874d612fdcee09bdae71d3"
},
"downloads": -1,
"filename": "pybktr-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7c5d54f1c08432f1e47574ab80795079",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 213835,
"upload_time": "2024-08-21T02:57:43",
"upload_time_iso_8601": "2024-08-21T02:57:43.478293Z",
"url": "https://files.pythonhosted.org/packages/50/43/2504874725b88f47b415523cf02757427a022e57646ee178486226c7b13f/pybktr-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-21 02:57:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "julien-hec",
"github_project": "pyBKTR",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pybktr"
}
