Metadata-Version: 2.4
Name: mespy
Version: 1.1.4
Summary: Toolbox Python per l'analisi dei dati di laboratorio
Author-email: Giancarmine Sparso <giancarminesparso@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/giancarmine-sparso/mespy
Project-URL: Repository, https://github.com/giancarmine-sparso/mespy
Project-URL: Issues, https://github.com/giancarmine-sparso/mespy/issues
Keywords: physics,statistics,data analysis,laboratory,mechanics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: sphinx>=9.1.0; extra == "dev"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "dev"
Requires-Dist: myst-nb>=1.3.0; extra == "dev"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "dev"
Requires-Dist: sphinx-intl; extra == "dev"
Dynamic: license-file

# mespy

> Documentation: [giancarmine-sparso.github.io/mespy](https://giancarmine-sparso.github.io/mespy/index.html#)

Small Python toolbox for mechanics laboratory data analysis.

`mespy` started as a set of helper functions that kept reappearing across mechanics lab notebooks and classroom scripts: loading CSV measurements, computing descriptive and weighted statistics, plotting histograms, and running linear fits with uncertainties. The library brings those recurring tasks together into a single typed package with a small public API that is easy to use in notebooks, scripts, and teaching material.

## What It Provides

- CSV loading with explicit missing-data policies
- Descriptive and weighted statistics for one-dimensional data
- Histogram plotting for quick exploratory analysis
- Weighted linear fitting with a typed result object
- Clear validation errors instead of silent `nan` propagation

## Public API

The root package exports:

- `load_csv`
- `median`
- `weighted_mean`
- `variance`
- `covariance`
- `standard_deviation`
- `histogram`
- `lin_fit`

The root namespace stays intentionally small. Additional public types, such as `mespy.fit_utils.LinearFitResult`, live in submodules.

## Installation

`mespy` requires Python `>= 3.12`.

```bash
pip install git+https://github.com/giancarmine-sparso/mespy.git
```

## Development Setup

To set up a local development environment:

### Unix / macOS

```bash
git clone https://github.com/giancarmine-sparso/mespy
cd mespy
make setup
```

To activate the virtual environment manually:

```bash
source .venv/bin/activate
```

### Windows

```cmd
git clone https://github.com/giancarmine-sparso/mespy
cd mespy
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
```

## Documentation

The Sphinx source lives in `docs/source`, and the generated site is written to `docs/build/html`.

Build the documentation with:

```bash
make docs
```

The generated site includes both English and Italian outputs, with English as the default landing page. The documentation also includes usage examples for the available functions. Complete usage workflows and notebooks are available in `docs/source/examples`.

## Project Structure

```text
mespy/
├── .github/
│   └── workflows/          # automation for documentation publishing
├── data/
│   └── reference/          # reference datasets used by tests and examples
├── docs/
│   ├── source/             # Sphinx source, examples, and translations
│   ├── Makefile
│   └── make.bat
├── figures/                # exported example figures
├── src/
│   └── mespy/              # library package
├── tests/                  # pytest suite
├── tools/                  # release and smoke-test helpers
├── LICENSE
├── Makefile                # local setup, testing, release, and docs tasks
├── pyproject.toml          # package metadata and dependencies
├── README.md
└── uv.lock
```
