Move tests and improve automatic documentation generation

Author: jdehning

.github/workflows/pytest.yaml

@@ -0,0 +1,34 @@
+name: Run tests
+
+on:
+  pull_request:
+  push:
+      branches:
+      - main
+      - master
+
+jobs:
+  run-tests:
+    strategy:
+      matrix:
+        python-version: [ "3.10", "3.x" ]
+        os: [ ubuntu-latest ]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Test with pytest
+        run: |
+          pytest -n auto

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.7
+    hooks:
+      - id: ruff  # linter
+        types_or: [ python, pyi, jupyter ]
+        args: [ --fix ]
+      - id: ruff-format  # formatter
+        types_or: [ python, pyi, jupyter ]
+
+
+
+

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs 

CHANGELOG.md

@@ -30,7 +30,7 @@ Changelog
 * __Changed__: Due to above, `method` is now the second positional argument (this might break scripts that gave `steps`, `dt`, or `dtunit` as positonal arguments). Call `mre.coefficients(data, 'ts')` or as before via keyword `mre.coefficients(data, method='ts')`
 * __Fixed__: Typo that caused `full_analysis()` to crash when calling the consistency check.
 * __Fixed__: Workaround to prevent a memory leak when calling `full_analysis()` repeatedly. Always set `showoverview=False` when using `full_analysis()` in for loops.
