ezsnake 0.1.0__tar.gz

ezsnake-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

ezsnake-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14.3

ezsnake-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ezsnake
+Version: 0.1.0
+Summary: ezsnake is a Python package for working with NetCDF files, a framework for working with python-docx, openpyxl, and also MATLAB datenum conversions into pandas Datetime format, providing an easy-to-use interface for data manipulation and analysis.
+Author-email: "Fernando Bello Fuentes (BelloDev)" <fernandojbf123@gmail.com>
+License-File: licence.md
+Requires-Python: >=3.11
+Requires-Dist: netcdf4>=1.7.4
+Requires-Dist: numpy>=2.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: scipy>=1.17.1
+Description-Content-Type: text/markdown
+
+
+# ezsnake
+
+Librería de utilidades científicas en Python para NetCDF, manipulación avanzada de Word, utilidades geográficas y funciones tipo MATLAB.
+
+---
+
+## 📦 Módulos principales
+
+### 1. NetCDF (`ezsnake.netcdf`)
+Lectura, exploración y escritura de archivos NetCDF usando netCDF4.
+
+**Funciones principales:**
+- `load_nc(ruta, variable=None)`
+- `view_att(ruta, variable=None)`
+- `dict2nc(ruta, data)`
+
+### 2. Word Template Writer (`ezsnake.word_template_writer`)
+Automatización avanzada de plantillas Word (.docx): inserción de figuras, referencias cruzadas, reemplazo de variables, tablas y documentos externos.
+
+**API pública:**
+- `insertar_figuras_en_plantilla(doc, diccionario_de_reemplazos)`
+- `insertar_referencias_cruzadas_en_plantilla(doc, diccionario_de_reemplazos)`
+- `reemplazar_texto_en_plantilla(doc, diccionario_de_reemplazos)`
+- `insertar_documento_externo_en_plantilla(doc, diccionario_de_reemplazos)`
+- `rellenar_tablas_en_plantilla(doc, diccionario_de_reemplazos)`
+- `reemplazar_variables_en_tablas(doc, diccionario_de_reemplazos)`
+
+### 3. MATLAB-like (`ezsnake.matlab`)
+Funciones científicas compatibles con MATLAB para estadística, distribuciones y conversión de fechas:
+
+**Funciones principales:**
+- `betacdf`, `betafit`, `betainv`, `betalike`, `betapdf`, `betaln`
+- `datenum_to_datetime`, `datenum_to_pd_datetime`
+- `distchck`, `hist`
+- `logncdf`, `lognfit`, `lognlike`, `lognpdf`, `lognrnd`, `lognstat`
+- `normcdf`, `normfit`, `normlike`, `normpdf`, `norminv`
+
+### 4. Utilidades (`ezsnake.utils`)
+Funciones para cálculos geográficos, manipulación de datos y utilidades varias:
+
+**Funciones principales:**
+- `uv2polar(u, v)`
+- `polar2uv(dir_deg, spd)`
+- `grados_a_km_lat(delta_lat)`
+- `grados_a_km_lon(delta_lon, latitud)`
+- `distancia_entre_dos_puntos(lon2, lat2, lon1, lat1, unidad='km')`
+- `calcular_tiempo_de_viaje(lon2, lon1, lat2, lat1, velocidad, unidad='km')`
+- `timestamp_a_texto_espanol(fecha, mes_y_anio)`
+- `get_excel_variables_name(df_datos_documento)`
+- `get_excel_variable_values(df_datos_documento, nombre_variable)`
+
+---
+
+## 🚀 Instalación
+
+Desde PyPI:
+```bash
+pip install ezsnake
+```
+
+Desde el repositorio (editable):
+```bash
+pip install -e .
+```
+
+---
+
+## 📋 Requerimientos
+
+- Python >= 3.11
+- netcdf4 >= 1.7.4
+- numpy >= 2.0
+- openpyxl >= 3.1
+- pandas >= 2.0
+- python-docx >= 1.1
+- scipy >= 1.17.1
+
+---
+
+## 📝 Ejemplo de uso
+
+```python
+from ezsnake.netcdf import load_nc, view_att, dict2nc
+
+# Cargar todas las variables de un archivo NetCDF
+data = load_nc('archivo.nc')
+
+# Cargar una variable específica
+temperatura = load_nc('archivo.nc', 'temperature')
+
+# Ver atributos de una variable
+attrs = view_att('archivo.nc', 'temperature')
+
+# Crear un archivo NetCDF desde un diccionario
+data_dict = {
+    'global_atributes': {'title': 'Mi archivo NetCDF'},
+    'temperature': {
+        'value': np.array([[1, 2], [3, 4]]),
+        'dims': ['time', 'lat'],
+        'units': 'Celsius'
+    }
+}
+dict2nc('nuevo_archivo.nc', data_dict)
+```
+
+---
+
+## 👤 Autor y créditos
+
+***********
+by BelloDev  
+agregado 2026/05/25  
+ultima revision 2026/05/25
+***********
+

