==========
torchapp
==========
.. image:: https://raw.githubusercontent.com/rbturnbull/torchapp/master/docs/images/torchapp-banner.svg
.. start-badges
|testing badge| |coverage badge| |docs badge| |black badge| |git3moji badge| |torchapp badge|
.. |torchapp badge| image:: https://img.shields.io/badge/MLOpps-torchapp-B1230A.svg
:target: https://rbturnbull.github.io/torchapp/
.. |testing badge| image:: https://github.com/rbturnbull/torchapp/actions/workflows/testing.yml/badge.svg
:target: https://github.com/rbturnbull/torchapp/actions
.. |docs badge| image:: https://github.com/rbturnbull/torchapp/actions/workflows/docs.yml/badge.svg
:target: https://rbturnbull.github.io/torchapp
.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |coverage badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/rbturnbull/506563cd9b49c8126284e34864c862d0/raw/coverage-badge.json
:target: https://rbturnbull.github.io/torchapp/coverage/
.. |git3moji badge| image:: https://img.shields.io/badge/git3moji-%E2%9A%A1%EF%B8%8F%F0%9F%90%9B%F0%9F%93%BA%F0%9F%91%AE%F0%9F%94%A4-fffad8.svg
:target: https://robinpokorny.github.io/git3moji/
.. end-badges
A wrapper for PyTorch projects to create easy command-line interfaces and manage hyper-parameter tuning.
Documentation at https://rbturnbull.github.io/torchapp/
.. start-quickstart
Installation
=======================
The software can be installed using ``pip``
.. code-block:: bash
pip install torchapp
To install the latest version from the repository, you can use this command:
.. code-block:: bash
pip install git+https://github.com/rbturnbull/torchapp.git
Writing an App
=======================
Inherit a class from :code:`TorchApp` to make an app. The parent class includes several methods for training and hyper-parameter tuning.
The minimum requirement is that you fill out the dataloaders method and the model method.
The :code:`dataloaders` method requires that you return a fastai Dataloaders object. This is a collection of dataloader objects.
Typically it contains one dataloader for training and another for testing. For more information see https://docs.fast.ai/data.core.html#DataLoaders
You can add parameter values with typing hints in the function signature and these will be automatically added to the train and show_batch methods.
The :code:`model` method requires that you return a pytorch module. Parameters in the function signature will be added to the train method.
Here's an example for doing logistic regression:
.. code-block:: Python
#!/usr/bin/env python3
from pathlib import Path
import pandas as pd
from torch import nn
from fastai.data.block import DataBlock, TransformBlock
from fastai.data.transforms import ColReader, RandomSplitter
import torchapp as ta
from torchapp.blocks import BoolBlock
class LogisticRegressionApp(ta.TorchApp):
"""
Creates a basic app to do logistic regression.
"""
def dataloaders(
self,
csv: Path = ta.Param(help="The path to a CSV file with the data."),
x: str = ta.Param(default="x", help="The column name of the independent variable."),
y: str = ta.Param(default="y", help="The column name of the dependent variable."),
validation_proportion: float = ta.Param(
default=0.2, help="The proportion of the dataset to use for validation."
),
batch_size: int = ta.Param(
default=32,
help="The number of items to use in each batch.",
),
):
datablock = DataBlock(
blocks=[TransformBlock, BoolBlock],
get_x=ColReader(x),
get_y=ColReader(y),
splitter=RandomSplitter(validation_proportion),
)
df = pd.read_csv(csv)
return datablock.dataloaders(df, bs=batch_size)
def model(self) -> nn.Module:
"""Builds a simple logistic regression model."""
return nn.Linear(in_features=1, out_features=1, bias=True)
def loss_func(self):
return nn.BCEWithLogitsLoss()
if __name__ == "__main__":
LogisticRegressionApp.main()
Programmatic Interface
=======================
To use the app in Python, simply instantiate it:
.. code-block:: Python
app = LogisticRegressionApp()
Then you can train with the method:
.. code-block:: Python
app.train(training_csv_path)
This takes the arguments of both the :code:`dataloaders` method and the :code:`train` method. The function signature is modified so these arguments show up in auto-completion in a Jupyter notebook.
Predictions are made by simply calling the app object.
.. code-block:: Python
app(data_csv_path)
Command-Line Interface
=======================
Command-line interfaces are created simply by using the Poetry package management tool. Just add a line like this in :code:`pyproject.toml`
.. code-block:: toml
logistic = "logistic.apps:LogisticRegressionApp.main"
Now we can train with the command line:
.. code-block:: bash
logistic train training_csv_path
All the arguments for the dataloader and the model can be set through arguments in the CLI. To see them run
.. code-block:: bash
logistic train -h
Predictions are made like this:
.. code-block:: bash
logistic predict data_csv_path
Hyperparameter Tuning
=======================
All the arguments in the dataloader and the model can be tuned using Weights & Biases (W&B) hyperparameter sweeps (https://docs.wandb.ai/guides/sweeps). In Python, simply run:
.. code-block:: python
app.tune(runs=10)
Or from the command line, run
.. code-block:: bash
logistic tune --runs 10
These commands will connect with W&B and your runs will be visible on the wandb.ai site.
Project Generation
=======================
To use a template to construct a package for your app, simply run:
.. code-block:: bash
torchapp
.. end-quickstart
Credits
=======================
.. start-credits
torchapp was created created by Robert Turnbull with contributions from Jonathan Garber and Simone Bae.
Citation details to follow.
Logo elements derived from icons by `ProSymbols <https://thenounproject.com/icon/flame-797130/>`_ and `Philipp Petzka <https://thenounproject.com/icon/parcel-2727677/>`_.
.. end-credits
Raw data
{
"_id": null,
"home_page": "https://github.com/rbturnbull/torchapp",
"name": "torchapp",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "fastai,pytorch,deep learning,command-line interface",
"author": "Robert Turnbull",
"author_email": "robert.turnbull@unimelb.edu.au",
"download_url": "https://files.pythonhosted.org/packages/df/d0/fe74ee870413abae491503e06c8953b9f2693834cbe4deb01d54bd3ab9d7/torchapp-0.3.10.tar.gz",
"platform": null,
"description": "==========\ntorchapp\n==========\n\n.. image:: https://raw.githubusercontent.com/rbturnbull/torchapp/master/docs/images/torchapp-banner.svg\n\n.. start-badges\n\n|testing badge| |coverage badge| |docs badge| |black badge| |git3moji badge| |torchapp badge|\n\n\n.. |torchapp badge| image:: https://img.shields.io/badge/MLOpps-torchapp-B1230A.svg\n :target: https://rbturnbull.github.io/torchapp/\n\n.. |testing badge| image:: https://github.com/rbturnbull/torchapp/actions/workflows/testing.yml/badge.svg\n :target: https://github.com/rbturnbull/torchapp/actions\n\n.. |docs badge| image:: https://github.com/rbturnbull/torchapp/actions/workflows/docs.yml/badge.svg\n :target: https://rbturnbull.github.io/torchapp\n \n.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n \n.. |coverage badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/rbturnbull/506563cd9b49c8126284e34864c862d0/raw/coverage-badge.json\n :target: https://rbturnbull.github.io/torchapp/coverage/\n\n.. |git3moji badge| image:: https://img.shields.io/badge/git3moji-%E2%9A%A1%EF%B8%8F%F0%9F%90%9B%F0%9F%93%BA%F0%9F%91%AE%F0%9F%94%A4-fffad8.svg\n :target: https://robinpokorny.github.io/git3moji/\n\n.. end-badges\n\nA wrapper for PyTorch projects to create easy command-line interfaces and manage hyper-parameter tuning.\n\nDocumentation at https://rbturnbull.github.io/torchapp/\n\n.. start-quickstart\n\nInstallation\n=======================\n\nThe software can be installed using ``pip``\n\n.. code-block:: bash\n\n pip install torchapp\n\nTo install the latest version from the repository, you can use this command:\n\n.. code-block:: bash\n\n pip install git+https://github.com/rbturnbull/torchapp.git\n\n\nWriting an App\n=======================\n\nInherit a class from :code:`TorchApp` to make an app. The parent class includes several methods for training and hyper-parameter tuning. \nThe minimum requirement is that you fill out the dataloaders method and the model method.\n\nThe :code:`dataloaders` method requires that you return a fastai Dataloaders object. This is a collection of dataloader objects. \nTypically it contains one dataloader for training and another for testing. For more information see https://docs.fast.ai/data.core.html#DataLoaders\nYou can add parameter values with typing hints in the function signature and these will be automatically added to the train and show_batch methods.\n\nThe :code:`model` method requires that you return a pytorch module. Parameters in the function signature will be added to the train method.\n\nHere's an example for doing logistic regression:\n\n.. code-block:: Python\n \n #!/usr/bin/env python3\n from pathlib import Path\n import pandas as pd\n from torch import nn\n from fastai.data.block import DataBlock, TransformBlock\n from fastai.data.transforms import ColReader, RandomSplitter\n import torchapp as ta\n from torchapp.blocks import BoolBlock\n\n\n class LogisticRegressionApp(ta.TorchApp):\n \"\"\"\n Creates a basic app to do logistic regression.\n \"\"\"\n\n def dataloaders(\n self,\n csv: Path = ta.Param(help=\"The path to a CSV file with the data.\"),\n x: str = ta.Param(default=\"x\", help=\"The column name of the independent variable.\"),\n y: str = ta.Param(default=\"y\", help=\"The column name of the dependent variable.\"),\n validation_proportion: float = ta.Param(\n default=0.2, help=\"The proportion of the dataset to use for validation.\"\n ),\n batch_size: int = ta.Param(\n default=32,\n help=\"The number of items to use in each batch.\",\n ),\n ):\n\n datablock = DataBlock(\n blocks=[TransformBlock, BoolBlock],\n get_x=ColReader(x),\n get_y=ColReader(y),\n splitter=RandomSplitter(validation_proportion),\n )\n df = pd.read_csv(csv)\n\n return datablock.dataloaders(df, bs=batch_size)\n\n def model(self) -> nn.Module:\n \"\"\"Builds a simple logistic regression model.\"\"\"\n return nn.Linear(in_features=1, out_features=1, bias=True)\n\n def loss_func(self):\n return nn.BCEWithLogitsLoss()\n\n\n if __name__ == \"__main__\":\n LogisticRegressionApp.main()\n \n\nProgrammatic Interface\n=======================\n\nTo use the app in Python, simply instantiate it:\n\n.. code-block:: Python\n\n app = LogisticRegressionApp()\n\nThen you can train with the method:\n\n.. code-block:: Python\n\n app.train(training_csv_path)\n\nThis takes the arguments of both the :code:`dataloaders` method and the :code:`train` method. The function signature is modified so these arguments show up in auto-completion in a Jupyter notebook.\n\nPredictions are made by simply calling the app object.\n\n.. code-block:: Python\n\n app(data_csv_path)\n\nCommand-Line Interface\n=======================\n\nCommand-line interfaces are created simply by using the Poetry package management tool. Just add a line like this in :code:`pyproject.toml`\n\n.. code-block:: toml\n\n logistic = \"logistic.apps:LogisticRegressionApp.main\"\n\nNow we can train with the command line:\n\n.. code-block:: bash\n\n logistic train training_csv_path\n\nAll the arguments for the dataloader and the model can be set through arguments in the CLI. To see them run\n\n.. code-block:: bash\n\n logistic train -h\n\nPredictions are made like this:\n\n.. code-block:: bash\n\n logistic predict data_csv_path\n\nHyperparameter Tuning\n=======================\n\nAll the arguments in the dataloader and the model can be tuned using Weights & Biases (W&B) hyperparameter sweeps (https://docs.wandb.ai/guides/sweeps). In Python, simply run:\n\n.. code-block:: python\n\n app.tune(runs=10)\n\nOr from the command line, run\n\n.. code-block:: bash\n\n logistic tune --runs 10\n\nThese commands will connect with W&B and your runs will be visible on the wandb.ai site.\n\nProject Generation\n=======================\n\nTo use a template to construct a package for your app, simply run:\n\n.. code-block:: bash\n\n torchapp\n\n.. end-quickstart\n\nCredits\n=======================\n\n.. start-credits\n\ntorchapp was created created by Robert Turnbull with contributions from Jonathan Garber and Simone Bae.\n\nCitation details to follow.\n\nLogo elements derived from icons by `ProSymbols <https://thenounproject.com/icon/flame-797130/>`_ and `Philipp Petzka <https://thenounproject.com/icon/parcel-2727677/>`_.\n\n.. end-credits",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A wrapper for fastai projects to create easy command-line inferfaces and manage hyper-parameter tuning.",
"version": "0.3.10",
"project_urls": {
"Documentation": "https://rbturnbull.github.io/torchapp/",
"Homepage": "https://github.com/rbturnbull/torchapp",
"Repository": "https://github.com/rbturnbull/torchapp"
},
"split_keywords": [
"fastai",
"pytorch",
"deep learning",
"command-line interface"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d5c57061fd4c6439d89b5ce4e77c5deec7d926b1f5f890efb909b98ec2e8409",
"md5": "c8960d8b2fcd9829f8c83e75e69ee713",
"sha256": "617e96c280a29ee13cb8270cf134948e5df3909afa06ac6e32fb418cf2c9fd76"
},
"downloads": -1,
"filename": "torchapp-0.3.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8960d8b2fcd9829f8c83e75e69ee713",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 48251,
"upload_time": "2024-02-14T04:47:27",
"upload_time_iso_8601": "2024-02-14T04:47:27.155704Z",
"url": "https://files.pythonhosted.org/packages/5d/5c/57061fd4c6439d89b5ce4e77c5deec7d926b1f5f890efb909b98ec2e8409/torchapp-0.3.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfd0fe74ee870413abae491503e06c8953b9f2693834cbe4deb01d54bd3ab9d7",
"md5": "fd62417edbebd61e0201efafabe5f2db",
"sha256": "56f5c05936fd461a04966d04287f51ff30cad800b3cb1a3754b0b05d54ae6e29"
},
"downloads": -1,
"filename": "torchapp-0.3.10.tar.gz",
"has_sig": false,
"md5_digest": "fd62417edbebd61e0201efafabe5f2db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 41146,
"upload_time": "2024-02-14T04:47:29",
"upload_time_iso_8601": "2024-02-14T04:47:29.128249Z",
"url": "https://files.pythonhosted.org/packages/df/d0/fe74ee870413abae491503e06c8953b9f2693834cbe4deb01d54bd3ab9d7/torchapp-0.3.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 04:47:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rbturnbull",
"github_project": "torchapp",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "torchapp"
}
JSON
