Skip to main content

PyPI version Python License Downloads

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:

  1. Short ID: Use the scenario identifier (e.g., "s01", "s02", etc.)
  2. Full Name: Use the descriptive name (e.g., "thread-degradation", "surface-friction")
  3. 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 download
  • cache_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)

Source distribution for pyscrew 1.2.4
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)

Table of built distributions (wheels) for pyscrew 1.2.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page