ezsnake-0.1.0/README.md

@@ -0,0 +1,116 @@
+
+# ezsnake
+
+Librería de utilidades científicas en Python para NetCDF, manipulación avanzada de Word, utilidades geográficas y funciones tipo MATLAB.
+
+---
+
+## 📦 Módulos principales
+
+### 1. NetCDF (`ezsnake.netcdf`)
+Lectura, exploración y escritura de archivos NetCDF usando netCDF4.
+
+**Funciones principales:**
+- `load_nc(ruta, variable=None)`
+- `view_att(ruta, variable=None)`
+- `dict2nc(ruta, data)`
+
+### 2. Word Template Writer (`ezsnake.word_template_writer`)
+Automatización avanzada de plantillas Word (.docx): inserción de figuras, referencias cruzadas, reemplazo de variables, tablas y documentos externos.
+
+**API pública:**
+- `insertar_figuras_en_plantilla(doc, diccionario_de_reemplazos)`
+- `insertar_referencias_cruzadas_en_plantilla(doc, diccionario_de_reemplazos)`
+- `reemplazar_texto_en_plantilla(doc, diccionario_de_reemplazos)`
+- `insertar_documento_externo_en_plantilla(doc, diccionario_de_reemplazos)`
+- `rellenar_tablas_en_plantilla(doc, diccionario_de_reemplazos)`
+- `reemplazar_variables_en_tablas(doc, diccionario_de_reemplazos)`
+
+### 3. MATLAB-like (`ezsnake.matlab`)
+Funciones científicas compatibles con MATLAB para estadística, distribuciones y conversión de fechas:
+
+**Funciones principales:**
+- `betacdf`, `betafit`, `betainv`, `betalike`, `betapdf`, `betaln`
+- `datenum_to_datetime`, `datenum_to_pd_datetime`
+- `distchck`, `hist`
+- `logncdf`, `lognfit`, `lognlike`, `lognpdf`, `lognrnd`, `lognstat`
+- `normcdf`, `normfit`, `normlike`, `normpdf`, `norminv`
+
+### 4. Utilidades (`ezsnake.utils`)
+Funciones para cálculos geográficos, manipulación de datos y utilidades varias:
+
+**Funciones principales:**
+- `uv2polar(u, v)`
+- `polar2uv(dir_deg, spd)`
+- `grados_a_km_lat(delta_lat)`
+- `grados_a_km_lon(delta_lon, latitud)`
+- `distancia_entre_dos_puntos(lon2, lat2, lon1, lat1, unidad='km')`
+- `calcular_tiempo_de_viaje(lon2, lon1, lat2, lat1, velocidad, unidad='km')`
+- `timestamp_a_texto_espanol(fecha, mes_y_anio)`
+- `get_excel_variables_name(df_datos_documento)`
+- `get_excel_variable_values(df_datos_documento, nombre_variable)`
+
+---
+
+## 🚀 Instalación
+
+Desde PyPI:
+```bash
+pip install ezsnake
+```
+
+Desde el repositorio (editable):
+```bash
+pip install -e .
+```
+
+---
+
+## 📋 Requerimientos
+
+- Python >= 3.11
+- netcdf4 >= 1.7.4
+- numpy >= 2.0
+- openpyxl >= 3.1
+- pandas >= 2.0
+- python-docx >= 1.1
+- scipy >= 1.17.1
+
+---
+
+## 📝 Ejemplo de uso
+
+```python
+from ezsnake.netcdf import load_nc, view_att, dict2nc
+
+# Cargar todas las variables de un archivo NetCDF
+data = load_nc('archivo.nc')
+
+# Cargar una variable específica
+temperatura = load_nc('archivo.nc', 'temperature')
+
+# Ver atributos de una variable
+attrs = view_att('archivo.nc', 'temperature')
+
+# Crear un archivo NetCDF desde un diccionario
+data_dict = {
+    'global_atributes': {'title': 'Mi archivo NetCDF'},
+    'temperature': {
+        'value': np.array([[1, 2], [3, 4]]),
+        'dims': ['time', 'lat'],
+        'units': 'Celsius'
+    }
+}
+dict2nc('nuevo_archivo.nc', data_dict)
+```
+
+---
+
+## 👤 Autor y créditos
+
+***********
+by BelloDev  
+agregado 2026/05/25  
+ultima revision 2026/05/25
+***********
+

