SpectraFit Development Assistant

An AI coding assistant specialized for the SpectraFit project - a command-line and Jupyter notebook tool for quick data-fitting based on distribution functions.

Project Overview

SpectraFit (📊📈🔬) is a scientific computing tool for spectroscopy data analysis and peak fitting. It supports multiple file formats (JSON, YAML, TOML, CSV) and provides comprehensive fitting capabilities with various distribution functions.

Code Style and Standards

1. **Follow PEP8** for all Python code

2. **Use type hints** for function signatures and variables

3. **Write descriptive variable names** - prefer explicit over implicit

4. **Keep functions small and focused** - single responsibility principle

5. **Add comprehensive docstrings** for all public functions and classes

6. **Keep documentation in sync** with code changes

Project Structure Guidelines

When suggesting new code:

- `models.py` - Data models and fitting algorithms

- `plotting.py` - Visualization functions

- `report.py` - Report generation and statistics

- `tools.py` - Utility functions

- `api/` - API endpoints and interfaces

- `plugins/` - Plugin system extensions

- `test/` - All test code (use `pytest`)

Data Handling

Input Files

Output Files

Peak Definition Example

```json

{

"peaks": {

"1": {

"pseudovoigt": {

"amplitude": { "max": 2, "min": 0, "vary": true, "value": 1 },

"center": { "max": 2, "min": -2, "vary": true, "value": 0 },

"fwhmg": { "max": 0.1, "min": 0.02, "vary": true, "value": 0.01 },

"fwhml": { "max": 0.1, "min": 0.01, "vary": true, "value": 0.01 }

}

}

}

}

```

Fitting and Optimization

Always Include Minimizer and Optimizer Settings

When generating fitting code, always respect and include these settings:

```json

{

"minimizer": {

"nan_policy": "propagate",

"calc_covar": true

},

"optimizer": {

"max_nfev": 1000,

"method": "leastsq"

}

}

```

Parameter Consistency

Error Handling

1. **Handle NaN values gracefully** - use `np.nan_to_num` or similar functions

2. **Provide informative error messages** - include context about what went wrong

3. **Use appropriate exception types** - don't catch generic exceptions unless necessary

4. **Validate inputs early** - fail fast with clear messages

Reporting and Statistics

Command Line Interface

Testing

1. **Write tests in `test/` subdirectories**

2. **Use pytest framework** for all tests

3. **Include regression tests** for bug fixes

4. **Test edge cases** - NaN values, empty inputs, boundary conditions

5. **Mock external dependencies** when appropriate

Documentation

1. **Update docstrings** for all changed functions

2. **Update `/docs/` files** when changing user-facing behavior

3. **Keep code and documentation synchronized**

4. **Include examples** in docstrings for complex functions

5. **Reference related documentation** in comments when helpful

Commit Message Format

Use Conventional Commits with gitmoji style:

| Type | Emoji | Description |

|----------|-------|------------------------------------------|

| feat | ✨ | A new feature |

| fix | 🐛 | A bug fix |

| docs | 📝 | Documentation only changes |

| style | 💄 | Formatting, missing semicolons, etc. |

| refactor | ♻️ | Code change that neither fixes nor adds |

| perf | ⚡ | Performance improvement |

| test | ✅ | Adding or correcting tests |

| build | 👷 | Build system or dependencies |

| ci | 🔧 | CI/CD configuration |

| chore | 🔨 | Other changes that don't modify src |

| revert | ⏪ | Reverts a previous commit |

**Example commit messages:**

```

feat: ✨ add new peak fitting method

fix: 🐛 handle NaN values in solver

docs: 📝 update usage documentation

test: ✅ add regression test for optimizer

refactor: ♻️ merge dictionary assignments in report generation

```

Branching Strategy (Trunk-Based Development)

1. **Branch from `main`** for all changes

2. **Use short-lived feature branches** with naming pattern: `type/short-description`

- Examples: `feat/peak-fitting`, `fix/nan-handling`, `docs/usage-update`

3. **Merge via pull request** after review and passing CI

4. **Rebase frequently** to stay current with `main`

5. **Delete feature branches** after successful merge

When Suggesting Code

1. **Always read existing code first** - never suggest changes to files you haven't seen

2. **Match existing patterns** in the codebase

3. **Consider the full parameter chain** - from input file to optimizer to output

4. **Validate against the data model** before suggesting structural changes

5. **Reference documentation** when suggesting API changes

6. **Think about backwards compatibility** - avoid breaking existing workflows

Key Principles