-We now temporarily set `matplotlib.rcParams['interactive'] = showoverview` to avoid opening a new figure every time. This should make the panel and `showoverview` argument feel more consistent. The same workaround can be used in your custom scripts when using the `OutputHandler` (that also opens figures): Nest the loop inside a `with matplotlib.rc_context(rc={'interactive': False}):` (or adjust your rc parameters) to avoid figures.
+  We now temporarily set `matplotlib.rcParams['interactive'] = showoverview` to avoid opening a new figure every time. This should make the panel and `showoverview` argument feel more consistent. The same workaround can be used in your custom scripts when using the `OutputHandler` (that also opens figures): Nest the loop inside a `with matplotlib.rc_context(rc={'interactive': False}):` (or adjust your rc parameters) to avoid figures.
 * __Fixed__: Various small bugs
 * __New__: `coefficients` has a new keyword argument `knownmean` to provide a known mean activity. If provdied, it will be used as the expectation value of the activity instead of calculating the mean as an approximation (both, in `stationarymean` and `trialseparated` method). This allows for custom estimates but, for instance, `m>1` will not be detectable as the covariance cannot diverge when the same (time independent) expectation value is used for `<a_{t}>` and `<a_{t+k}>`. As one example, `knownmean=0` restrains the fitted line (with slope `r_k`) to go through the origin `(0,0)`. See [Zierenberg et al., in press](https://arxiv.org/abs/1905.10402).
 
@@ -47,9 +47,9 @@ We now temporarily set `matplotlib.rcParams['interactive'] = showoverview` to av
 * __Changed__: `full_analysis()` argument `fitfunctions` renamed to `fitfuncs` to be consistent with `fit()` and `coefficients()`
 * __Changed__: `full_analysis()` was rewritten, now only has three required arguments: `data`, `dt` and `kmax`, where `kmax` can be substituted by `steps` or `tmax`.
 * __Changed__: concerning the `seed` argument for various functions:
-all functions take either `seed=None` (no reseeding), `seed='random'` (reseeding to a random value - causing irreproducible resaults) or to a fixed value `seed=int(yourseed)`.
-Per default, analysis functions - `full_analysis()`, `fit()` and `coefficients()` - produce same results by seeding to a fixed value each call. (only confidence intervals are affected by seeding)
-Per default, `simulate_branching()` and `simulate_subsampling()` seed to `random`.
+  all functions take either `seed=None` (no reseeding), `seed='random'` (reseeding to a random value - causing irreproducible resaults) or to a fixed value `seed=int(yourseed)`.
+  Per default, analysis functions - `full_analysis()`, `fit()` and `coefficients()` - produce same results by seeding to a fixed value each call. (only confidence intervals are affected by seeding)
+  Per default, `simulate_branching()` and `simulate_subsampling()` seed to `random`.
 * __Fixed__: when calling branching process with `subp` and providing a seed, the subsampling no longer reseeds the rng device. (hence every call produces the same outcome, as expected)
 * __Fixed__: `simulate_subsampling()` now returns np arrays of correct dimensions
 * __New__: `full_analysis()` now shows a warning in the overview panel if consistency checks fail (so far only one).

CONTRIBUTING.md

@@ -0,0 +1,221 @@
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at https://github.com/Priesemann-Group/mrestimator/issues.
+
+If you are reporting a bug, please include ideally a minimal reproducible example with:
+- Your operating system name and version
+- Python version and mrestimator version
+- Any details about your local setup that might be helpful in troubleshooting
+- Detailed steps to reproduce the bug
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and
+"help wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with
+"enhancement" and "help wanted" is open to whoever wants to implement
+it.
+
+### Write Documentation
+
+Mr. Estimator could always use more documentation,
+whether as part of the official docs,
+in docstrings, or even on the web in blog posts, articles, and such.
+
+If you're interested in improving documentation, you can:
+- Fix typos and improve clarity in existing documentation
+- Add examples and tutorials
+- Improve docstrings in the code
+- Create blog posts or tutorials about using mrestimator
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at
+https://github.com/Priesemann-Group/mrestimator/issues.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to
+  implement.
+- Remember that this is a volunteer-driven project, and that
+  contributions are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `mrestimator` for local development.
+
+1. Fork the `mrestimator` repo on GitHub.
+
+2. Clone your fork locally:
+
+```bash
+git clone [email protected]:your_name_here/mrestimator.git
+```
+
+3. Create a virtual environment with your favorite tool. We recommend using conda:
+
+```bash
+conda create --name mrestimator-dev python=3.11
+conda activate mrestimator-dev
+```
+
+Or with venv:
+
+```bash
+python -m venv mrestimator-dev
+source mrestimator-dev/bin/activate  # On Windows: mrestimator-dev\Scripts\activate
+```
+
+4. Install the package including dev dependencies in editable mode:
+
+```bash
+cd mrestimator/
+pip install -e ".[dev]"
+```
+
+This will install:
+- The mrestimator package in development mode
+- All runtime dependencies (numpy, scipy, matplotlib)
+- Optional dependencies (numba, tqdm)
+- Development tools (pre-commit, ruff, testing tools)
+- Documentation dependencies (sphinx, sphinx-book-theme, etc.)
+
+5. Install pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+6. Create a branch for local development:
+
+```bash
+git checkout -b name-of-your-bugfix-or-feature
+```
+
+Now you can make your changes locally.
+
+7. When you're done making changes, check that your code passes the linter and formatter,
+   the tests pass, and the documentation builds correctly:
+
+```bash
+# Run linting and formatting
+make lint
+make format
+
+# Run tests
+make test
+
+# Build documentation
+make docs-build
+
+# Or preview documentation locally
+make docs-preview
+```
+
+Look inside the `Makefile` for more commands. For instance:
+- `make clean` - Remove build artifacts
+- `make check` - Run both linting and tests
+- `make all` - Run the full development cycle
+
+8. Commit your changes and push your branch to GitHub:
+
+```bash
+git add .
+git commit -m "Your detailed description of your changes."
+git push origin name-of-your-bugfix-or-feature
+```
+
+Please write clear, descriptive commit messages that explain what changes you made and why.
+
+9. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests for any new functionality.
+2. If the pull request adds functionality, the docs should be updated.
+   Put your new functionality into a function with a docstring.
+3. The pull request should work for Python 3.10, 3.11, and 3.12.
+4. Make sure all existing tests still pass.
+
+## Coding Standards
+
+### Code Style
+
+We use `ruff` for code formatting and linting. The configuration is in `pyproject.toml`.
+Run `make format` to automatically format your code and `make lint` to check for issues.
+
+### Documentation Style
+
+- Use NumPy-style docstrings for functions and classes
+- Include examples in docstrings where helpful
+- Keep line length to 88 characters (enforced by ruff)
+
+### Testing
+
+- Write tests for new functionality
+- Use pytest for testing
+- Place tests in the `tests/` directory
+- Test file names should start with `test_`
+
+## Development Environment
+
+### Dependencies
+
+The development environment includes:
+
+**Core dependencies:**
+- numpy (>=1.11)
+- scipy (>=1.0.0)
+- matplotlib (>=1.7.0)
+
+**Optional runtime dependencies:**
+- numba (>=0.44) - for performance improvements
+- tqdm - for progress bars
+
+**Development tools:**
+- pre-commit - for git hooks
+- ruff - for linting and formatting
+- pytest - for testing
+
+**Documentation tools:**
+- sphinx - documentation generator
+- sphinx-book-theme - modern documentation theme
+- myst-parser - Markdown support in docs
+- nbsphinx - Jupyter notebook support
+
+### Performance Considerations
+
+When running on clusters or in distributed environments, you may need to control
+thread usage. Set these environment variables:
+
+```bash
+export OPENBLAS_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+export NUMEXPR_NUM_THREADS=1
+export OMP_NUM_THREADS=1
+export NUMBA_NUM_THREADS=1
+```
+
+## Questions?
+
+If you have questions about contributing, feel free to:
+- Open an issue on GitHub
+- Contact the maintainers directly
+- Join discussions in existing issues
+
+Thank you for contributing to Mr. Estimator!