Initial commit of Catalytix: Enzyme Kinetics Fitter

Author: chiragroy2007

.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Run Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+    - name: Run tests
+      run: |
+        pytest

.gitignore

@@ -0,0 +1,9 @@
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

README.md

@@ -0,0 +1,105 @@
+# Catalytix: Precision Enzyme Kinetics
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+**Catalytix** is a robust computational biology tool designed to model and analyze enzyme kinetics data. It leverages non-linear least squares regression to fit experimental data to the **Michaelis–Menten** equation, providing precise estimates for $V_{max}$ and $K_m$.
+
+Whether you are a researcher, student, or bioinformatician, Catalytix offers both a command-line interface for batch processing and a modern web interface for interactive exploration.
+
+---
+
+## 🔬 The Science
+
+This tool is built upon the foundational principles of enzyme kinetics established by **Leonor Michaelis** and **Maud Menten** in their seminal 1913 paper, *"Die Kinetik der Invertinwirkung"*.
+
+The model describes the rate of enzymatic reactions ($v$) as a function of substrate concentration ($[S]$):
+
+$$ v = \frac{V_{max} [S]}{K_m + [S]} $$
+
+Where:
+- **$V_{max}$**: The maximum reaction velocity achieved at saturating substrate concentrations.
+- **$K_m$** (Michaelis constant): The substrate concentration at which the reaction rate is half of $V_{max}$. This is often used as a measure of the enzyme's affinity for its substrate.
+
+Catalytix automates the determination of these critical parameters, replacing error-prone manual linearization methods (like Lineweaver-Burk plots) with direct non-linear regression.
+
+---
+
+## 📊 Visual Output
+
+Catalytix generates high-quality plots showing the experimental data overlaid with the fitted curve, along with a residual plot to assess the goodness of fit.
+
+![Enzyme Kinetics Fit](assets/kinetics_fit.png)
+
+*Figure 1: Example output showing the Michaelis-Menten curve fit (top) and residuals (bottom).*
+
+---
+
+## 🚀 Features
+
+- **Dual Interface**:
+    - **CLI**: Efficient for scripting and pipelines.
+    - **Web App**: Interactive Streamlit dashboard for instant visualization.
+- **Statistical Rigor**: Calculates standard deviations for parameters and $R^2$ values.
+- **Data Agnostic**: Auto-detects numeric columns in your CSV files.
+- **Publication Ready**: Exports high-DPI plots suitable for reports and papers.
+
+---
+
+## 🛠️ Installation
+
+### Prerequisites
+- Python 3.8 or higher
+
+### Quick Start
+Clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/yourusername/catalytix.git
+cd catalytix
+pip install -r requirements.txt
+```
+
+---
+
+## 💻 Usage
+
+### 1. Interactive Web App (Recommended)
+Launch the dashboard to upload data and visualize fits instantly:
+
+```bash
+streamlit run app.py
+```
+
+### 2. Command Line Interface
+Run the analysis directly on your data files:
+
+```bash
+python enzyme_kinetics_fitter.py --input data.csv --output-plot my_results.png
+```
+
+**Arguments:**
+- `--input`: Path to your CSV file.
+- `--substrate-col`: (Optional) Name of the substrate column.
+- `--velocity-col`: (Optional) Name of the velocity column.
+- `--output-json`: (Optional) Save parameters to a JSON file.
+
+---
+
+## 📂 Input Data Format
+Your CSV file should look like this:
+
+| Substrate_mM | Rate_uM_s |
+|--------------|-----------|
+| 0.1          | 0.05      |
+| 0.2          | 0.09      |
+| ...          | ...       |
+
+---
+
+## 🤝 Contributing
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📜 License
+This project is licensed under the MIT License.

app.py

@@ -0,0 +1,112 @@
+import streamlit as st
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from enzyme_kinetics_fitter import fit_michaelis_menten, michaelis_menten
+
+st.set_page_config(page_title="Catalytix: Enzyme Kinetics", page_icon="🧪")
+
+st.title("🧪 Catalytix")
+st.markdown("""
+This tool fits **Michaelis–Menten** enzyme kinetics data.
+Upload a CSV file with substrate concentration $[S]$ and initial velocity $v$.
+""")
+
+# Sidebar for inputs
+st.sidebar.header("Upload Data")
+uploaded_file = st.sidebar.file_uploader("Choose a CSV file", type="csv")
+
+if uploaded_file is not None:
+    try:
+        df = pd.read_csv(uploaded_file)
+        st.write("### Data Preview")
+        st.dataframe(df.head())
+
+        # Column selection
+        numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist()
+        
+        if len(numeric_cols) < 2:
+            st.error("CSV must contain at least two numeric columns.")
+        else:
+            st.sidebar.header("Select Columns")
+            s_col = st.sidebar.selectbox("Substrate Concentration ([S])", numeric_cols, index=0)
+            v_col = st.sidebar.selectbox("Velocity (v)", numeric_cols, index=1)
+
+            if st.sidebar.button("Fit Model"):
+                S = df[s_col].to_numpy(dtype=float)
+                v = df[v_col].to_numpy(dtype=float)
+
+                try:
+                    fit = fit_michaelis_menten(S, v)
+
+                    # Display Results
+                    st.success("Fitting successful!")
+                    
+                    col1, col2, col3 = st.columns(3)
+                    col1.metric("Vmax", f"{fit.Vmax:.4g}", delta_color="off")
+                    col2.metric("Km", f"{fit.Km:.4g}", delta_color="off")
+                    if fit.r_squared is not None:
+                        col3.metric("R²", f"{fit.r_squared:.4f}", delta_color="off")
+
+                    # Detailed stats
+                    with st.expander("See detailed statistics"):
+                        st.write(f"**Vmax Std Dev:** {fit.Vmax_std:.4g}" if fit.Vmax_std else "Vmax Std Dev: N/A")
+                        st.write(f"**Km Std Dev:** {fit.Km_std:.4g}" if fit.Km_std else "Km Std Dev: N/A")
+
+                    # Plotting
+                    st.write("### Fitted Curve")
+                    
+                    # Generate plot data
+                    S_range = np.linspace(0, S.max() * 1.1, 200)
+                    v_fit_curve = michaelis_menten(S_range, fit.Vmax, fit.Km)
+                    
+                    fig, ax = plt.subplots(figsize=(8, 5))
+                    ax.scatter(S, v, label="Experimental Data", color="black", zorder=5)
+                    ax.plot(S_range, v_fit_curve, label=f"Fit (Vmax={fit.Vmax:.2f}, Km={fit.Km:.2f})", color="red", linewidth=2)
+                    
+                    ax.set_xlabel(s_col)
+                    ax.set_ylabel(v_col)
+                    ax.set_title("Michaelis–Menten Fit")
+                    ax.legend()
+                    ax.grid(True, linestyle="--", alpha=0.5)
+                    
+                    st.pyplot(fig)
+
+                    # Residuals
+                    st.write("### Residuals")
+                    v_pred = michaelis_menten(S, fit.Vmax, fit.Km)
+                    residuals = v - v_pred
+                    
+                    fig_res, ax_res = plt.subplots(figsize=(8, 3))
+                    ax_res.axhline(0, linestyle="--", color="gray")
+                    ax_res.scatter(S, residuals, color="blue")
+                    ax_res.set_xlabel(s_col)
+                    ax_res.set_ylabel("Residuals")
+                    ax_res.grid(True, linestyle="--", alpha=0.5)
+                    
+                    st.pyplot(fig_res)
+
+                except Exception as e:
+                    st.error(f"Fitting failed: {e}")
+
+    except Exception as e:
+        st.error(f"Error reading file: {e}")
+else:
+    st.info("Please upload a CSV file to get started.")
+    
+    # Example data button
+    if st.button("Load Example Data"):
+        # Create a dummy dataframe for demonstration
+        data = {
+            "Substrate_mM": [0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0],
+            "Rate_uM_s": [0.05, 0.09, 0.22, 0.38, 0.60, 0.88, 1.05]
+        }
+        df_example = pd.DataFrame(data)
+        csv = df_example.to_csv(index=False).encode('utf-8')
+        
+        st.download_button(
+            label="Download Example CSV",
+            data=csv,
+            file_name="example_kinetics_data.csv",
+            mime="text/csv",
+        )