tidymut 0.0.0__tar.gz

tidymut-0.0.0/.gitignore

@@ -0,0 +1,45 @@
+# Editor temporary/working/backup files #
+#########################################
+.#*
+*\#*\#
+[#]*#
+*~
+*$
+*.bak
+*flymake*
+*.iml
+*.kdev4
+*.log
+*.swp
+*.pdb
+*.zip
+.project
+.pydevproject
+.settings
+.idea
+.vagrant
+.noseids
+.ipynb_checkpoints
+.tags
+.cache/
+.vscode/
+
+# Python files #
+################
+__pycache__/
+# pytest
+/.pytest_cache
+# egg metadata
+*.egg-info
+*.eggs
+# coverage
+.coverage
+coverage.xml
+coverage_html_report
+htmlcov
+
+# Documentation related files #
+###############################
+doc/source/
+doc/make.bat
+doc/Makefile

tidymut-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Yuxiang Tang.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tidymut-0.0.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: tidymut
+Version: 0.0.0
+Summary: An efficient framework for tidying and standardizing protein mutation data.
+Author-email: Yuxiang Tang <845351766@qq.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025, Yuxiang Tang.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Project-URL: Repository, https://github.com/xulab-research/TidyMut
+Keywords: protein,mutation,tidy,framework,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: joblib>=1.5.0
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: tzdata>=2022.7
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: sphinx>=8.0.0; extra == "dev"
+Requires-Dist: sphinx-autobuild>=2024.10.0; extra == "dev"
+Requires-Dist: sphinx_rtd_theme>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# TidyMut
+
+A comprehensive Python package for processing and analyzing biological sequence data with advanced mutation analysis capabilities.
+
+## Overview
+
+TidyMut is designed for bioinformaticians, computational biologists, and researchers working with genetic sequence data. The package streamlines the complex process of cleaning, processing, and analyzing DNA and protein sequences, with specialized tools for mutation analysis and large-scale dataset handling.
+
+### Key Capabilities
+
+- **Sequence Data Processing**: Comprehensive support for DNA and protein sequence operations including complementation, transcription, translation, and validation
+- **Advanced Mutation Analysis**: Specialized tools for detecting, analyzing, and characterizing genetic mutations with statistical insights
+- **Intelligent Data Cleaning**: Automated preprocessing pipelines that handle common data quality issues in biological datasets
+- **Flexible Pipeline Architecture**: Modular design allowing custom workflow creation for specific research needs
+- **High-Performance Processing**: Optimized for handling large-scale sequence datasets efficiently
+
+## Installation
+
+### Requirements
+- Python 3.13+
+- pandas
+
+### Install via pip
+```bash
+pip install tidymut
+```
+
+### Development Installation
+```bash
+git clone https://github.com/xulab-research/TidyMut.git tidymut
+cd tidymut
+pip install -e .
+```
+
+## Quick Start
+
+### Processing K50 Dataset
+
+Here's a complete example demonstrating TidyMut's capabilities with the K50 mutation dataset:
+
+```python
+from tidymut import k50_cleaner
+
+
+# Create K50 cleaning pipeline using TidyMut's default pipeline
+# Download from: https://zenodo.org/records/799292
+# File: `Tsuboyama2023_Dataset2_Dataset3_20230416.csv` in `Processed_K50_dG_datasets.zip`
+k50_cleaning_pipeline = k50_cleaner.create_k50_cleaner(
+    "path/to/Tsuboyama2023_Dataset2_Dataset3_20230416.csv"
+)
+
+# Clean and process the dataset 
+k50_dataset = clean_k50_dataset(k50_cleaning_pipeline)
+
+# Save the processed dataset
+k50_dataset.save("output/cleaned_k50_data")
+
+# Access processed data
+print(f"Dataset contains {len(k50_dataset)} sequences")
+print(f"Mutation types identified: {k50_dataset.mutation_summary()}")
+```
+
+### Basic Sequence Operations
+
+```python
+from tidymut.sequence import DNASequence, ProteinSequence
+
+# DNA sequence analysis
+dna = DNASequence("ATGCGATCGTAGC")
+print(f"Complement: {dna.complement()}")
+print(f"Reverse complement: {dna.reverse_complement()}")
+print(f"Translation: {dna.translate()}")
+```
+
+## Core Features
+
+### Sequence Data Manipulation
+- **Sequence Validation**: Automatic detection and correction of common sequence errors
+- **Format Conversion**: Seamless conversion between different sequence formats
+- **Batch Processing**: Efficient handling of large sequence collections
+
+### Mutation Analysis
+- **Mutation Detection**: Automated identification of point mutations, insertions, and deletions
+- **Statistical Analysis**: Comprehensive mutation frequency and distribution statistics
+- **Visualization Tools**: Built-in plotting functions for mutation landscapes
+
+### Data Cleaning & Preprocessing
+- **Standardization**: Consistent sequence formatting and annotation
+- **Duplicate Removal**: Intelligent handling of redundant sequences
+
+### Pipeline Architecture
+- **Modular Design**: Mix and match processing components
+- **Parallel Processing**: Multi-core support for large datasets
+- **Progress Tracking**: Real-time processing status and logging
+
+## Examples and Use Cases
+
+### Comparative Mutation Analysis
+```python
+from tidymut.analysis import MutationComparator
+
+comparator = MutationComparator()
+comparator.add_dataset("wildtype", wt_sequences)
+comparator.add_dataset("variant", variant_sequences)
+
+results = comparator.compare_mutation_profiles()
+comparator.plot_comparison(results)
+```
+
+### Custom Processing Pipeline
+```python
+import pandas as pd
+from typing import Tuple
+
+from tidymut.cleaners.basic_cleaners import (
+    extract_and_rename_columns,
+    filter_and_clean_data,
+    convert_data_types,
+    validate_mutations,
+    infer_wildtype_sequences,
+    convert_to_mutation_dataset_format,
+)
+from tidymut.core.dataset import MutationDataset
+from tidymut.core.pipeline import Pipeline, create_pipeline
+
+dataset = pd.read_csv("path/to/Tsuboyama2023_Dataset2_Dataset3_20230416.csv")
+
+pipeline = create_pipeline(dataset, "k50_cleaner")
+clean_result = (
+    pipeline.then(
+        extract_and_rename_columns,
+        column_mapping={
+            "WT_name": "name",
+            "aa_seq": "mut_seq",
+            "mut_type": "mut_info",
+            "ddG_ML": "ddG",
+        },
+    )
+    .then(filter_and_clean_data, filters={"ddG": lambda x: x != "-"})
+    .then(convert_data_types, type_conversions={"ddG": "float"})
+    .then(
+        validate_mutations,
+        mutation_column="mut_info",
+        mutation_sep="_",
+        is_zero_based=False,
+        num_workers=16,
+    )
+    .then(
+        infer_wildtype_sequences,
+        label_columns=["ddG"],
+        handle_multiple_wt="error",
+        is_zero_based=True,
+        num_workers=16,
+    )
+    .then(
+        convert_to_mutation_dataset_format,
+        name_column="name",
+        mutation_column="mut_info",
+        mutated_sequence_column="mut_seq",
+        score_column="ddG",
+        is_zero_based=True,
+    )
+)
+k50_dataset_df, k50_ref_seq = clean_result.data
+k50_dataset = MutationDataset.from_dataframe(k50_dataset_df, k50_ref_seq)
+
+# Get execution summary
+execution_info = pipeline.get_execution_summary()
+
+# Access artifacts
+artifacts = pipeline.artifacts
+
+# Save pipeline state
+pipeline.save_structured_data("k50_cleaner_pipeline.pkl")
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:
+- Code style and standards
+- Testing requirements
+- Pull request process
+- Issue reporting
+
+## Citation
+
+If you use TidyMut in your research, please cite:
+
+```bibtex
+@software{tidymut,
+  title={TidyMut: A Python Package for Biological Sequence Data Processing},
+  author={Your Name and Contributors},
+  year={2025},
+  url={https://github.com/xulab-research/tidymut}
+}
+```
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/xulab-research/tidymut/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/xulab-research/tidymut/discussions)
+- **Email**: 

tidymut-0.0.0/README.md

@@ -0,0 +1,206 @@
+# TidyMut
+
+A comprehensive Python package for processing and analyzing biological sequence data with advanced mutation analysis capabilities.
+
+## Overview
+
+TidyMut is designed for bioinformaticians, computational biologists, and researchers working with genetic sequence data. The package streamlines the complex process of cleaning, processing, and analyzing DNA and protein sequences, with specialized tools for mutation analysis and large-scale dataset handling.
+
+### Key Capabilities
+
+- **Sequence Data Processing**: Comprehensive support for DNA and protein sequence operations including complementation, transcription, translation, and validation
+- **Advanced Mutation Analysis**: Specialized tools for detecting, analyzing, and characterizing genetic mutations with statistical insights
+- **Intelligent Data Cleaning**: Automated preprocessing pipelines that handle common data quality issues in biological datasets
+- **Flexible Pipeline Architecture**: Modular design allowing custom workflow creation for specific research needs
+- **High-Performance Processing**: Optimized for handling large-scale sequence datasets efficiently
+
+## Installation
+
+### Requirements
+- Python 3.13+
+- pandas
+
+### Install via pip
+```bash
+pip install tidymut
+```
+
+### Development Installation
+```bash
+git clone https://github.com/xulab-research/TidyMut.git tidymut
+cd tidymut
+pip install -e .
+```
+
+## Quick Start
+
+### Processing K50 Dataset
+
+Here's a complete example demonstrating TidyMut's capabilities with the K50 mutation dataset:
+
+```python
+from tidymut import k50_cleaner
+
+
+# Create K50 cleaning pipeline using TidyMut's default pipeline
+# Download from: https://zenodo.org/records/799292
+# File: `Tsuboyama2023_Dataset2_Dataset3_20230416.csv` in `Processed_K50_dG_datasets.zip`
+k50_cleaning_pipeline = k50_cleaner.create_k50_cleaner(
+    "path/to/Tsuboyama2023_Dataset2_Dataset3_20230416.csv"
+)
+
+# Clean and process the dataset 
+k50_dataset = clean_k50_dataset(k50_cleaning_pipeline)
+
+# Save the processed dataset
+k50_dataset.save("output/cleaned_k50_data")
+
+# Access processed data
+print(f"Dataset contains {len(k50_dataset)} sequences")
+print(f"Mutation types identified: {k50_dataset.mutation_summary()}")
+```
+
+### Basic Sequence Operations
+
+```python
+from tidymut.sequence import DNASequence, ProteinSequence
+
+# DNA sequence analysis
+dna = DNASequence("ATGCGATCGTAGC")
+print(f"Complement: {dna.complement()}")
+print(f"Reverse complement: {dna.reverse_complement()}")
+print(f"Translation: {dna.translate()}")
+```
+
+## Core Features
+
+### Sequence Data Manipulation
+- **Sequence Validation**: Automatic detection and correction of common sequence errors
+- **Format Conversion**: Seamless conversion between different sequence formats
+- **Batch Processing**: Efficient handling of large sequence collections
+
+### Mutation Analysis
+- **Mutation Detection**: Automated identification of point mutations, insertions, and deletions
+- **Statistical Analysis**: Comprehensive mutation frequency and distribution statistics
+- **Visualization Tools**: Built-in plotting functions for mutation landscapes
+
+### Data Cleaning & Preprocessing
+- **Standardization**: Consistent sequence formatting and annotation
+- **Duplicate Removal**: Intelligent handling of redundant sequences
+
+### Pipeline Architecture
+- **Modular Design**: Mix and match processing components
+- **Parallel Processing**: Multi-core support for large datasets
+- **Progress Tracking**: Real-time processing status and logging
+
+## Examples and Use Cases
+
+### Comparative Mutation Analysis
+```python
+from tidymut.analysis import MutationComparator
+
+comparator = MutationComparator()
+comparator.add_dataset("wildtype", wt_sequences)
+comparator.add_dataset("variant", variant_sequences)
+
+results = comparator.compare_mutation_profiles()
+comparator.plot_comparison(results)
+```
+
+### Custom Processing Pipeline
+```python
+import pandas as pd
+from typing import Tuple
+
+from tidymut.cleaners.basic_cleaners import (
+    extract_and_rename_columns,
+    filter_and_clean_data,
+    convert_data_types,
+    validate_mutations,
+    infer_wildtype_sequences,
+    convert_to_mutation_dataset_format,
+)
+from tidymut.core.dataset import MutationDataset
+from tidymut.core.pipeline import Pipeline, create_pipeline
+
+dataset = pd.read_csv("path/to/Tsuboyama2023_Dataset2_Dataset3_20230416.csv")
+
+pipeline = create_pipeline(dataset, "k50_cleaner")
+clean_result = (
+    pipeline.then(
+        extract_and_rename_columns,
+        column_mapping={
+            "WT_name": "name",
+            "aa_seq": "mut_seq",
+            "mut_type": "mut_info",
+            "ddG_ML": "ddG",
+        },
+    )
+    .then(filter_and_clean_data, filters={"ddG": lambda x: x != "-"})
+    .then(convert_data_types, type_conversions={"ddG": "float"})
+    .then(
+        validate_mutations,
+        mutation_column="mut_info",
+        mutation_sep="_",
+        is_zero_based=False,
+        num_workers=16,
+    )
+    .then(
+        infer_wildtype_sequences,
+        label_columns=["ddG"],
+        handle_multiple_wt="error",
+        is_zero_based=True,
+        num_workers=16,
+    )
+    .then(
+        convert_to_mutation_dataset_format,
+        name_column="name",
+        mutation_column="mut_info",
+        mutated_sequence_column="mut_seq",
+        score_column="ddG",
+        is_zero_based=True,
+    )
+)
+k50_dataset_df, k50_ref_seq = clean_result.data
+k50_dataset = MutationDataset.from_dataframe(k50_dataset_df, k50_ref_seq)
+
+# Get execution summary
+execution_info = pipeline.get_execution_summary()
+
+# Access artifacts
+artifacts = pipeline.artifacts
+
+# Save pipeline state
+pipeline.save_structured_data("k50_cleaner_pipeline.pkl")
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:
+- Code style and standards
+- Testing requirements
+- Pull request process
+- Issue reporting
+
+## Citation
+
+If you use TidyMut in your research, please cite:
+
+```bibtex
+@software{tidymut,
+  title={TidyMut: A Python Package for Biological Sequence Data Processing},
+  author={Your Name and Contributors},
+  year={2025},
+  url={https://github.com/xulab-research/tidymut}
+}
+```
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/xulab-research/tidymut/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/xulab-research/tidymut/discussions)
+- **Email**: 

tidymut-0.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "setuptools_scm>=8.2.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tidymut"
+dynamic = ["version"]
+description = "An efficient framework for tidying and standardizing protein mutation data."
+readme = "README.md"
+authors = [{ name = "Yuxiang Tang", email = "845351766@qq.com" }]
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "joblib>=1.5.0",
+    "numpy>=2.1.0",
+    "pandas>=2.1.0",
+    "tqdm>=4.60.0",
+    "python-dateutil>=2.8.2",
+    "tzdata>=2022.7",
+]
+keywords = ["protein", "mutation", "tidy", "framework", "pipeline"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: BSD License",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/xulab-research/TidyMut"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0", "pytest-cov>=6.0.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=6.0.0",
+    "sphinx>=8.0.0",
+    "sphinx-autobuild>=2024.10.0",
+    "sphinx_rtd_theme>=3.0.0"
+]

tidymut-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+