ezsnake-0.1.0/licence.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BelloDev [PhD. Fernando Bello Fuentes]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ezsnake-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ezsnake"]
+
+[project]
+name = "ezsnake"
+version = "0.1.0"
+description = "ezsnake is a Python package for working with NetCDF files, a framework for working with python-docx, openpyxl, and also MATLAB datenum conversions into pandas Datetime format, providing an easy-to-use interface for data manipulation and analysis."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "netcdf4>=1.7.4",
+    "numpy>=2.0",
+    "openpyxl>=3.1",
+    "pandas>=2.0",
+    "python-docx>=1.1",
+    "scipy>=1.17.1",
+]
+
+authors = [
+    { name = "Fernando Bello Fuentes (BelloDev)", email = "fernandojbf123@gmail.com" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+]

ezsnake-0.1.0/src/ezsnake/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+__author__ = "BelloDev"

ezsnake-0.1.0/src/ezsnake/matlab/__init__.py

@@ -0,0 +1,42 @@
+from .betacdf import betacdf
+from .betafit import betafit
+from .betainv import betainv
+from .betalike import betalike
+from .betapdf import betapdf
+from .datenum_converter import (datenum_to_datetime, datenum_to_pd_datetime)
+from .distchck import distchck
+from .hist import hist
+from .logncdf import logncdf
+from .lognfit import lognfit
+from .lognlike import lognlike
+from .lognpdf import lognpdf
+from .lognrnd import lognrnd
+from .lognstat import lognstat
+from .normcdf import normcdf
+from .normfit import normfit
+from .normlike import normlike
+from .normpdf import normpdf
+
+__all__ = [
+    "betacdf",
+    "betafit",
+    "betainv",
+    "betalike",
+    "betapdf",
+    "datenum_converter",
+    "datenum_to_pd_datetime",
+    "distchck",
+    "hist",
+    "logncdf",
+    "lognfit",
+    "lognlike",
+    "lognpdf",
+    "lognrnd",
+    "lognstat",
+    "normcdf",
+    "normfit",
+    "normlike",
+    "normpdf"
+]
+
+__author__ = "BelloDev"

ezsnake-0.1.0/src/ezsnake/matlab/betacdf.py

@@ -0,0 +1,43 @@
+import numpy as np
+from scipy.stats import beta
+
+def betacdf(x, a, b, tail='lower'):
+    """
+    BETACDF Beta cumulative distribution function.
+    P = BETACDF(X,A,B) returns the beta cumulative distribution
+    function with parameters A and B at the values in X.
+
+    The size of P is the common size of the input arguments. A scalar input  
+    functions as a constant matrix of the same size as the other inputs.    
+
+    BETAINC does the computational work.
+
+    P = BETACDF(X,A,B,'upper') returns the upper tail probability of the beta 
+    distribution function with parameters A and B at the values in X.
+
+    See also BETAFIT, BETAINV, BETALIKE, BETAPDF, BETARND, BETASTAT, CDF,
+             BETAINC.
+
+    Reference:
+       [1]  M. Abramowitz and I. A. Stegun, "Handbook of Mathematical
+       Functions", Government Printing Office, 1964, 26.5.
+    """
+    x = np.asarray(x)
+    a = np.asarray(a)
+    b = np.asarray(b)
+    # Broadcast to common shape
+    x, a, b = np.broadcast_arrays(x, a, b)
+    p = np.full_like(x, np.nan, dtype=float)
+    okAB = (0 < a) & (a < np.inf) & (0 < b) & (b < np.inf)
+    k = okAB & (0 <= x) & (x <= 1)
+    if tail == 'upper':
+        p[okAB & (x <= 0)] = 1.0
+        p[okAB & (x >= 1)] = 0.0
+        if np.any(k):
+            p[k] = beta.sf(x[k], a[k], b[k])
+    else:
+        p[okAB & (x < 0)] = 0.0
+        p[okAB & (x > 1)] = 1.0
+        if np.any(k):
+            p[k] = beta.cdf(x[k], a[k], b[k])
+    return p

ezsnake-0.1.0/src/ezsnake/matlab/betafit.py

@@ -0,0 +1,132 @@
+import numpy as np
+from scipy import stats, optimize
+from scipy.special import gammaln, psi, logsumexp
+from .betalike import betalike
+from .norminv import norminv
+
+def betafit(x, alpha=0.05):
+    """
+    BETAFIT Parameter estimates and confidence intervals for beta distributed data.
+    BETAFIT(X) Returns the maximum likelihood estimates of the parameters
+    of the beta distribution given the data in the vector, X.
+    
+    [PHAT, PCI] = BETAFIT(X,ALPHA) gives MLEs and 100(1-ALPHA) percent
+    confidence intervals given the data. By default, the optional parameter
+    ALPHA = 0.05 corresponding to 95% confidence intervals.
+    
+    The beta distribution is defined on the open interval (0,1).  However, it
+    is sometimes also necessary to fit a beta distribution to data that
+    include exact zeros or ones.  For such data, the beta likelihood function
+    is unbounded, and standard maximum likelihood estimation is not possible.
+    In that case, BETAFIT maximizes a modified likelihood that incorporates
+    the zeros or ones by treating them as if they were values that have been
+    left-censored at SQRT(REALMIN) or right-censored at 1-EPS/2, respectively.
+    
+    See also BETACDF, BETAINV, BETALIKE, BETAPDF, BETARND, BETASTAT, MLE.
+    
+    Reference:
+       (1994) Hahn, Gerald J., and Shapiro, Samuel, S. "Statistical Models in
+       Engineering", Wiley Classics Library, John Wiley & Sons, p. 95.
+    """
+    
+    alpha = float(alpha)
+    
+    if len(x) == 0:
+        phat = np.array([np.nan, np.nan])
+        pci = np.array([[np.nan, np.nan], [np.nan, np.nan]])
+        return phat, pci
+    
+    x = np.asarray(x).flatten()
+    
+    # Remove missing values from the data
+    x = x[~np.isnan(x)]
+    
+    # Cannot fit data outside of the closed interval [0,1], or constant data
+    xmin = np.min(x)
+    xmax = np.max(x)
+    
+    if (xmin < 0) or (xmax > 1) or not np.all(np.isreal(x)):
+        raise ValueError('X must be real values in the interval [0,1]')
+    
+    if abs(xmin - xmax) <= 2 * np.finfo(float).eps * xmax:
+        raise ValueError('X must contain distinct values')
+    
+    # Initial parameter estimates
+    n = len(x)
+    sumlogx = np.sum(np.log(x))
+    sumlog1mx = np.sum(np.log1p(-x))
+    tmp1 = np.exp(sumlog1mx / n)
+    tmp2 = np.exp(sumlogx / n)
+    
+    tmp3 = (1 - tmp1 - tmp2)
+    ahat = 0.5 * (1 - tmp1) / tmp3
+    bhat = 0.5 * (1 - tmp2) / tmp3
+    pstart = np.array([ahat, bhat])
+    
+    # If all values are strictly within the interval (0,1), use
+    # maximum likelihood with the usual continuous log-likelihood
+    xl = np.sqrt(np.finfo(float).tiny)  # some tolerance above zero
+    xu = 1 - np.finfo(float).eps / 2
+    
+    if (xl <= xmin) and (xmax <= xu):
+        def negloglike_cts(p):
+            p = np.exp(p)  # remove log transform
+            return n * betaln(p[0], p[1]) - (p[0] - 1) * sumlogx - (p[1] - 1) * sumlog1mx
+        
+        negloglike = negloglike_cts
+    else:
+        # If some values are zero or one, maximize a mixed likelihood that
+        # includes discrete probabilities for those values
+        x0 = (x < xl)
+        n0 = np.sum(x0)
+        x1 = (x > xu)
+        n1 = np.sum(x1)
+        x2 = x[~x0 & ~x1]
+        n2 = len(x2)
+        sumlogx2 = np.sum(np.log(x2))
+        sumlog1mx2 = np.sum(np.log1p(-x2))
+        
+        def negloglike_mixed(p):
+            p = np.exp(p)  # remove log transform
+            nll = n2 * betaln(p[0], p[1]) - (p[0] - 1) * sumlogx2 - (p[1] - 1) * sumlog1mx2
+            
+            # Include F(xl) = Pr(X <= xl) for data that are zeros
+            if n0 > 0:
+                nll = nll - n0 * np.log(stats.beta.cdf(xl, p[0], p[1]))
+            
+            # Include 1-F(xu) = Pr(X >= xu) for data that are ones
+            if n1 > 0:
+                nll = nll - n1 * np.log(1 - stats.beta.cdf(xu, p[0], p[1]))
+            
+            return nll
+        
+        negloglike = negloglike_mixed
+    
+    # Maximize the likelihood using a log transform for the parameters, to ensure
+    # the parameters are positive
+    pstart = np.log(pstart)
+    result = optimize.minimize(negloglike, pstart, method='Nelder-Mead',
+                             options={'xatol': 1e-7, 'fatol': 1e-7})
+    phat = np.exp(result.x)
+    
+    if alpha is not None:
+        
+        # Compute CIs on the log scale for both params
+        _, acov = betalike(phat, x)
+        logphat = np.log(phat)
+        selog = np.sqrt(np.diag(acov)) / phat
+        
+        p_int = np.array([alpha / 2, 1 - alpha / 2])
+        pci = np.exp(norminv(np.column_stack([p_int, p_int]), 
+                            np.row_stack([logphat, logphat]), 
+                            np.row_stack([selog, selog])))
+        return phat, pci
+    else:
+        return phat
+
+
+def betaln(a, b):
+    """
+    Beta function logarithm - equivalent to MATLAB's betaln function
+    """
+    return gammaln(a) + gammaln(b) - gammaln(a + b)

ezsnake-0.1.0/src/ezsnake/matlab/betainv.py

@@ -0,0 +1,76 @@
+import numpy as np
+import warnings
+from scipy.special import betaincinv, betainc
+from .distchck import distchck
+from .betacdf import betacdf
+
+def betainv(p, a, b):
+    """
+    BETAINV Inverse of the beta cumulative distribution function (cdf).
+    X = BETAINV(P,A,B) returns the inverse of the beta cdf with 
+    parameters A and B at the values in P.
+
+    The size of X is the common size of the input arguments. A scalar input  
+    functions as a constant matrix of the same size as the other inputs.    
+
+    BETAINV uses Newton's method to converge to the solution (en MATLAB).
+    En Python, se usa scipy.special.betaincinv.
+
+    See also BETACDF, BETAFIT, BETALIKE, BETAPDF, BETARND, BETASTAT, ICDF.
+    """
+    if a is None or b is None:
+        raise ValueError('Too few inputs')
+    errorcode, (p, a, b) = distchck(3, p, a, b)
+    if errorcode > 0:
+        raise ValueError('Input size mismatch')
+    p = np.asarray(p)
+    a = np.asarray(a)
+    b = np.asarray(b)
+    # Weed out any out of range parameters or probabilities.
+    okAB = (0 < a) & (a < np.inf) & (0 < b) & (b < np.inf)
+    k = okAB & (0 <= p) & (p <= 1)
+    allOK = np.all(k)
+    # Fill in NaNs for out of range cases.
+    x = np.full(k.shape, np.nan, dtype=float)
+    if not allOK:
+        if np.any(k):
+            if p.size > 1:
+                p2 = p[k]
+            else:
+                p2 = p
+            if a.size > 1:
+                a2 = a[k]
+            else:
+                a2 = a
+            if b.size > 1:
+                b2 = b[k]
+            else:
+                b2 = b
+        else:
+            return x
+    else:
+        p2, a2, b2 = p, a, b
+    # Call betaincinv to find a root of betainc(q,a,b) = p
+    q = betaincinv(a2, b2, p2)
+    delta = np.finfo(float).eps
+    badcdf = (np.abs(betainc(a2, b2, q) - p2) / np.maximum(p2, 1e-12)) > np.sqrt(delta)
+    if np.any(badcdf):
+        # Intentar ajustar con betacdf
+        idx = np.where(badcdf)[0]
+        for i in idx:
+            q_i = q[i]
+            a_i = a2[i] if a2.size > 1 else a2
+            b_i = b2[i] if b2.size > 1 else b2
+            p_i = p2[i] if p2.size > 1 else p2
+            q_minus = q_i - delta
+            q_plus = q_i + delta
+            cdf_minus = betacdf(q_minus, a_i, b_i)
+            cdf_plus = betacdf(q_plus, a_i, b_i)
+            if (cdf_minus - p_i) * (cdf_plus - p_i) > 0:
+                warnings.warn(f'betainv: NoConvergence for a={a_i}, b={b_i}, p={p_i}')
+    # Broadcast the values to the correct place if need be.
+    if allOK:
+        x = q
+    else:
+        x[k] = q
+    return x