PyScrew
PyScrew is a Python package designed to simplify access to industrial research data from screw driving experiments. It provides a streamlined interface for downloading, validating, and preparing experimental datasets hosted on Zenodo.
More information on the data is available here: https://zenodo.org/records/14769379
Features
- Data loading from various scenarios
- Handling duplicates and missing values
- Length normalization through padding and truncation
- Configurable data processing pipeline
- Comprehensive data validation and integrity checks
- Detailed logging and statistics tracking
- Support for multiple measurement types (torque, angle, time, gradient, step)
Installation
To install PyScrew, use pip:
pip install pyscrew
Usage
Basic Usage
You can load data from a specific scenario using the get_data function with default settings:
import pyscrew
# Load data from the thread degradation scenario (s01)
data = pyscrew.get_data(scenario="s01")
# Access the measurements and labels
x_values = data["torque_values"]
y_values = data["class_values"]
Advanced Usage
Click to expand for detailed configuration options
import pyscrew
# Load and process data with custom settings
data = pyscrew.get_data(
scenario="assembly-conditions-2", # or "s04" or "s04_assembly-conditions-2"
cache_dir="~/.cache/pyscrew", # Specify custom directory (default: src/pyscrew/downloads)
force_download=True, # Force re-download even if cached
handle_duplicates="first", # How to handle duplicate time points
handle_missings="mean", # How to handle missing values
target_length=2000, # Target length for normalization
)
# Describe the data
print("Available measurements:", data.keys())
print("Number of torque measurements:", len(data["torque_values"]))
# Access the data
x_values = data["torque_values"]
y_values = data["class_values"]
Scenario Specification
The scenario parameter can be specified in three different ways:
- Short ID: Use the scenario identifier (e.g.,
"s01","s02", etc.) - Full Name: Use the descriptive name (e.g.,
"thread-degradation","surface-friction") - Full ID: Use the complete identifier (e.g.,
"s01_thread-degradation","s02_surface-friction")
All three formats are equivalent and will load the same dataset. For example, these all refer to the same scenario:
data = pyscrew.get_data(scenario="s02") # Short ID
data = pyscrew.get_data(scenario="surface-friction") # Full name
data = pyscrew.get_data(scenario="s02_surface-friction") # Full ID
You can find more info regarding the scenarios on github and on zenodo, or you can simply list available scenarios with their descriptions like this:
scenarios = pyscrew.list_scenarios()
print("Available scenarios:", scenarios)
Available Scenarios
Our datasets examine various aspects of screw driving operations in industrial settings. Each scenario focuses on specific experimental conditions and research questions:
| ID | Name | Description | Samples | Classes | Documentation |
|---|---|---|---|---|---|
| s01 | Thread Degradation | Examines thread degradation in plastic materials through repeated fastening operations | 5,000 | 1 | Details |
| s02 | Surface Friction | Investigates the impact of different surface conditions (water, lubricant, adhesive, etc.) on screw driving operations | 12,500 | 8 | Details |
| s03 | Assembly Conditions 1 | Examines various screw and component faults including washer modifications, thread deformations, and alignment issues | 1,700 | 26 | Details |
| s04 | Assembly Conditions 2 | Investigates thread modifications, surface conditions, component modifications, and process parameter changes | 5,000 | 25 | Details |
| s05 | Upper Workpiece Fabrication | Analyzes variations in injection molding parameters for upper workpieces | 2,400 | 42 | Details |
| s06 | Lower Workpiece Fabrication | Studies variations in injection molding parameters for lower workpieces | 7,482 | 44 | Details |
Package Structure
PyScrew/
├── docs/
│ └── scenarios/
│ ├── s01_thread-degradation.md
│ ├── s02_surface-friction.md
│ ├── s03_assembly-conditions-1.md
│ ├── s04_assembly-conditions-2.md
│ ├── s05_upper-workpiece.md
│ └── s06_lower-workpiece.md
├── src/
│ └── pyscrew/
│ ├── __init__.py # Package initialization and version
│ ├── main.py # Main interface and high-level functions
│ ├── core/ # Core data model and structures
│ │ ├── __init__.py
│ │ ├── dataset.py # ScrewDataset class
│ │ ├── run.py # ScrewRun class
│ │ ├── step.py # ScrewStep class
│ │ └── fields.py # Field definitions
│ ├── config/ # Configuration management
│ │ ├── __init__.py
│ │ ├── pipeline.py # Pipeline configuration
│ │ └── scenarios.py # Scenario configuration
│ ├── pipeline/ # Data processing pipeline components
│ │ ├── __init__.py
│ │ ├── loading.py # Data loading from Zenodo
│ │ ├── processing.py # Data processing functionality
│ │ ├── validating.py # Data validation after loading
│ │ └── transformers/ # Data transformation modules
│ ├── scenarios/ # Scenario-specific configurations
│ │ ├── __init__.py
│ │ ├── s01.yml # Thread degradation scenario
│ │ ├── s02.yml # Surface friction scenario
│ │ ├── s03.yml # Assembly conditions 1
│ │ ├── s04.yml # Assembly conditions 2
│ │ ├── s05.yml # Upper workpiece
│ │ └── s06.yml # Lower workpiece
│ ├── downloads/ # Default location for downloaded data
│ │ ├── archives/ # Compressed dataset archives
│ │ └── extracted/ # Extracted dataset files
│ ├── tools/ # Utility scripts and tools
│ │ ├── create_label_csv.py # Label file generation
│ │ └── get_dataset_metrics.py # Documentation metrics calculation
│ └── utils/ # Utility functions and helpers
│ ├── data_model.py
│ └── logger.py
└── tests/ # Test suite
API Reference
Main Functions
get_data(scenario_name: str, cache_dir: Optional[Path] = None, force: bool = False) -> Path
Downloads and extracts a specific dataset.
scenario_name: Name of the dataset to downloadcache_dir: Optional custom cache directory (default: ~/.cache/pyscrew)force: Force re-download even if cached- Returns: Path to extracted dataset
list_scenarios() -> Dict[str, str]
Lists all available datasets and their descriptions.
- Returns: Dictionary mapping scenario names to descriptions
Cache Structure
Downloaded data is stored in:
~/.cache/pyscrew/
├── archives/ # Compressed dataset archives
└── extracted/ # Extracted dataset files
├── s01_thread-degradation/
├── s02_surface-friction/
├── s03_assembly-conditions-1/
├── s04_assembly-conditions-2/
├── s05_upper-workpiece/
├── s06_lower-workpiece/
└── ...
Code Style
This project uses:
- Black for code formatting
- Ruff for fast linting and import sorting
- MyPy for static type checking
- Pytest for testing
Configuration for these tools can be found in pyproject.toml.
Development
The package is under active development. Further implementation will add data processing utilities and data validation tools.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Citation
If you use this package in your research, please cite our arXiv publication:
- West, N., & Deuse, J. (2025). PyScrew: A Comprehensive Dataset Collection from Industrial Screw Driving Experiments. arXiv (Computer Science > Machine Learning), 1-18. https://doi.org/10.48550/arXiv.2505.11925
The PyScrew data was used in other papers that might be interesting to you as well:
- West, N., & Deuse, J. (2024). A Comparative Study of Machine Learning Approaches for Anomaly Detection in Industrial Screw Driving Data. Proceedings of the 57th Hawaii International Conference on System Sciences (HICSS), 1050-1059. https://hdl.handle.net/10125/106504
- West, N., Trianni, A. & Deuse, J. (2024). Data-driven analysis of bolted joints in plastic housings with surface-based anomalies using supervised and unsupervised machine learning. CIE51 Proceedings. (DOI will follow after publication of the proceedings)
- West, N. & Deuse, J. (2025). Multi-class Error Detection in Industrial Screw Driving 2 Operations Using Machine Learning. Proceedings of the 11th International conference on Time Series and Forecasting (ITISE). (DOI will follow after publication of the proceedings)
Metadata
Release files for pyscrew 1.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyscrew-1.2.4.tar.gz | 82.3 kB | Without provenance | Details for pyscrew-1.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyscrew-1.2.4-py3-none-any.whl | Python 3 | none | any | Details for pyscrew-1.2.4-py3-none-any.whl |
Total release size: 178.4 kB
Release files / pyscrew-1.2.4.tar.gz
| Download URL | pyscrew-1.2.4.tar.gz |
|---|---|
| Size | 82.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
158718dfc8240b9ad94954003a32d4bb4f852cb817f9211e6188e2b20ec3676a
|
|
BLAKE2b-256 checksum How to use checksums |
7b8e79adae53b24ebd6a8a39b2f01135cff60cb18540b32bd88806cb4f112201
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / pyscrew-1.2.4-py3-none-any.whl
| Download URL | pyscrew-1.2.4-py3-none-any.whl |
|---|---|
| Size | 96.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
810d281d32e11d38e79d6825e7634fc34f461b26663257283ebcc9efd468ffca
|
|
BLAKE2b-256 checksum How to use checksums |
e424c14e04d92ac3c799e78704646b06245eddad8f3e14d4c28e58ecd195546e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for pyscrew 1.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.