Metrologic

    A scientific measurement and quality-engineering library covering statistical process control, measurement science, process capability, probability analysis, and data analytics.
    
    **Version:** 0.0.1.0.1.2 | **Python:** ≥ 3.10 | **License:** MIT
    
    ---
    
    ## Overview
    
    Metrologic provides a unified Python interface for:
    
    - **Measurement science** — typed physical quantities with unit conversion (Pint), uncertainty tracking, and traceability
    - **Statistical process control (SPC)** — all major control chart types plus run-rules evaluation
    - **Process quality tools** — ANOVA, capability (Cp/Cpk/Pp/Ppk), Gage R&R, DOE, test planning
    - **Probability analysis** — fitting 23 distributions, AIC/BIC ranking, CDF/quantile queries
    - **Statistical analysis** — metrics, multi-series comparison, regression, data profiling
    - **Data analytics** — technical indicators, financial pattern recognition, visual color analysis
    
    ---
    
    ## Installation
    
    ```bash
    uv pip install metrologic
    # or
    pip install metrologic
    ```
    
    ---
    
    ## Module Status
    
    ### Measurement Domains (`metrologic.measurements.domains`)
    
    All nine physical measurement dimensions are implemented:
    
    | Domain | Classes | Status |
    |--------|---------|--------|
    | **Size** | `Length`, `Diameter` | ✅ Full — meters, mm, inches, feet; radius/circumference/area |
    | **Mass** | `Mass` | ✅ Full — kg, grams, pounds |
    | **Temperature** | `Temperature` | ✅ Full — Celsius, Fahrenheit, Kelvin |
    | **Electrical** | `ElectricalCurrent`, `Voltage` | ✅ Full — amperes, milliamperes; volts, mV, kV |
    | **Fluid** | `Pressure`, `Volume` | ✅ Full — pascal/bar/psi; liter/gallon/m³/ft³/in³ |
    | **Time** | `Time`, `Duration`, `Frequency` | ✅ Full — ns→years; HMS formatting; period↔frequency; ω |
    | **Movement** | `Speed`, `Velocity`, `Acceleration`, `AngularVelocity` | ✅ Full — m/s, km/h, mph, knots, Mach; vector components; g-force; RPM↔rad/s |
    | **Color** | `Color` | ✅ Full — RGB, HSV, HSL, CMYK, XYZ, L\*a\*b\*, YIQ, YUV; ΔE; luminance; contrast ratio |
    | **Finance** | `Money`, `Price`, `Rate`, `ExchangeRate` | ✅ Full — 20 ISO currencies + crypto + commodities; unit price; rate application; FX conversion |
    
    All domain classes extend the `Measurement` base which provides:
    - Pint-based unit conversion
    - Uncertainty and quality tracking
    - Instrument / operator / environment context
    - Statistical summary of repetitions
    - Tolerance checking and relative error
    
    ---
    
    ### Statistical Process Control (`metrologic.controls`)
    
    | Module | Coverage | Status |
    |--------|----------|--------|
    | `control.py` | I-MR, Xbar-R, Xbar-S (variables); p, np, c, u (attributes) | ✅ |
    | `ewmacusum.py` | EWMA, CUSUM, combined EWMA-CUSUM | ✅ |
    | `laney.py` | Laney p′, u′ (overdispersion correction) | ✅ |
    | `phases.py` | Phase I / Phase II analysis | ✅ |
    | `rules.py` | Western Electric & Nelson run rules | ✅ |
    
    ---
    
    ### Process Quality Tools (`metrologic.process`)
    
    | Module | Capability | Status |
    |--------|-----------|--------|
    | `anova.py` | One-way ANOVA, effect sizes (η², ω²), assumption tests | ✅ |
    | `capability.py` | Cp, Cpk, Pp, Ppk, Cpm (Taguchi); one- and two-sided | ✅ |
    | `doe.py` | Full factorial, central composite, Box-Behnken, Plackett-Burman | ✅ |
    | `gagestudy.py` | Gage R&R (crossed/nested), ANOVA & ranges methods | ✅ |
    | `testplans.py` | Sample size, sequential, adaptive, reliability tests | ✅ |
    
    ---
    
    ### Probability Analysis (`metrologic.probabilities`)
    
    Fits and ranks 23 distributions (17 continuous + 6 discrete) by AIC/BIC. Supports MLE, KS goodness-of-fit, CDF queries, and quantile lookups.
    
    **Continuous:** normal, lognormal, exponential, gamma, Weibull (min/max), beta, uniform, triangular, Student-t, Cauchy, Laplace, logistic, Gumbel (left/right), Pareto  
    **Discrete:** Bernoulli, Binomial, Poisson, Geometric, Negative Binomial, Hypergeometric
    
    ---
    
    ### Statistical Analysis (`metrologic.stats`)
    
    | Module | Capability | Status |
    |--------|-----------|--------|
    | `metrics.py` | Descriptive, error, regression, classification, financial metrics | ✅ |
    | `comparison.py` | Paired/independent tests, Bland-Altman, ND array comparison | ✅ |
    | `evaluation.py` | Data profiling, randomness tests, prediction evaluation | ✅ |
    | `regression.py` | `LinearRegression` (OLS, single/multi-predictor), `PolynomialRegression` (sklearn) | ✅ |
    
    ---
    
    ### Data Analytics (`metrologic.analytics`)
    
    | Module | Capability | Status |
    |--------|-----------|--------|
    | `analytics.py` | Abstract `Analyzer`, `SeriesAnalyzer`, `DataFrameAnalyzer` base classes | ✅ |
    | `evaluation.py` | Bollinger bands, EMA, MACD, RSI, SMA, clustering, linear regression | ✅ |
    | `financial.py` | Candlestick patterns, MACD/SMA/RSI signal crossovers, volatility | ✅ |
    | `electrical.py` | Ohm's law — voltage, current, resistance | ✅ |
    | `physical.py` | Volume, SpeedOfSound | ✅ |
    | `predictive.py` | `PredictionEvaluation` — accuracy, AUC, log-loss, precision/recall/F1, confusion matrix | ✅ |
    | `textual.py` | Character/word counts, average word length | ✅ |
    | `visual.py` | `ColorAnalyzer` — RGB/HSV histograms, dominant colors, finish type (requires OpenCV) | ✅ |
    
    ---
    
    ### Supporting Infrastructure
    
    | Component | Path | Status |
    |-----------|------|--------|
    | `Measurement` base class | `measurements/measurements.py` | ✅ Pint units, uncertainty, quality, repetitions |
    | `MetrologicModel` | `models.py` | ✅ Multi-series container, spec limits, describe, serialize |
    | `MeasurementCollector` | `measurements/measurements.py` | ✅ |
    | Instruments | `measurements/instruments/` | ✅ Base protocol + calipers, micrometer, scales, grids, strain, fiduciaries |
    | Environments | `measurements/environments/` | ✅ Temperature, humidity, pressure context |
    | Operators | `measurements/operators/` | ✅ Operator profiles and certifications |
    | Procedures | `measurements/methods/` | ✅ Uncertainty, MeasurementQuality, MeasurementType enums |
    | Constants | `constants.py` | ✅ Physics constants (Avogadro, Boltzmann, speed of light, etc.) |
    | CLI | `cmds/runMeasurement.py` | ✅ |
    | Tests | `test_metrologic/` | ✅ 366 tests passing |
    
    ---
    
    ## Quick Start
    
    ```python
    # Physical measurements with unit conversion
    from metrologic.measurements.domains import Length, Temperature, Speed
    
    shaft = Length(value=25.4, unit="millimeter")
    print(shaft.in_inches)      # 1.0 inch
    
    temp = Temperature(value=98.6, unit="fahrenheit")
    print(temp.in_celsius)      # 37.0 °C
    
    mach2 = Speed.from_mach(2.0)
    print(mach2.in_kilometers_per_hour)  # 2469.6 km/h
    
    # Color
    from metrologic.measurements.domains import Color
    c = Color.from_hex("#FF6B35")
    print(c.to_lab())       # CIE L*a*b*
    print(c.to_pantone())   # nearest Pantone name
    
    # Finance
    from metrologic.measurements.domains import Money, ExchangeRate
    usd = Money(1000.0, "usd")
    rate = ExchangeRate(value=0.92, base="usd", quote="eur")
    eur = rate.convert(usd)
    print(eur)   # Money(920.0000 EUR)
    
    # Time & frequency
    from metrologic.measurements.domains import Time, Frequency
    t = Time(1.5, "hour")
    print(t.in_minutes)  # 90.0 min
    f = Frequency(440.0, "hertz")   # A4 note
    print(f.period)      # Time(0.00227 s)
    print(f.angular_frequency)  # 2764.6 rad/s
    
    # Movement
    from metrologic.measurements.domains import AngularVelocity
    motor = AngularVelocity.from_rpm(1800)
    print(motor.linear_speed(radius=0.05))  # tangential speed at r=5cm
    
    # Statistical process control
    from metrologic.controls.control import ControlChartAnalyzer
    result = ControlChartAnalyzer(data).imr()
    
    # Capability analysis
    from metrologic.process.capability import CapabilityAnalyzer
    cap = CapabilityAnalyzer(data, lsl=2.45, usl=2.55).analyze()
    print(cap.result.cpk)
    
    # Probability distribution fitting
    from metrologic.probabilities.probabilities import ProbabilityModelAnalyzer
    pma = ProbabilityModelAnalyzer(data).fit_all()
    print(pma.ranked_models[:3])
    
    # Regression
    from metrologic.stats.regression import LinearRegression, PolynomialRegression
    lr = LinearRegression().fit(x, y)
    print(lr.result)
    
    pr = PolynomialRegression(degree=3).fit(x, y)
    print(pr.result.r_squared)
    
    # Composite model
    from metrologic.models import MetrologicModel
    model = MetrologicModel(name="Shaft Diameter Study")
    model.add_series("diameter", measurements, unit="mm", lsl=24.9, usl=25.1)
    print(model.describe("diameter"))
    ```
    
    ---
    
    ## Dependencies
    
    **Core (required):** numpy, scipy, pandas, scikit-learn, pint, rich  
    **Optional:** pandas-ta (technical indicators), opencv-python (visual color analysis)  
    **Internal:** kahndor (YAML config + logging), ogma
    
    ---
    
    ## Project Structure
    
    ```
    metrologic/
    ├── api.py                     # High-level Metrologic facade
    ├── metrologic.py              # MeasurementSeries, MeasurementValidator
    ├── models.py                  # MetrologicModel composite container
    ├── constants.py               # Physics constants
    ├── analytics/                 # Data analytics modules
    ├── controls/                  # SPC control charts + run rules
    ├── measurements/              # Physical measurement science
    │   ├── domains/               # Typed measurement classes (9 dimensions)
    │   ├── instruments/           # Instrument types and calibration
    │   ├── environments/          # Environmental conditions
    │   ├── operators/             # Operator profiles
    │   └── methods/               # Measurement procedures and uncertainty
    ├── probabilities/             # Distribution fitting (23 models)
    ├── process/                   # ANOVA, capability, Gage R&R, DOE, test planning
    └── stats/                     # Metrics, comparison, evaluation, regression
    ```