# Lightning Action
A modern action segmentation framework built with PyTorch Lightning for behavioral analysis.
## Features
- **Modern Architecture**: Built with PyTorch Lightning for scalable and reproducible training
- **Multiple Backbones**: Support for TemporalMLP, RNN (LSTM/GRU), and Dilated TCN architectures
- **Command-line Interface**: Easy-to-use CLI for training and inference
- **Comprehensive Logging**: Built-in metrics tracking and visualization with TensorBoard
- **Extensive Testing**: Full test coverage for reliable development
## Installation
### Prerequisites
- Python 3.10+
- PyTorch with CUDA support (optional, for GPU training)
### Install from Source
```bash
git clone https://github.com/paninski-lab/lightning-action.git
cd lightning-action
pip install -e .
```
### Dependencies
Core dependencies include:
- `pytorch-lightning` - Training framework
- `torch` - Deep learning backend
- `numpy` - Numerical computing
- `pandas` - Data manipulation
- `scikit-learn` - Machine learning utilities
- `tensorboard` - Experiment tracking
## Quick Start
### 1. Prepare Your Data
Organize your data in the following structure:
```
data/
├── markers/
│ ├── experiment1.csv
│ ├── experiment2.csv
│ └── ...
├── labels/
│ ├── experiment1.csv
│ ├── experiment2.csv
│ └── ...
└── features/ # optional, hand-crafted featurization of markers or other video representations
├── experiment1.csv
├── experiment2.csv
└── ...
```
### 2. Create a Configuration File
Create a YAML configuration file (see `configs/segmenter_example.yaml`):
```yaml
data:
data_path: /path/to/your/data
input_dir: markers
transforms: # optional, defaults to ZScore
- ZScore
model:
input_size: 10
output_size: 4
backbone: temporalmlp
num_hid_units: 256
num_layers: 2
optimizer:
type: Adam
lr: 1e-3
training:
num_epochs: 100
batch_size: 32
device: cpu # or 'gpu'
```
### 3. Train a Model
#### Using the CLI:
```bash
litaction train --config configs/my_config.yaml --output-dir runs/my_experiment
```
#### Using the Python API:
```python
from lightning_action.api import Model
# Load model from config
model = Model.from_config('configs/my_config.yaml')
# Train model
model.train(output_dir='runs/my_experiment')
```
### 4. Generate Predictions
#### Using the CLI:
```bash
litaction predict --model-dir runs/my_experiment --data-path /path/to/data --input-dir markers --output-dir predictions/
```
#### Using the Python API:
```python
# Load trained model
model = Model.from_checkpoint('runs/my_experiment')
# Generate predictions
model.predict(
data_path='/path/to/data',
input_dir='markers',
output_dir='predictions/'
)
```
See `configs/README.md` for detailed configuration options.
## Monitoring Training with TensorBoard
Lightning Action automatically logs training metrics to TensorBoard. To visualize your training progress:
1. **Launch TensorBoard** after starting training:
```bash
tensorboard --logdir /path/to/your/runs/directory
```
2. **Set the correct logdir**: Use the deepest directory that contains all your model directories. For example:
```bash
# If your models are in:
# runs/experiment1/
# runs/experiment2/
# runs/baseline/
# Launch TensorBoard with:
tensorboard --logdir runs/
```
3. **Open your browser** and navigate to `http://localhost:6006` to view the TensorBoard dashboard.
4. **Available metrics** include:
- Training and validation loss
- Training and validation accuracy
- Training and validation F1 score
- Learning rate schedules
**Tip**: Keep TensorBoard running while training multiple experiments to compare results in real-time.
## Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run all tests
pytest
# Run with coverage
pytest --cov=lightning_action
```
### Code Style
The project uses:
- `flake8` for linting
- `isort` for import sorting
- Maximum line length: 99 characters
## Project Structure
```
lightning_action/
├── api/ # High-level API for model usage
├── cli/ # Command-line interface
├── data/ # Data loading and preprocessing
├── models/ # Model architectures
│ └── backbones/ # Backbone implementations
└── tests/ # Test suite
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (`pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Citation
If you use this framework in your research, please cite:
```bibtex
@software{lightning_action,
title = {Lightning Action: A PyTorch Lightning Framework for Action Segmentation},
author = {Whiteway, Matt},
url = {https://github.com/paninski-lab/lightning-action},
year = {2024}
}
```
## Acknowledgments
This framework is built upon the work of:
- [PyTorch Lightning](https://lightning.ai/) for the training framework
- [PyTorch](https://pytorch.org/) for the deep learning backend
- Previous action segmentation work from the [Paninski Lab](https://github.com/themattinthehatt/daart)
Raw data
{
"_id": null,
"home_page": "https://github.com/paninski-lab/lightning-action",
"name": "lightning-action",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "machine learning, deep learning, action segmentation, computer vision",
"author": "Matt Whiteway",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/af/fb/aeaa15a0768970434cef179bb39081862c86beffb1314afe52f3fc770aec/lightning_action-0.1.0.tar.gz",
"platform": null,
"description": "# Lightning Action\n\nA modern action segmentation framework built with PyTorch Lightning for behavioral analysis.\n\n## Features\n\n- **Modern Architecture**: Built with PyTorch Lightning for scalable and reproducible training\n- **Multiple Backbones**: Support for TemporalMLP, RNN (LSTM/GRU), and Dilated TCN architectures\n- **Command-line Interface**: Easy-to-use CLI for training and inference\n- **Comprehensive Logging**: Built-in metrics tracking and visualization with TensorBoard\n- **Extensive Testing**: Full test coverage for reliable development\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10+ \n- PyTorch with CUDA support (optional, for GPU training)\n\n### Install from Source\n\n```bash\ngit clone https://github.com/paninski-lab/lightning-action.git\ncd lightning-action\npip install -e .\n```\n\n### Dependencies\n\nCore dependencies include:\n- `pytorch-lightning` - Training framework\n- `torch` - Deep learning backend\n- `numpy` - Numerical computing\n- `pandas` - Data manipulation\n- `scikit-learn` - Machine learning utilities\n- `tensorboard` - Experiment tracking\n\n## Quick Start\n\n### 1. Prepare Your Data\n\nOrganize your data in the following structure:\n```\ndata/\n\u251c\u2500\u2500 markers/\n\u2502 \u251c\u2500\u2500 experiment1.csv\n\u2502 \u251c\u2500\u2500 experiment2.csv\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 labels/\n\u2502 \u251c\u2500\u2500 experiment1.csv\n\u2502 \u251c\u2500\u2500 experiment2.csv\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 features/ # optional, hand-crafted featurization of markers or other video representations\n \u251c\u2500\u2500 experiment1.csv\n \u251c\u2500\u2500 experiment2.csv\n \u2514\u2500\u2500 ...\n```\n\n### 2. Create a Configuration File\n\nCreate a YAML configuration file (see `configs/segmenter_example.yaml`):\n\n```yaml\ndata:\n data_path: /path/to/your/data\n input_dir: markers\n transforms: # optional, defaults to ZScore\n - ZScore\n\nmodel:\n input_size: 10\n output_size: 4\n backbone: temporalmlp\n num_hid_units: 256\n num_layers: 2\n \noptimizer:\n type: Adam\n lr: 1e-3\n \ntraining:\n num_epochs: 100\n batch_size: 32\n device: cpu # or 'gpu'\n```\n\n### 3. Train a Model\n\n#### Using the CLI:\n```bash\nlitaction train --config configs/my_config.yaml --output-dir runs/my_experiment\n```\n\n#### Using the Python API:\n```python\nfrom lightning_action.api import Model\n\n# Load model from config\nmodel = Model.from_config('configs/my_config.yaml')\n\n# Train model\nmodel.train(output_dir='runs/my_experiment')\n```\n\n### 4. Generate Predictions\n\n#### Using the CLI:\n```bash\nlitaction predict --model-dir runs/my_experiment --data-path /path/to/data --input-dir markers --output-dir predictions/\n```\n\n#### Using the Python API:\n```python\n# Load trained model\nmodel = Model.from_checkpoint('runs/my_experiment')\n\n# Generate predictions\nmodel.predict(\n data_path='/path/to/data',\n input_dir='markers',\n output_dir='predictions/'\n)\n```\n\nSee `configs/README.md` for detailed configuration options.\n\n## Monitoring Training with TensorBoard\n\nLightning Action automatically logs training metrics to TensorBoard. To visualize your training progress:\n\n1. **Launch TensorBoard** after starting training:\n ```bash\n tensorboard --logdir /path/to/your/runs/directory\n ```\n\n2. **Set the correct logdir**: Use the deepest directory that contains all your model directories. For example:\n ```bash\n # If your models are in:\n # runs/experiment1/\n # runs/experiment2/\n # runs/baseline/\n \n # Launch TensorBoard with:\n tensorboard --logdir runs/\n ```\n\n3. **Open your browser** and navigate to `http://localhost:6006` to view the TensorBoard dashboard.\n\n4. **Available metrics** include:\n - Training and validation loss\n - Training and validation accuracy\n - Training and validation F1 score\n - Learning rate schedules\n\n**Tip**: Keep TensorBoard running while training multiple experiments to compare results in real-time.\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=lightning_action\n```\n\n### Code Style\n\nThe project uses:\n- `flake8` for linting\n- `isort` for import sorting\n- Maximum line length: 99 characters\n\n## Project Structure\n\n```\nlightning_action/\n\u251c\u2500\u2500 api/ # High-level API for model usage\n\u251c\u2500\u2500 cli/ # Command-line interface\n\u251c\u2500\u2500 data/ # Data loading and preprocessing\n\u251c\u2500\u2500 models/ # Model architectures\n\u2502 \u2514\u2500\u2500 backbones/ # Backbone implementations\n\u2514\u2500\u2500 tests/ # Test suite\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use this framework in your research, please cite:\n\n```bibtex\n@software{lightning_action,\n title = {Lightning Action: A PyTorch Lightning Framework for Action Segmentation},\n author = {Whiteway, Matt},\n url = {https://github.com/paninski-lab/lightning-action},\n year = {2024}\n}\n```\n\n## Acknowledgments\n\nThis framework is built upon the work of:\n- [PyTorch Lightning](https://lightning.ai/) for the training framework\n- [PyTorch](https://pytorch.org/) for the deep learning backend\n- Previous action segmentation work from the [Paninski Lab](https://github.com/themattinthehatt/daart)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Action segmentation framework built with PyTorch Lightning",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/paninski-lab/lightning-action",
"Homepage": "https://github.com/paninski-lab/lightning-action",
"Repository": "https://github.com/paninski-lab/lightning-action"
},
"split_keywords": [
"machine learning",
" deep learning",
" action segmentation",
" computer vision"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3b6de701c3ca288fcf625d5a0cae5f0aaed2c3397fb98bab8afa487bc3361fe",
"md5": "b833da5cd77dc662da02651399f397fd",
"sha256": "fc47bc9307ee13d6ca2933f429eaaf8a2cf16716dd2d65144bd07d1494099649"
},
"downloads": -1,
"filename": "lightning_action-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b833da5cd77dc662da02651399f397fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 42160,
"upload_time": "2025-07-17T21:20:43",
"upload_time_iso_8601": "2025-07-17T21:20:43.554166Z",
"url": "https://files.pythonhosted.org/packages/e3/b6/de701c3ca288fcf625d5a0cae5f0aaed2c3397fb98bab8afa487bc3361fe/lightning_action-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "affbaeaa15a0768970434cef179bb39081862c86beffb1314afe52f3fc770aec",
"md5": "88c7ef772ef7e7a9a5a2daa8da5813fb",
"sha256": "f44408ed18c9e86b88654802a7287d5247d60cb5396f5c8f478f9c5fa1158ce5"
},
"downloads": -1,
"filename": "lightning_action-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "88c7ef772ef7e7a9a5a2daa8da5813fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 33138,
"upload_time": "2025-07-17T21:20:44",
"upload_time_iso_8601": "2025-07-17T21:20:44.672601Z",
"url": "https://files.pythonhosted.org/packages/af/fb/aeaa15a0768970434cef179bb39081862c86beffb1314afe52f3fc770aec/lightning_action-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 21:20:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paninski-lab",
"github_project": "lightning-action",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lightning-action"
}
JSON
