Contributing to spectre#

We welcome contributions from the community.

Getting Started#

  1. Fork the repository on Codeberg
  2. Clone your fork locally:
git clone https://codeberg.org/your-username/spectre.git
cd spectre
  1. Install the package in development mode with all dependencies:

Using uv:

uv venv
source .venv/bin/activate
uv pip install -e .

Using pip:

pip install -e .
  1. Create a new branch for your changes:
git checkout -b feature/your-feature-name

Development Workflow#

Code Quality Standards#

  • Type hints: Use throughout (e.g., torch.Tensor, dict[str, float])
  • Docstrings: Minimalistic NumPy format with backticks for code (method(), variable, Type)
  • Line length: 88 characters maximum
  • Comments: Only when purpose unclear from context
  • Error handling: Descriptive ValueError/TypeError with context

Running Tests#

Run tests using pytest:

# Run all tests
pytest tests/test_*

# Run specific test modules
pytest tests/test_decomposition_*.py -v

# Run with coverage
pytest tests/ --cov=spectre --cov-report=html

You can also use a script for running unit tests. See:

python tools/run_unit_tests -h

Test coverage should remain above 80%.

Code Style#

We use several tools to maintain code quality:

In general, we encourage using tools from https://docs.astral.sh/.

Before submitting a pull request, ensure your code passes all checks:

# Run linter
ruff check spectre/

# Run type checker
ty check spectre/

# Run unit tests
pytest tests/

Contributing#

Reporting Bugs#

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

  • A clear title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • Your environment (Python version, PyTorch version, OS)
  • Any relevant code snippets or error messages

Use the bug report template when creating an issue.

Suggesting Improvements#

Suggestions are tracked as Codeberg issues. When creating asuggestion, include:

  • A clear and descriptive title
  • A detailed description of the proposed functionality
  • Examples of how the feature would be used
  • Any relevant references (research papers, implementations, etc.)

Use the feature request template when creating an issue.

Pull Requests#

  1. Ensure your code follows the project's code quality standards
  2. Add tests for any new functionality
  3. Update documentation as needed
  4. Ensure all tests pass
  5. Submit a pull request with a clear description of the changes

Project Structure#

spectre/
├──  spectre                 # Main package
│   ├── core                  # Core classes (`Estimator`, `Model`)
│   ├── data                  # Data (weighted datasets, dataloaders)
│   ├── kernel                # Kernel implementations
│   ├── loss                  # Loss functions
│   ├── transform             # Transform modules
│   ├── metrics               # Various metrics
│   ├── module                # Additional modules
│   ├── pairwise_distance     # Pairwise distances for kernels
│   ├── decomposition         # Non-parametric methods (diffusion maps)
│   ├── parametric            # Parametric neural networks
│   ├── clustering            # Basic clustering algorithms
│   ├── comparator            # Neural networks comparators
│   ├── ensemble              # Ensemble methods
│   ├── feature_selection     # Feature selection methods
│   ├── stats                 # Weighted statistics
│   ├── utils                 # Utilities (e.g., KDE, free-energy computations)
│   ├── validation            # Cross-validation and bootstrapping
│   ├── ...
├──  tests                   # Unit test suite
├──  docs                    # MkDocs documentation
└── ...

Code of Conduct#

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to jr@fizyka.umk.pl.

See CODE_OF_CONDUCT.md for details.

Questions?#

Feel free to open an issue with your question or contact the maintainers directly.

License#

By contributing to spectre, you agree that your contributions will be licensed under the MIT License.