Incertidumbre y unidades
Alcance
Usa esta habilidad cada vez que un cálculo lleve unidades físicas o un número reportado necesite una incertidumbre. En concreto:
- convertir entre unidades, incluyendo conversiones que necesitan un contexto físico (longitud de onda a energía de fotón, masa a cantidad de sustancia, energía a temperatura);
- propagar la incertidumbre a través de un modelo de medición, con o sin entradas correlacionadas;
- construir un presupuesto de incertidumbre GUM a partir de certificados de calibración, especificaciones y datos de repetibilidad;
- elegir un factor de cobertura y decidir si
k = 2es defendible; - redondear y escribir un resultado para que el lector sepa qué significa el
±; - extraer incertidumbres de parámetros de un ajuste de curva sin descartar las correlaciones;
- revisar el código de análisis existente en busca de defectos silenciosos de unidades e incertidumbre;
- comprobar que una respuesta dimensionalmente consistente es también físicamente posible: el orden de magnitud, el grupo adimensional y el régimen que implica.
Esta habilidad cubre la metrología y las dos bibliotecas que la implementan. No cubre inferencia estadística, selección de modelos ni diseño de estudios; véanse statistical-analysis, statistical-power y experimental-design.
Versión actual e instalación
Verificado el 26 de julio de 2026:
- pint 0.25.3, publicado el 19 de marzo de 2026; requiere Python 3.11+.
- uncertainties 3.2.3, publicado el 21 de abril de 2025; requiere Python 3.8+.
- NumPy 2.5.1 y SciPy 1.18.0; ambos requieren Python 3.12+.
scipy.constantsen SciPy 1.18.0 proporciona CODATA 2022. SciPy 1.11 y anteriores proporcionaban CODATA 2018, y varios valores recomendados difieren entre ambas.
uv venv --python 3.13
source .venv/bin/activate
uv pip install "pint==0.25.3" "uncertainties==3.2.3" "numpy==2.5.1" "scipy==1.18.0"
pint-pandas y pint-xarray añaden columnas y arrays compatibles con unidades y se instalan por separado.
Flujo de trabajo no negociable
- Adjunta las unidades en la entrada y elimínalas solo en la salida. Convierte en los límites de las funciones con
ureg.wrapsom_as("unidad"), nunca en medio del cálculo. - Escribe el modelo de medición explícitamente antes de calcular nada, incluyendo correcciones cuyo valor estimado sea cero. Una corrección omitida en el modelo deja su incertidumbre fuera del presupuesto.
- Proporciona a cada entrada cuatro cosas: una estimación, una incertidumbre típica, la distribución de la que proviene la incertidumbre y sus grados de libertad.
- Convierte las declaraciones Tipo B con el divisor correcto. La incertidumbre expandida de un certificado se divide por su
kdeclarado; los límites rectangulares se dividen porsqrt(3). - Identifica las correlaciones antes de combinar. Las entradas calibradas contra el mismo patrón, medidas en el mismo instrumento o extraídas del mismo ajuste están correlacionadas.
- Calcula los coeficientes de sensibilidad y lee el presupuesto a partir de
c_i * u(x_i)en lugar de las incertidumbres brutas. - Verifica la linealización. Ejecuta Monte Carlo junto con el marco GUM y aplica la comparación de la cláusula 8 de la JCGM 101. Reporta el resultado de Monte Carlo cuando falle.
- Elige
ka partir de los grados de libertad efectivos, no por costumbre. - Redondea primero la incertidumbre y luego el valor al mismo decimal.
- Declara qué es el
±— estándar o expandido, conk, la probabilidad de cobertura y el método. - Verifica la magnitud antes de informar. Un resultado dimensionalmente consistente puede seguir siendo imposible. Compáralo con una escala conocida o un grupo adimensional y confirma que todas las suposiciones en las que te basaste siguen siendo válidas en ese régimen.
Fallos que esta habilidad existe para prevenir
Cada uno de los siguientes se ejecuta sin error y produce un número plausible.
Una unidad eliminada a una escala desconocida
length = (12.7 * ureg.mm).magnitude # 12.7 -- ¿de qué?
length = (12.7 * ureg.mm).m_as("m") # 0.0127 metros, declarado
.magnitude devuelve lo que la cantidad tuviera en ese momento. Nombra la unidad en el punto de extracción, siempre.
Aritmética con temperaturas offset
Q(20, "degC") + Q(5, "degC") # OffsetUnitCalculusError -- correctamente rechazado
Q(20, "degC") + Q(5, "delta_degC") # 25 grado_Celsius
Q(25, "degC") - Q(20, "degC") # 5 delta_degree_Celsius
Celsius y Fahrenheit son escalas de intervalo. Una incertidumbre sobre una temperatura es siempre una diferencia y pertenece a una unidad delta_: convertir 20 ± 0.5 degC a Fahrenheit da 68 degF ± 0.9 delta_degF, dos conversiones diferentes en una sola línea.
Unidades logarítmicas que se suman multiplicando
Q(10, "dBm") + Q(10, "dBm") # 0.0001 kilogram**2 * meter**4 / second**6
Eso es 10 mW × 10 mW, no 20 mW ni 13 dBm. Nada lanza una excepción. Convierte a una unidad lineal antes de cualquier aritmética.
Una correlación destruida por un viaje de ida y vuelta
x = ufloat(1.0, 0.1)
x - x # 0.0+/-0
x - ufloat(x.nominal_value, x.std_dev) # 0.00+/-0.14
Reconstruir una variable a partir de su valor nominal y desviación estándar crea una variable independiente. También lo hace cualquier serialización que pase a través de un par de flotantes. Usa correlated_values(valores, matriz_de_covarianza) para reconstruir un conjunto correlacionado.
Una matriz de covarianza reescalada silenciosamente
popt, pcov = curve_fit(f, x, y, sigma=sigma) # por defecto
popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=True)
El comportamiento por defecto reescala pcov por el chi-cuadrado reducido, por lo que las incertidumbres de los parámetros absorben la bondad del ajuste y coinciden con lo que se obtendría sin pasar ningún sigma. En un ajuste lineal sintético los dos dan [0.0364, 0.2154] y [0.0477, 0.2820] — una diferencia del 31%. Pasa absolute_sigma=True siempre que sigma contenga incertidumbres típicas reales.
Una linealización que nunca se verificó
Para y = x² con x = 1.0 ± 0.5, el marco GUM da y = 1.0, u_c = 1.0 y un intervalo del 95% de [-0.96, 2.96] — en su mayoría negativo, para una cantidad al cuadrado. Monte Carlo da una media de 1.25, u_c = 1.06 y un intervalo del 95% más corto de [0, 3.32]. Nada en una biblioteca de propagación lineal te dirá que esto ha ocurrido.
CLI locales incluidos
Todos los ayudantes se ejecutan sin conexión, rechazan URLs y enlaces simbólicos, limitan sus entradas, escriben la salida atómicamente con permisos privados y se niegan a sobrescribir sin --force.
python skills/uncertainty-and-units/scripts/propagate_uncertainty.py --help
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --help
python skills/uncertainty-and-units/scripts/format_result.py --help
python skills/uncertainty-and-units/scripts/convert_units.py --help
python skills/uncertainty-and-units/scripts/audit_units.py --help
python skills/uncertainty-and-units/scripts/check_plausibility.py --help
propagate_uncertainty.py
Ejecuta ambos métodos de propagación en el mismo modelo y aplica la prueba de validación de la cláusula 8 de la JCGM 101.
python skills/uncertainty-and-units/scripts/propagate_uncertainty.py \
--expression "m / (pi * (d / 2) ** 2 * h)" \
--variable "m=250.0,0.05" \
--variable "d=20.0,0.02,rectangular" \
--variable "h=40.0,0.05,rectangular" \
--measurand densidad --unit "g/cm3" --format markdown
Cada --variable es nombre=valor,incertidumbre_típica[,distribución[,gdl]], donde la distribución es normal, rectangular, triangular, arcsine o exact y controla solo el muestreo de Monte Carlo. Las correlaciones se añaden como --correlation "a,b=0.9". Un archivo --spec JSON contiene el mismo modelo para cualquier cosa de larga duración.
La expresión se analiza en un árbol de sintaxis abstracta y se reduce mediante un recorrido explícito sobre + - * / ** y una lista fija de funciones. Nunca se compila ni ejecuta.
El informe proporciona la estimación, u_c, los coeficientes de sensibilidad, el presupuesto en porcentaje, los grados de libertad efectivos, k, U, ambos intervalos de cobertura de Monte Carlo y el veredicto sobre si se puede reportar el resultado linealizado.
uncertainty_budget.py
Combina componentes tal como se expresan en los certificados y hojas de datos.
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --template > budget.json
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --spec budget.json --format markdown
Cada componente nombra una distribución que fija su divisor — expanded divide por su coverage_factor, rectangular por sqrt(3), triangular por sqrt(6), arcsine por sqrt(2), normal por 1 — con una sensibilidad, gdl y relative: true opcionales. La herramienta calcula u_c, los grados de libertad efectivos de Welch-Satterthwaite, k a partir de la distribución t y U, y advierte cuando un componente Tipo A no tiene grados de libertad, cuando nu_eff es lo suficientemente pequeño como para que k = 2 sea incorrecto, cuando un componente domina y cuando un componente Tipo B declarado normal es probablemente una incertidumbre expandida sin dividir.
format_result.py
python skills/uncertainty-and-units/scripts/format_result.py \
--value 12.34567 --uncertainty 0.02345 --unit mm \
--coverage-factor 2.26 --coverage-probability 0.95
Devuelve 12.346 ± 0.023 mm, 12.346(23) mm, las formas científica y LaTeX, y la oración que debe acompañar al número. Advierte cuando se solicita un dígito significativo para una incertidumbre que comienza en 1 o 2, y cuando la incertidumbre supera la estimación.
convert_units.py
python skills/uncertainty-and-units/scripts/convert_units.py \
--value 532 --unit nm --to eV --context spectroscopy --uncertainty 0.5
python skills/uncertainty-and-units/scripts/convert_units.py \
--value 1.0 --unit g --to mol --context chemistry --context-parameter "mw=180.156 g/mol"
Propaga la incertidumbre a través de la derivada local de la conversión, lo cual es importante porque las conversiones de contexto son recíprocas en lugar de proporcionales. Nombra el contexto en el mensaje de error cuando una conversión lo necesita y marca las unidades offset y logarítmicas. --list-contexts muestra lo que define el registro.
audit_units.py
Revisión estática del código de análisis existente. Analiza, nunca importa ni ejecuta.
python skills/uncertainty-and-units/scripts/audit_units.py \
--input analysis.py --format markdown --fail-on medium
| Regla | Severidad | Detecta |
|---|---|---|
UNIT001 | media | un segundo UnitRegistry en un módulo — ValueError entre registros |
UNIT002 | media | unidades de temperatura offset sin ninguna unidad delta_ |
UNIT003 | alta | .magnitude sin un .to(...) o .m_as(...) precedente |
UNIT004 | media | unidades logarítmicas, cuyo + multiplica |
UNC001 | alta | curve_fit sin absolute_sigma |
UNC002 | media | np.std / np.var sin ddof |
UNC003 | media | funciones de math o numpy en un módulo que usa uncertainties |
UNC004 | alta | un ufloat reconstruido a partir de .nominal_value y .std_dev |
CONST001 | baja | un literal dentro del 0.1% de una constante CODATA |
El estado de salida es 1 cuando un hallazgo cumple --fail-on (por defecto high), lo que lo hace utilizable como comprobación de pre-commit o CI.
Las reglas son heurísticas, por lo que un falso positivo se suprime con un comentario directivo — al final de la línea para cubrir su propia línea, o solo en una línea para cubrir la siguiente:
value = quantity.magnitude # audit-units: ignore UNIT003 -- ya convertido aguas arriba
# audit-units: ignore UNC003 -- el argumento aquí es un array de flotantes simple
scaled = np.log10(counts)
# audit-units: ignore-file CONST001 cubre todo un módulo, y no nombrar ninguna regla suprime todas. Las supresiones se cuentan en el informe en lugar de ocultarse, por lo que un archivo que silencia todo sigue diciéndolo.
check_plausibility.py
La consistencia dimensional no es posibilidad física. Una celda de 2 m de diámetro y un número de Reynolds de 4e7 en un capilar pasan todas las comprobaciones de unidades. Esta herramienta prueba un conjunto de cantidades contra grupos adimensionales, escalas características y bandas de magnitud seleccionadas, y verifica la dimensionalidad de cada fórmula antes de reportar un número.
python skills/uncertainty-and-units/scripts/check_plausibility.py \
--quantity "density=1060 kg/m**3" --quantity "velocity=0.5 mm/s" \
--quantity "length=8 um" --quantity "viscosity=3.5 mPa*s" \
--group reynolds --format markdown
# Re = 0.001211 -- laminar (tubería circular, longitud = diámetro)
python skills/uncertainty-and-units/scripts/check_plausibility.py \
--quantity "diameter=2 m" --band "eukaryotic_cell_diameter=diameter"
# inverosímil: 4.3 décadas fuera del rango de 5-100 um
--group evalúa uno de los 14 grupos adimensionales y nombra el régimen en el que sitúa el sistema; --scale calcula una escala característica como el tiempo de difusión, la longitud de Debye o la velocidad de sedimentación de Stokes; --band compara una cantidad proporcionada con un rango observado. --list imprime todo el catálogo con las entradas que necesita cada fórmula.
Las constantes físicas (k_B, N_A, R_gas, g_earth, y el resto) están disponibles para cada fórmula sin ser proporcionadas, y se leen de scipy.constants en tiempo de ejecución en lugar de escribirse como literales, por lo que siguen la versión de CODATA que SciPy incluya.
La verificación dimensional es el punto. Pasar una viscosidad cinemática donde la fórmula necesita una dinámica — ambas llamadas "viscosity", ambas tabuladas para el agua, diferenciándose por un factor de ρ — se rechaza antes de que se calcule cualquier número:
error: viscosity must have dimensionality [mass] / ([length] * [time]),
but m²/s is [length] ** 2 / [time]
El estado de salida es 1 cuando el veredicto cumple --fail-on (por defecto implausible; un valor dentro de una década de una banda es questionable). Los umbrales son convenciones con bordes suaves y asumen la geometría para la que se ajustó su correlación; véase references/plausibility-scales.md para la longitud característica a usar en cada caso.
Elegir un método de propagación
| Situación | Método |
|---|---|
| Modelo lineal o casi lineal, entradas aproximadamente normales, gdl grandes | Marco GUM solo |
| Cualquier no linealidad en ±2u de una entrada | ejecutar ambos, aplicar la prueba de la cláusula 8 |
| Incertidumbre relativa superior a ~20% en cualquier entrada | Monte Carlo, rechazar el marco GUM si falla la prueba de la cláusula 8 |
| Distribuciones de entrada no normales (rectangular, triangular, arcoseno) | Monte Carlo |
| Entradas correlacionadas con modelo no lineal | Monte Carlo con muestreo de cópula |
| Modelo analíticamente diferenciable, gdl grandes, lineal | Marco GUM, validar con Monte Carlo |
| Se necesita el intervalo de cobertura más corto (por ejemplo, cantidad acotada) | Monte Carlo, informar el intervalo de densidad más alta |
| Presupuesto de incertidumbre a partir de certificados | uncertainty_budget.py primero, luego propagate_uncertainty.py con el modelo completo |
Referencias
- BIMP, Evaluación de datos de medición — Guía para la expresión de la incertidumbre de medición (GUM). JCGM 100:2008.
- BIMP, Evaluación de datos de medición — Suplemento 1 del GUM: Propagación de distribuciones mediante el método de Monte Carlo. JCGM 101:2008.
- BIMP, Evaluación de datos de medición — Suplemento 2 del GUM: Modelos con cualquier número de cantidades de salida. JCGM 102:2011.
- The
uncertaintiespackage. Lebigot, E. O. https://uncertainties-python-package.readthedocs.io/ pint: Python packaging for physical units. https://pint.readthedocs.io/- CODATA Valores recomendados de constantes físicas fundamentales. 2022. https://physics.nist.gov/cuu/Constants/