# TorchVineCopuLib
[](https://app.codacy.com/gh/TY-Cheng/torchvinecopulib/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)
[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/static.yml)
[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)
[](https://zenodo.org/doi/10.5281/zenodo.10836953)
Yet another vine copula package, using [PyTorch](https://pytorch.org/get-started/locally/).
- C/D/R-Vine full-simulation/ quantile-regression/ conditional-simulation, all in one package
- Flexible simulation workflow for experienced users
- Vectorized tensor computation with GPU (`device='cuda'`) support
- Shorter runtimes for higher dimension simulations
- Decoupled dataclasses and factory methods
- Pure `Python` library, inspired by and tested against [pyvinecopulib](https://github.com/vinecopulib/pyvinecopulib/) on Windows, Linux, MacOS
- IO and visualization support
## Dependencies
```toml
# inside the `./pyproject.toml` file;
numpy = "*"
python = "^3.10"
scipy = "*"
# optional to facilitate customization
torch = { version = "^2", optional = true }
```
For [PyTorch](https://pytorch.org/get-started/locally/) with `cuda` support on Windows:
```bash
pip install torch --index-url https://download.pytorch.org/whl/cu121 --force-reinstall
# check cuda availability
python -c "import torch; print(torch.cuda.is_available())"
```
> [!TIP]
> macOS users should set `device='cpu'` at this stage, for using `device='mps'` won't support `dtype=torch.float64`.
## Installation
- By `pip` from [`PyPI`](https://pypi.org/project/torchvinecopulib/):
```bash
pip install torchvinecopulib torch
```
- Or with full drawing and bivariate dependency metric support:
```bash
pip install torchvinecopulib torch matplotlib pot scikit-learn
```
- Or `pip` from `./dist/*.whl` or `./dist/*.tar.gz` in this repo.
Need to use proper file name.
```bash
# inside project root folder
pip install ./dist/torchvinecopulib-2024.10.1-py3-none-any.whl
# or
pip install ./dist/torchvinecopulib-2024.10.1.tar.gz
```
### (Optional) [Poetry](https://python-poetry.org/docs/) for Dependency Management and Packaging
After `git clone https://github.com/TY-Cheng/torchvinecopulib.git`, `cd` into the project root where [`pyproject.toml`](https://github.com/TY-Cheng/torchvinecopulib/blob/main/pyproject.toml) exists,
```bash
# inside project root folder
poetry lock && poetry install -E dev_cpu --with dev_cpu --sync
# or
poetry lock && poetry install -E dev_cuda --with dev_cuda --sync
```
## Examples
Visit the [`./examples/`](https://github.com/TY-Cheng/torchvinecopulib/tree/main/examples) folder for `.ipynb` Jupyter notebooks.
## Documentation
- Visit [GitHub Pages website](https://ty-cheng.github.io/torchvinecopulib/)
- Or visit [html-preview.github.io](https://html-preview.github.io/?url=https%3A%2F%2Fgithub.com%2FTY-Cheng%2Ftorchvinecopulib%2Fblob%2Fmain%2Fdocs%2F_build%2Fhtml%2Findex.html)
- Or build by yourself (need [`Sphinx`](https://github.com/sphinx-doc/sphinx), theme [`furo`](https://github.com/pradyunsg/furo) and [the GNU `make`](https://www.gnu.org/software/make/))
```bash
# inside project root folder
sphinx-apidoc -o ./docs ./torchvinecopulib && cd ./docs && make html && cd ..
```
## Tests
> [!TIP]
> the `./tests/test_vinecop.py` may take longer without `'cuda'`
```python
# inside project root folder
python -m pytest ./tests
# coverage report
coverage run -m pytest ./tests && coverage html
```
## TODO
- more (non-parametric) `bicop` class in `torch`
- port to TensorFlow Probability for `cuda`-compatible [Student's t cdf/ppf](https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/StudentT)
## Contributing
We welcome contributions, whether it's a bug report, feature suggestion, code contribution, or documentation improvement.
- If you encounter any issues with the project or have ideas for new features, please [open an issue](https://github.com/TY-Cheng/torchvinecopulib/issues/new) on GitHub or [privately email us](mailto:cty120120@gmail.com). Make sure to include detailed information about the problem or feature request, including steps to reproduce for bugs.
### Code Contributions
1. Fork the repository and create a new branch from the `main` branch.
2. Make your changes and ensure they adhere to the project's coding style and conventions.
3. Write tests for any new functionality and ensure existing tests pass.
4. Commit your changes with clear and descriptive commit messages.
5. Push your changes to your fork and submit a pull request to the `main` branch of the original repository.
### Pull Request Guidelines
- Keep pull requests focused on addressing a single issue or feature.
- Include a clear and descriptive title and description for your pull request.
- Make sure all tests pass before submitting the pull request.
- If your pull request addresses an open issue, reference the issue number in the description using the syntax `#issue_number`.
- [in-place ops can be slower](https://discuss.pytorch.org/t/are-inplace-operations-faster/61209/4)
- [torch.jit.script can be slower](https://discuss.pytorch.org/t/why-is-torch-jit-script-slower/120131/6)
## License
> Copyright (C) 2024- Tuoyuan Cheng, Kan Chen
>
> This file is part of torchvinecopulib.
> torchvinecopulib is free software: you can redistribute it and/or modify
> it under the terms of the GNU General Public License as published by
> the Free Software Foundation, either version 3 of the License, or
> (at your option) any later version.
>
> torchvinecopulib 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 General Public License for more details.
>
> You should have received a copy of the GNU General Public License
> along with torchvinecopulib. If not, see <http://www.gnu.org/licenses/>.
Raw data
{
"_id": null,
"home_page": "https://github.com/TY-Cheng/torchvinecopulib",
"name": "torchvinecopulib",
"maintainer": "Xiaosheng You",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "e1204754@u.nus.edu",
"keywords": "vine copula, copula, torch",
"author": "Tuoyuan Cheng",
"author_email": "tuoyuan.cheng@nus.edu.sg",
"download_url": "https://files.pythonhosted.org/packages/49/a9/b80f7079f6ebb6c08344f140a4c3a50d3b1692ac0db0144a72f8a3254b7e/torchvinecopulib-2024.10.1.tar.gz",
"platform": null,
"description": "# TorchVineCopuLib\n\n[](https://app.codacy.com/gh/TY-Cheng/torchvinecopulib/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n[](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)\n[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)\n[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/static.yml)\n\n\n[](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)\n\n\n\n[](https://zenodo.org/doi/10.5281/zenodo.10836953)\n\nYet another vine copula package, using [PyTorch](https://pytorch.org/get-started/locally/).\n\n- C/D/R-Vine full-simulation/ quantile-regression/ conditional-simulation, all in one package\n - Flexible simulation workflow for experienced users\n- Vectorized tensor computation with GPU (`device='cuda'`) support\n- Shorter runtimes for higher dimension simulations\n- Decoupled dataclasses and factory methods\n- Pure `Python` library, inspired by and tested against [pyvinecopulib](https://github.com/vinecopulib/pyvinecopulib/) on Windows, Linux, MacOS\n- IO and visualization support\n\n## Dependencies\n\n```toml\n# inside the `./pyproject.toml` file;\nnumpy = \"*\"\npython = \"^3.10\"\nscipy = \"*\"\n# optional to facilitate customization\ntorch = { version = \"^2\", optional = true }\n```\n\nFor [PyTorch](https://pytorch.org/get-started/locally/) with `cuda` support on Windows:\n\n```bash\npip install torch --index-url https://download.pytorch.org/whl/cu121 --force-reinstall\n# check cuda availability\npython -c \"import torch; print(torch.cuda.is_available())\"\n```\n\n> [!TIP]\n> macOS users should set `device='cpu'` at this stage, for using `device='mps'` won't support `dtype=torch.float64`.\n\n## Installation\n\n- By `pip` from [`PyPI`](https://pypi.org/project/torchvinecopulib/):\n\n```bash\npip install torchvinecopulib torch\n```\n\n- Or with full drawing and bivariate dependency metric support:\n\n```bash\npip install torchvinecopulib torch matplotlib pot scikit-learn\n```\n\n- Or `pip` from `./dist/*.whl` or `./dist/*.tar.gz` in this repo.\n Need to use proper file name.\n\n```bash\n# inside project root folder\npip install ./dist/torchvinecopulib-2024.10.1-py3-none-any.whl\n# or\npip install ./dist/torchvinecopulib-2024.10.1.tar.gz\n```\n\n### (Optional) [Poetry](https://python-poetry.org/docs/) for Dependency Management and Packaging\n\nAfter `git clone https://github.com/TY-Cheng/torchvinecopulib.git`, `cd` into the project root where [`pyproject.toml`](https://github.com/TY-Cheng/torchvinecopulib/blob/main/pyproject.toml) exists,\n\n```bash\n# inside project root folder\npoetry lock && poetry install -E dev_cpu --with dev_cpu --sync\n# or\npoetry lock && poetry install -E dev_cuda --with dev_cuda --sync\n```\n\n## Examples\n\nVisit the [`./examples/`](https://github.com/TY-Cheng/torchvinecopulib/tree/main/examples) folder for `.ipynb` Jupyter notebooks.\n\n## Documentation\n\n- Visit [GitHub Pages website](https://ty-cheng.github.io/torchvinecopulib/)\n\n- Or visit [html-preview.github.io](https://html-preview.github.io/?url=https%3A%2F%2Fgithub.com%2FTY-Cheng%2Ftorchvinecopulib%2Fblob%2Fmain%2Fdocs%2F_build%2Fhtml%2Findex.html)\n\n- Or build by yourself (need [`Sphinx`](https://github.com/sphinx-doc/sphinx), theme [`furo`](https://github.com/pradyunsg/furo) and [the GNU `make`](https://www.gnu.org/software/make/))\n\n```bash\n# inside project root folder\nsphinx-apidoc -o ./docs ./torchvinecopulib && cd ./docs && make html && cd ..\n```\n\n## Tests\n\n> [!TIP]\n> the `./tests/test_vinecop.py` may take longer without `'cuda'`\n\n```python\n# inside project root folder\npython -m pytest ./tests\n# coverage report\ncoverage run -m pytest ./tests && coverage html\n```\n\n## TODO\n\n- more (non-parametric) `bicop` class in `torch`\n- port to TensorFlow Probability for `cuda`-compatible [Student's t cdf/ppf](https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/StudentT)\n\n## Contributing\n\nWe welcome contributions, whether it's a bug report, feature suggestion, code contribution, or documentation improvement.\n\n- If you encounter any issues with the project or have ideas for new features, please [open an issue](https://github.com/TY-Cheng/torchvinecopulib/issues/new) on GitHub or [privately email us](mailto:cty120120@gmail.com). Make sure to include detailed information about the problem or feature request, including steps to reproduce for bugs.\n\n### Code Contributions\n\n1. Fork the repository and create a new branch from the `main` branch.\n2. Make your changes and ensure they adhere to the project's coding style and conventions.\n3. Write tests for any new functionality and ensure existing tests pass.\n4. Commit your changes with clear and descriptive commit messages.\n5. Push your changes to your fork and submit a pull request to the `main` branch of the original repository.\n\n### Pull Request Guidelines\n\n- Keep pull requests focused on addressing a single issue or feature.\n- Include a clear and descriptive title and description for your pull request.\n- Make sure all tests pass before submitting the pull request.\n- If your pull request addresses an open issue, reference the issue number in the description using the syntax `#issue_number`.\n- [in-place ops can be slower](https://discuss.pytorch.org/t/are-inplace-operations-faster/61209/4)\n- [torch.jit.script can be slower](https://discuss.pytorch.org/t/why-is-torch-jit-script-slower/120131/6)\n\n## License\n\n> Copyright (C) 2024- Tuoyuan Cheng, Kan Chen\n>\n> This file is part of torchvinecopulib.\n> torchvinecopulib is free software: you can redistribute it and/or modify\n> it under the terms of the GNU General Public License as published by\n> the Free Software Foundation, either version 3 of the License, or\n> (at your option) any later version.\n>\n> torchvinecopulib is distributed in the hope that it will be useful,\n> but WITHOUT ANY WARRANTY; without even the implied warranty of\n> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n> GNU General Public License for more details.\n>\n> You should have received a copy of the GNU General Public License\n> along with torchvinecopulib. If not, see <http://www.gnu.org/licenses/>.\n",
"bugtrack_url": null,
"license": "GNU GPLv3",
"summary": "yet another vine copula library for PyTorch.",
"version": "2024.10.1",
"project_urls": {
"Bug Tracker": "https://github.com/TY-Cheng/torchvinecopulib/issues/new",
"Documentation": "https://ty-cheng.github.io/torchvinecopulib/",
"Homepage": "https://github.com/TY-Cheng/torchvinecopulib",
"Repository": "https://github.com/TY-Cheng/torchvinecopulib"
},
"split_keywords": [
"vine copula",
" copula",
" torch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f13330ff2953d55b8c9c3e2700dc31c3ba90458e3c8ca0636ad33110624dec13",
"md5": "a27863a7164db1c413a2554284e82a4a",
"sha256": "f60d20f9ce34d5a3d6916fb3858c31fbf67289573eccd114e7461d3a3a59e377"
},
"downloads": -1,
"filename": "torchvinecopulib-2024.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a27863a7164db1c413a2554284e82a4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 56984,
"upload_time": "2024-10-16T13:13:49",
"upload_time_iso_8601": "2024-10-16T13:13:49.401674Z",
"url": "https://files.pythonhosted.org/packages/f1/33/30ff2953d55b8c9c3e2700dc31c3ba90458e3c8ca0636ad33110624dec13/torchvinecopulib-2024.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49a9b80f7079f6ebb6c08344f140a4c3a50d3b1692ac0db0144a72f8a3254b7e",
"md5": "71dc27bd2695449db685d5d0519a7a04",
"sha256": "21bfc6a5aaec1856800185d33cbe1cef2b2d041e6b17b5d1b99483f6deafab46"
},
"downloads": -1,
"filename": "torchvinecopulib-2024.10.1.tar.gz",
"has_sig": false,
"md5_digest": "71dc27bd2695449db685d5d0519a7a04",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 52361,
"upload_time": "2024-10-16T13:13:51",
"upload_time_iso_8601": "2024-10-16T13:13:51.635848Z",
"url": "https://files.pythonhosted.org/packages/49/a9/b80f7079f6ebb6c08344f140a4c3a50d3b1692ac0db0144a72f8a3254b7e/torchvinecopulib-2024.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-16 13:13:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TY-Cheng",
"github_project": "torchvinecopulib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torchvinecopulib"
}
JSON
