¡Bienvenidoas a la documentación de Tinamït!¶

https://travis-ci.org/julienmalard/Tinamit.svg?branch=master

https://ci.appveyor.com/api/projects/status/3s1ppuilm0vioa3p?svg=true

Tinamït es un programa para conectar modelos socioeconómicos (dinámicas de los sistemas) con modelos biofísicos.

Tinamït permite la conexión rápida, flexible y reproducible de modelos con:

Una estructura fácil para conectar modelos en menos de 10 líneas (en vez de cientos).
Manejo automático de diferencias en escalas temporales y unidades.
Conexión con bases de datos para calibración y validación de modelos.
Inclusión automática de variables de cambios climáticos con la librería تقدیر (taqdir)
Una estructura transparente para que todos puedan agregar modelos y recursos.

Note

¿Encontraste algún error en la documentación? Es culpa mía. Si es error de español, por favor tenga la bondad de corregirlo en GitHub. Si es en otro idioma, corrígelo así. ¡Gracias!

¿Quieres contribuir?¶

Puedes agregar modelos, desarrollar nuevas funcionalidades, o ayudar a traducir Tinamït en tu lengua preferida.

Contacto: Julien Malard: julien.malard@mail.mcgill.ca

Índice:¶

Introducción¶

La modelización DS es una manera popular de hacer modelos participativos y visuales para el manejo ambiental y socio-económico. Vensim y Stella son programas populares y tienen versiones grátis.

No obstante, la inclusión de procesos ambientales o BF se complica en modelos DS. Y de verdad no deberías tener que contruir un modelo hidrológico o de cultivos en el ambiente DS solamente porque quieres ver los impactos de tu modelo socio-económico DS en el ambiente y vice-versa [1]. Ya existen muchos modelos BF que lo hacen para ti ([2], [3], [4]).

¿Pero cómo conectar un modelo DS con un BF? Por eso existe Tinamït. Empieza con nuestros tutoriales aquí o, aún mejor, con la instalción.

Figura 1

Diagrama de la estructura conceptual de Tinamït.

[1]	Jeong H, Adamowski J. 2016. A system dynamics based socio-hydrological model for agricultural wastewater reuse at the watershed scaleAgricultural Water Management, 171: 89-107. https://doi.org/10.1016/j.agwat.2016.03.019

[2]	SWAT+. https://swat.tamu.edu/software/plus/

[3]	SAHYSMOD. https://www.waterlog.info/sahysmod.htm

[4]	Jones, J.W., G. Hoogenboom, C.H. Porter, K.J. Boote, W.D. Batchelor, L.A. Hunt, P.W. Wilkens, U. Singh, A.J. Gijsman, and J.T. Ritchie. 2003. DSSAT Cropping System Model. European Journal of Agronomy 18:235-265.

Instalación¶

La instalación debería ser sencilla. Primero necesitarás la versión más recién de Python 3 Después, puedes instalar Tinamït en la terminal con:

pip install tinamit

Note

Windows todavía está causando complicaciones con programas no escritos en inglés (sí, en 2019). Si encuentras problemas, no hesites en pedir ayuda; por eso existe la comunidad.

Si quieres la versión más recién (en desarrollo), puedes obtenerla de GitHub directamente con:

pip install git+git://github.com/julienmalard/tinamit.git@master

Note

Si tienes Windows, es posible que tengas que instalar el C++ redistributable de aquí. Toma la versión terminando en …x86.exe si tienes Python de 32 bits y en …x64.exe si tienes Python (no Windows) de 64 bits. Después, instálalo. Por razones obscuras, SciPy, un paquete requerido por Tinamït, no funciona en Windows sin éste.

Publicaciones¶

Aquí compartimos publicaciones, en todos y cualquier idioma, que decriben o utilizaron Tinamït.

Publicaciones acerca de Tinamït¶

Publicaciones describiendo Tinamït y sus funcionalidades.

Note

Si publicas algún trabajo el el cual utilizasre Tinamït, puedes citar este artículo. ¡Gracias! :)

Malard JJ, Inam A, Hassanzadeh E, Adamowski J, Tuy HA, Melgar-Quiñonez H. Development of a software tool for rapid, reproducible, and stakeholder-friendly dynamic coupling of system dynamics and physically-based models. Environmental Modelling & Software, 96:410-420. https://doi.org/10.1016/j.envsoft.2017.06.053

Publicaciones con Tinamït¶

Publicaciones de estudios que utilizaron Tinamït.

Todavía estamos esperando. ¿No querrías escribir una, por casualidad?

Agradecimientos¶

Tinamït es un proyecto de fuente abierta. Las personas e instituciones siguientes hicieron posible su desarrollo.

Autores del código¶

Autores de envolturas¶

Gracias a los siguientes por escribir envolturas específicas a los modelos biofísicos siguientes (nota: escribimos las envolturas para que estos modelos sean compatibles con Tinamït, ¡no escribimos los modelos sí mismos!)

SAHYSMOD¶

محمّد اظہر انعام بیگ (Muhammad Azhar Inam Baig)
Julien Malard

Traductores¶

اردو: محمّد اظہر انعام بیگ (Muhammad Azhar Inam Baig)
தமிழ்: Julien Malard
हिंदी: Julien Malard
français: Julien Malard

Financiamiento¶

Los organismos siguientes contribuyeron apoyo financiero a uno o más de los autores del código mientras trabajaban en el desarrollo de Tinamït:

Instituciones afiliadas¶

Los autores de Tinamït están afiliados con las instituciones siguientes:

Conectar modelos¶

Ejemplo muy básico¶

Empezaremos con un modelo bastante sencillo. Pero demuestra muy bien cómo funciona Tinamït, y no tienes que instalar cualquier modelo biofísico externo para que te funcione, así que empecemos con este.

Primero vamos a utilizar este modelo de dinámicas de sistemas:

El modelo DS determina, dado la lluvia, la cantidad de pesca posible y su impacto en la necesidad de explotar recursos del bosque.

Del otro lado, el "modelo" biofísico nos da la precipitación según la cubertura forestal.

import matplotlib.pyplot as plt

from tinamit.conect import Conectado
from tinamit.ejemplos import obt_ejemplo

mds = obt_ejemplo('sencillo/mds_bosques.mdl')
bf = obt_ejemplo('sencillo/bf_bosques.py')

modelo = Conectado(bf=bf, mds=mds)

# Vamos a conectar los variables necesarios
modelo.conectar(var_mds='Lluvia', var_bf='Lluvia', mds_fuente=False)
modelo.conectar(var_mds='Bosques', var_bf='Bosques', mds_fuente=True)

# Y simulamos
res_conex = modelo.simular(200)

# Visualizar
f, (eje1, eje2) = plt.subplots(1, 2)
eje1.plot(res_conex['mds']['Bosques'].vals)
eje1.set_title('Bosques')
eje1.set_xlabel('Meses')

eje2.plot(res_conex['mds']['Lluvia'].vals)
eje2.set_title('Lluvia')
eje2.set_xlabel('Meses')

eje1.ticklabel_format(axis='y', style='sci', scilimits=(0,0))

(Source code, png, hires.png, pdf)

Tambiém comparemos a una corrida sin conexión para ver el impacto de incluir las relaciones entre ambiente y humano.

Note

Siendo subclases de Modelo, modelos BF (ModeloBF) y DS (ModeloDS) también se pueden simular de manera independiente.

from tinamit.envolt.mds import gen_mds
from tinamit.envolt.bf import gen_bf

res_mds = gen_mds(mds).simular(200, nombre='Corrida_MDS')
res_bf = gen_bf(bf).simular(200, nombre='Corrida_BF')

# Visualizar
f, (eje1, eje2) = plt.subplots(1, 2)
eje1.plot(res_conex['mds']['Bosques'].vals, label='Conectado')
eje1.plot(res_mds['Bosques'].vals, label='Individual')
eje1.set_title('Bosques')
eje1.set_xlabel('Meses')

eje1.ticklabel_format(axis='y', style='sci', scilimits=(0,0))

eje2.plot(res_conex['mds']['Lluvia'].vals)
eje2.plot(res_bf['Lluvia'].vals)
eje2.set_title('Lluvia')
eje2.set_xlabel('Meses')

f.legend()

(Source code, png, hires.png, pdf)

Opciones de tiempo¶

Si quieres más control sobre los detalles del eje de tiempo, puedes pasar un objeto EspecTiempo a la función simular(). Allí puedes especificar no solo el número de paso sino también una fecha inicial (útil para corridas con datos o clima externo), el tamaño de cada paso, y la frequencia con cual se guardan los resultados.

from tinamit.tiempo.tiempo import EspecTiempo

t = EspecTiempo(100, f_inic='2000-01-01', tmñ_paso=1, guardar_cada=1)
modelo.simular(t)

Unidades de tiempo¶

Tinamït se encargará de convertir entre unidades de tiempo para ti si difieren entre tus modelos. No obstante, si uno de tus modelos tiene unidad de tiempo no convencional o está en un idioma que Tinamït no reconoce, puede ser que tengas que especificar la conversión manualmente con nueva_unidad(), agregar_trad() o agregar_sinónimos().

from tinamit.unids import nueva_unidad, , agregar_sinónimos

# Una estación tiene 4 meses
nueva_unidad(unid='Estación', ref='Mes', conv=4)

# "día" se dice "நாள்" en Tamil
agregar_trad('día', 'நாள்', leng_trad='த', leng_orig='es', guardar=True)

# "தினம்" también quiere decir "día" en Tamil
agregar_sinónimos('நாள்', "தினம்", leng='த', guardar=True)

Tinamït reconoce las unidades de tiempo siguientes: año, mes, semana, día, hora, minuto, secundo, microsecundo, millisecundo, y nanosecundo.

3+ modelos¶

Si tienes más que 2 modelos para conectar, también es fácil con la clase SuperConectado. Se pueden conectar de manera horizontal o jerárquica, cómo prefieres.

Horizontal¶

Se pueden conectar modelos individuales de manera "horizontal" en un solo modelo SuperConectado.

from tinamit.conectado import SuperConectado

# Crear los 3 modelos
mod_1 = MiModelo1(nombre='modelo 1')
mod_2 = MiModelo2(nombre='modelo 2')
mod_3 = MiModelo3(nombre='modelo 3')

# El Conectado
conectado = SuperConectado([mod_1, mod_2, mod_3])

# Conectar variables entre dos de los modelos por el intermediario del tercero.
conectado.conectar_vars(
    var_fuente='Var 1', modelo_fuente='modelo 1', var_recip='Var 2', modelo_recip='modelo 2'
)
conectado.conectar_vars(
    var_fuente='Var 2', modelo_fuente='modelo 2', var_recip='Var 3', modelo_recip='modelo 3'
)

# Simular
res = conectado.simular(10, vars_interés=[mod_1.variables['Var 1'], mod_3.variables['Var 3']])

Los variables Var 1 del modelo 1 y Var 3 del modelo 3 ahora tendrán valores idénticos a través de la simulación.

Jerárquica¶

También se pueden anidar modelos adentro de otros.

# Los tres modelos
mod_1 = MiModelo1(nombre='modelo 1')
mod_2 = MiModelo2(nombre='modelo 2')
mod_3 = MiModelo3(nombre='modelo 3')

# El primer Conectado
conectado_sub = SuperConectado(nombre='sub', modelos=[mod_1, mod_2])
conectado_sub.conectar_vars(
    var_fuente='Var 1', modelo_fuente='modelo 1', var_recip='Var 2', modelo_recip='modelo 2'
)

# El segundo Conectado
conectado = SuperConectado([conectado_sub, mod_3])
conectado.conectar_vars(
    var_fuente=mod_2.variables['Var2'], var_recip='Var 3', modelo_recip='modelo 3'
)

# Correr la simulación
res = conectado.simular(10, vars_interés=[mod_1.variables['Var 1'], mod_3.variables['Var 2']])

Este código dará resultados idénticos a los del ejemplo horizontal arriba.

Clima¶

Tinamït puede incorporar datos de clima de manera automática, incluso con escenarios de cambios climáticos.

Note

Tinamït emplea تقدیر (taqdir) para obtener datos de cambios climáticos. Si vas a hacer muchas simulaciones con predicciones futuras, se recomienda que leas su documentación.

Especificar variables¶

Si tienes un variable climático en un modelo DS, puedes especificarlo con la función conectar_var_clima().

from tinamit.envolt.mds import gen_mds

mod = gen_mds('Mi modelo.xmile')
mod.conectar_var_clima(var='Lluvia', var_clima='بارش', combin='total', conv=0.001)
mod.conectar_var_clima(var='Temperatura', var_clima='درجہ_حرارت_اوسط', combin='prom', conv=1)

El parámetro combin especifica cómo se deben combinar los datos climáticos de varios días si el modelo se simula con un paso de más de un día. Si es prom, se tomará el promedio; si es total, se tomará el total de los días incluidos.

Warning

El parámetro var_clima debe ser un nombre de variable reconocido por taqdir (ver su documentación). Igualmente, si la unidad del variable en tu modelo no corresponde a la unidad del variable en taqdir, tendrás que especificar el factor de conversión en conv.

Para modelos BF, la conexión ya debería haberse efectuada en la envoltura específica al modelo, así que no deberías tener que hacer nada.

Correr¶

Después crearemos un objeto Clima para especificar el clima para nuestro lugar. El escenario de cambios climáticos sirve para simulaciones del futuro (taqdir obtendrá automáticamente los datos de cambios climáticos; ver aquí).

from tinamit.mod.clima import Clima

mi_clima = Clima(lat=31.569, long=74.355, elev=10, escenario='8.5')
t = EspecTiempo(365*50, f_inic='2020-01-01')
mod.simular(t, clima=mi_clima)

Si tienes tus propios datos observados, también los puedes incluir en el parámetro fuentes que corresponde directamente al parámetro ذرائع de taqdir.

from تقدیر.ذرائع import جےسن as Json

fuente = Json('DatosDeMiEstaciónClimáticaPrivadaQueNoVoyACompartirConNadie.json', 31.569, 74.355, 100)

mod.simular(t, clima=Clima(lat=31.569, long=74.355, elev=10, escenario='8.5', fuentes=(fuente,)))

Te recomendamos que leas la documentación de taqdir si quieres poder aprovechar te todas sus funcionalidades (extensión de datos, interpolación geográfica, desagregación temporal y mucho más).

Simulaciones en grupo¶

Si tienes muchas simulaciones para efectuar, puedes ahorar tiempo por hacerlas por grupos con la función simular_grupo() y un objeto de simulaciones por grupos (OpsSimulGrupo). Igualmente se pueden paralelizar las corridas para ahorar más tiempo.

from tinamit.mod import OpsSimulGrupo
from tinamit.envolt.mds import gen_mds

mod = gen_mds('Mi modelo.xmile')

vals_extern = [{'Política 1': 0, 'Política 2': 1}, {'Política 1': 1, 'Política 2': 0}]

ops = OpsSimulGrupo(t=[100, 150], extern=vals_extern)
res = mod.simular_grupo(ops)

En el ejemplo arriba, simularemos el modelo con Política 2 para 100 pasos, y con Política 1 por 150 pasos.

Warning

Cada opción con valores múltiples debe ser una lista, y cada lista presente en las opciones debe tener el mismo tamaño.

Opciones que no se especificaron en formato de lista se aplicarán a todas las corridas. En el ejemplo abajo, cada política se correrá por 100 pasos.

res = mod.simular_grupo(OpsSimulGrupo(t=100, extern=vals_extern))

Combinaciones¶

También se puede ejecutar todas las combinaciones posibles para las opciones de simulación con un objeto OpsSimulGrupoCombin. Por ejemplo, puedes simular todas las combinaciones de distintas políticas con varios escenarios de cambios climáticos.

from tinamit.mod.clima import Clima

clima_malo = Clima(lat=31.569, long=74.355, elev=10, escenario='2.6')
clima_peor = Clima(lat=31.569, long=74.355, elev=10, escenario='4.5')
clima_fritos = Clima(lat=31.569, long=74.355, elev=10, escenario='8.5')

t = EspecTiempo(365*50, f_inic='2020-01-01')

ops = OpsSimulGrupoCombin(t=t, extern=vals_extern, clima=[clima_malo, clima_peor, clima_fritos])
res = mod.simular_grupo(ops)

# Para ver cuáles combinaciones corresponden con cada resultado (en orden)
list(ops)

Mapas¶

Tinamït viene con algunas funcionalidades para dibujar mapas de resultados de simulación. Todos los mapas están compuestos de objetos Forma. Cada Forma está vinculada con un archivo .shp.

Formas dinámicas¶

Formas dinámicas (FormaDinámica) son las formas cuyos colores varían según los resultados de una simulación. Incluyen FormaDinámicaNumérica, la cual toma sus valores en formato de np.ndarray o de lista, y FormaDinámicaNombrada, la cual quiere sus datos en formato de diccionario.

Los mapas se pueden dibujar desde una matriz de un variable multidimensional en un modelo, o sino de una simulación de grupo donde cada simulación individual representa otra región en el mapa. Ambas situaciones se manejan por dibujar_mapa_de_res().

Simulaciones por grupo¶

En este ejemplo, correremos un modelo de epidemiología con distintas tazas de contacto para cada departamento de Guatemala.

import numpy as np

from tinamit.ejemplos import obt_ejemplo
from tinamit.envolt.mds import gen_mds
from tinamit.geog.mapa import FormaDinámicaNombrada, dibujar_mapa_de_res
from tinamit.mod import OpsSimulGrupo

mds = gen_mds(obt_ejemplo('enfermedad/mod_enferm.mdl'))
forma_deptos = obt_ejemplo('geog_guate/deptos.shp')

ops = OpsSimulGrupo(
    t=50,
    extern=[{'taza de contacto': np.random.random() * 500} for i in range(1, 23)],
    nombre=[str(i) for i in range(1, 23)]
)
res = mds.simular_grupo(ops, nombre='Epidemiología')

frm = FormaDinámicaNombrada(forma_deptos, col_id='COD_DEP', escala_colores=-1)
dibujar_mapa_de_res(forma_dinámica=frm, res=res, var='Individuos Infectados', t=16)

(Source code, png, hires.png, pdf)

Note

El nombre de cada simulación en el grupo debe corresponder con el nombre de una forma en el archivo .shp tal como especificado en la columna col_id.

Alternativamente, puedes utilizar una FormaDinámicaNumérica; en ese caso se asiñarán los resultados a las formas según su orden en OpsSimulGrupo, nada más.

Variables multidimensionales¶

Aplicaremos un modelo sencillo de bosques y lluvia a un mapa de la región del Rechna Doab (رچنا دوآب) en Pakistán. Este mapa divide la región en 215 polígonos, cada cual corresponde a un punto en el variable Bosque multidimensional.

from tinamit.ejemplos.sencillo.bf_bosques import PruebaBF
from tinamit.geog.mapa import FormaDinámicaNumérica

mod = PruebaBF(215)
polígonos = obt_ejemplo('rechna_doab/polígonos.shp')

extern = {'Bosques': np.random.random(215)*1e6}
res = mod.simular(t=10, extern=extern, nombre='Cobertura forestal')

frm = FormaDinámicaNumérica(polígonos, col_id='Id')
dibujar_mapa_de_res(forma_dinámica=frm, res=res, var='Bosques', t=10)

(Source code, png, hires.png, pdf)

Formas estáticas¶

También puedes agregar formas estáticas (FormaEstática), que no depienden de los resultados de una simulación y que se agregan solamente por razones estéticas.

Por el momento, tienes:

Cuerpos de agua: Agua
Bosques: Bosque
Calles: Calle
Zonas urbanas: Ciudad

from tinamit.geog.mapa import Agua, Calle

calles = Calle(obt_ejemplo('rechna_doab/calle.shp'))
río = Agua(obt_ejemplo('rechna_doab/río.shp'))
canales = Agua(obt_ejemplo('rechna_doab/canal.shp'), llenar=False)
dibujar_mapa_de_res(forma_dinámica=frm, otras_formas=[calles, canales, río], res=res, var='Bosques', t=10)

(Source code, png, hires.png, pdf)

Uso de datos¶

Puedes utilizar datos externos en Tinamït para especificar valores de variables en simulaciones, para alimentar calibraciones, y para efectuar validaciones.

Datos exógenos¶

Puedes especificar valores de parámetros o de variables externos en el transcurso de una simulación. ٓAquí vamos a hacer una simulación con un modelo sencillo de contagión de una enfermedad.

import matplotlib.pyplot as plt

from tinamit.ejemplos import obt_ejemplo
from tinamit.envolt.mds import gen_mds

mds = gen_mds(obt_ejemplo('enfermedad/mod_enferm.mdl'))

extern = {'número inicial infectado': 15}
res = mds.simular(t=100, extern=extern)

# Visualizar
plt.plot(res['Individuos Infectados'].vals)
plt.title('Población infectada')
plt.xlabel('Días')
plt.ylabel('Personas')

(Source code, png, hires.png, pdf)

Igualmente podemos pasar datos que varían temporalmente. Por ejemplo, la taza de infección puede variar a través de la epidemía.

from tinamit.tiempo import EspecTiempo
import numpy as np
import pandas as pd

extern = pd.DataFrame(
    data={'taza de infección': np.arange(0.001, 0.005, (0.005-0.001)/100)},
    index=pd.date_range('2000-01-01', periods=100)
)
res_base = mds.simular(t=EspecTiempo(100, f_inic='2000-01-01'))
res_extern = mds.simular(t=EspecTiempo(100, f_inic='2000-01-01'), extern=extern)

# Visualizar
plt.plot(res_base['Individuos Infectados'].vals, label='Constante')
plt.plot(res_extern['Individuos Infectados'].vals, label='Variable')

plt.legend()
plt.title('Población infectada')
plt.xlabel('Días')
plt.ylabel('Personas')

(Source code, png, hires.png, pdf)

Si quieres más control sobre el uso de variables externos, puedes utilizar la función gen_extern() para generar un objeto Extern que puedes pasar al parámetro extern.

Note

Se puede utilizar datos en formato de dict, pd.DataFrame o xr.Dataset.

Bases de datos¶

Para calibraciones y validaciones, puedes utilizar bases de datos, las cuales te permiten combinar varias fuentes de datos además de especificar datos geográficos.

En Tinamït, una base de datos (BD) está compuesta de una o más fuentes (Fuente). Fuentes pueden representar datos en formato .csv (FuenteCSV), diccionarios (FuenteDic), Dataset o DataArray de xarray (FuenteBaseXarray y FuenteVarXarray, respectivamente), o un DataFrame de pandas (FuentePandas).

Ver Calibraciones y Geografía para más detalles.

Calibraciones¶

Calibrar modelos¶

Tinamït puede calibrar modelos según variables observados. Las calibraciones se efectuan con calibradores (CalibradorMod), por ejemplo, CalibradorModSpotPy.

import numpy as np

from tinamit.ejemplos import obt_ejemplo
from tinamit.envolt.mds import gen_mds

mod = gen_mds(obt_ejemplo('enfermedad/mod_enferm.mdl'))

Generaremos unos datos artificiales (sí, hacemos trampa).

from tinamit.datos.fuente import FuenteDic

paráms = {
    'taza de contacto': 81.25,
    'taza de infección': 0.007,
    'número inicial infectado': 22.5,
    'taza de recuperación': 0.0375
}

simul = mod.simular(
    t=100, extern=paráms,
    vars_interés=['Individuos Suceptibles', 'Individuos Infectados', 'Individuos Resistentes']
)
datos = FuenteDic({ll: v[:, 0] for ll, v in simul.a_dic().items()}, nombre='Datos', fechas=np.arange(101))

Y efectuamos la calibración.

from tinamit.calibs.mod import CalibradorModSpotPy

líms_paráms={
    'taza de contacto': (0, 100),
    'taza de infección': (0, 0.02),
    'número inicial infectado': (0, 50),
    'taza de recuperación': (0, 0.1)
}

calibs = CalibradorModSpotPy(mod).calibrar(líms_paráms=líms_paráms, datos=datos, n_iter=50)

Calibrar ecuaciones¶

En el caso de modelos de dinámicas de sistemas, también se pueden calibrar los parámetros de ecuaciones individuales si tienes los datos necesarios.

Las calibraciones se pueden hacer con optimización (CalibradorEcOpt) o con inferencia bayesiana (CalibradorEcBayes).

Note

Casos sencillos con muchos datos disponibles generalmente se pueden resolver mucho más rápido con optimización normal que con la más sofisticada inferencia bayesiana.

El el modelo epidemiológico, el número de contactos con susceptibles se determina por el número de suceptibles y la taza de contacto según la ecuación contactos con suceptibles = Individuos Suceptibles * taza de contacto. Suponiendo que tenemos datos para el número de suceptibles y el número de contactos, podemos estimar la taza de contacto.

from tinamit.calibs.ec import CalibradorEcOpt
from tinamit.datos.bd import BD
from tinamit.datos.fuente import FuenteDic

n_obs = 100
taza_contacto = 125
individuos_suceptibles = np.random.random(n_obs)

contactos_con_suceptibles = individuos_suceptibles * taza_contacto + np.random.normal(0, 1, n_obs)
bd = BD(
    fuentes=FuenteDic({
            'contactos con suceptibles': contactos_con_suceptibles,
            'Individuos Suceptibles': individuos_suceptibles,
            'f': np.arange(n_obs)
        },
        nombre='Datos generados',
        fechas='f'
    )
)

calibrador = CalibradorEcOpt(
    ec=mod.variables['contactos con suceptibles'].ec, nombre='contactos con suceptibles',
    paráms=['taza de contacto']
)
calib_ec = calibrador.calibrar(líms_paráms={'taza de contacto': (0, 200)}, bd=bd)

Validar¶

Por supuesto, no hay calibración sin validación. (Al menos que tengas que publicar ya.) Las validaciones se efectuan con ValidadorMod.

from tinamit.calibs.valid import ValidadorMod

valid = ValidadorMod(mod).validar(
    t=100, datos=datos, paráms={prm: trz['mejor'] for prm, trz in calibs.items()}
)

Geografía¶

Tinamït cuenta con funcionalidades de datos geográficos para simulaciones, calibraciones y validaciones.

Especificación¶

Primero tenemos que especificar nuestra geografía. Ésta está compuesta de lugares (Lugar) de distintos niveles (Nivel). Por ejemplo, en el nivel departamental podremos encontrar varios muninicipios.

from tinamit.geog.región import Nivel, Lugar

muni = Nivel('Municipio')
dept = Nivel('Departamento', subniveles=muni)
terr = Nivel('Territorio', subniveles=muni)
país = Nivel('País', subniveles=[dept, terr])

muni1, muni2, muni3 = [Lugar('Muni%i' % i, nivel=muni, cód='M' + str(i)) for i in range(1, 4)]

dept1 = Lugar('Dept1', nivel=dept, cód='D1', sub_lugares=[muni1, muni2])
dept2 = Lugar('Dept2', nivel=dept, cód='D2', sub_lugares=[muni3])
terr1 = Lugar('Terr1', nivel=terr, cód='T1', sub_lugares=[muni1])
terr2 = Lugar('Terr2', nivel=terr, cód='T2', sub_lugares=[muni2])

guate = Lugar(
    'Guatemala', sub_lugares={muni1, muni2, muni3, dept1, dept2, terr1, terr2},
    nivel=país
)

O, para ahorar tiempo con geografías más complejas, puedes emplear la función gen_lugares(), que genera un lugar automáticamente a base de un archivo de .csv.

from tinamit.geog.región import gen_lugares
from tinamit.ejemplos import obt_ejemplo

guate = gen_lugares(obt_ejemplo('geog_guate/geog_guate.csv'), nivel_base='País', nombre='Iximulew')

Note

Puedes especificar niveles paralelos. Por ejemplo, aquí Departamento y Territorio son dos maneras alternativas de agrupar los municipios de Guatemala.

Calibración¶

Se pueden calibrar modelos según datos geográficos. El resultado será una calibración distinta para cada lugar para el cual tienes datos.

Ecuaciones¶

Tinamït tiene funcionalidades experimentales para calibrar ecuaciones con inferencia bayesiana jerárquica. Esta funcionalidad permite al modelo inferir valores el regiones para las cuales tienes muy poco (o hacia no) datos. Funciona por calibrar los variables al nivel más alto (por ejemplo, nacional) y después ajustar sus estimos para cada sublugar según la disponibilidad de datos.

Cada Nivel en tu geografía corresponderá a un nivel distinto en el modelo jerárquico.

Warning

La calibración con inferencia bayesiana jerárquica es muy emocionante pero también todavía experimental.

Si tus ecuaciones no están bien definidas o si su forma no corresponde con la de los datos, correrá muy lentamente la calibración y tus resultados no valdrán nada de todo modo. Siempre es buena idea visualmente comparar los resultados con los datos.

Simplemente puedes pasar un objeto Lugar a CalibradorEcOpt o al CalibradorEcBayes (ver Calibraciones).

Modelos¶

Calibraciones geográficas se pueden también aplicar al nivel del modelo entero.

import numpy as np

from tinamit.calibs.geog_mod import SimuladorGeog, CalibradorGeog
from tinamit.datos.bd import BD
from tinamit.datos.fuente import FuenteDic

paráms = {
         '708': {
             'taza de contacto': 81.25, 'taza de infección': 0.007, 'número inicial infectado': 22.5,
             'taza de recuperación': 0.0375
         },
         '1010': {
             'taza de contacto': 50, 'taza de infección': 0.005, 'número inicial infectado': 40,
             'taza de recuperación': 0.050
         }
}

# Unos datos artificiales
simul = SimuladorGeog(mds).simular(
    t=100, vals_geog=paráms,
    vars_interés=['Individuos Suceptibles', 'Individuos Infectados', 'Individuos Resistentes']
)
datos = {
    lg: {ll: v[:, 0] for ll, v in simul[lg].a_dic().items()} for lg in paráms
}

datos = BD([
    FuenteDic(datos[lg], 'Datos geográficos', lugares=lg, fechas=np.arange(101)) for lg in paráms
])

calib = CalibradorGeog(mds).calibrar(t=100, datos=datos, líms_paráms=líms_paráms, n_iter=50)

Validación¶

Se puede validar una calibración geográfica con la clase ValidadorGeog.

from tinamit.calibs.geog_mod import ValidadorGeog

valid = ValidadorGeog(mds).validar(
         t=100, datos=datos,
         paráms={lg: {prm: trz['mejor'] for prm, trz in calib[lg].items()} for lg in paráms}
)

Envolturas BF¶

Cada modelo BF requiere la presencia de una envoltura especial que maneja su interacción (simulación, intercambio de variables) con Tinamït.

Note

Todas las envolturas son subclases de ModeloBF. No obstante, Tinamït viene con clases especiales para simplificar tu vida con casos de modelos más compicados.

¿Cómo escoger la clase pariente? Si tu modelo da resultados con el mismo paso de tiempo con el cual puede avanzar (por ejemplo, da resultados mensuales y avanza con paso mensual), entonces es un modelo sencillo. Si da resultados con paso más pequeño que el paso con el cual puede avanzar (por ejemplo, un modelo hidrológico que simula 1 año a la vez pero después devuelve resultados diarios), entonces es un modelo determinado.

Si tu modelo tiene subdivisiones temporales adicionales (p. ej., SAHYSMOD simula por un año, pero después devuelve datos por estaciones de duración de entre 1 a 12 meses), entonces es un modelo bloques.

Y, por fin, si no sabes antes de simular cuánto tiempo va a simular (p. ej., modelos de cultivos que corren hacia la cosecha), entonces tienes un modelo indeterminado.

Modelos Sencillos¶

Siendo modelos sencillos, las envolturas basadas directamente en ModeloBF solamente deben implementar las funciones siguientes:

unidad_tiempo(): Devuelve la unidad de tiempo del modelo.
incrementar(): Avanza el modelo.
__init__(): Inicializa el modelo. En la llamada a super().__init__ debes incluir un objeto VariablesMod con los variables del modelo.

Funciones y atributos opcionales:

paralelizable(): Indica si el modelo se puede paralelizar para ahorar tiempo.
iniciar_modelo(): Acciones llamadas justo antes de la simulación.
cerrar(): Efectua acciones de limpieza al final de una simulación.
_correr_hasta_final(): Permite el modelo de combinar pasos de simulación cuando posible para ser más rápido.
instalado(): Verifica si el modelo correspondiendo a la envoltura está instalado en la computadora o no.
Modelo.idioma_orig: Indica el idioma de los nombres de variables del modelo.

Warning

Tu implementación de incrementar() debe incluir una llamada a super().incrementar(rebanada) al final para que valores de parámetros externos y de clima se actualicen correctamente. Igualmente, cualquier reimplementación de iniciar_modelo() debe incluir una llamada a super().iniciar_modelo(corrida) al final.

En la función incrementar(), se puede acceder los variables del modelo con símismo.variables["nombre del variable"], obtener su valor con obt_val(), y cambiar su valor con poner_val():

lago = símismo.variables['Lago']
val_lago = lago.obt_val()

nuevo_valor = 100
lago.poner_val(nuevo_valor)

Modelos Determinados¶

Modelos determinados (ModeloDeterminado) simulan por un periodo fijo, y después devuelven egresos de manera retroactiva. Muchos modelos biofísicos (SWAT, DSSAT, STICS) funcionan (o pueden funcionar) así.

El paso del modelo sigue siendo la unidad de tiempo de los egresos (p. ej., días), y se agrega el concepto de un ciclo, o el tiempo mínimo que se puede efectuar una simulación (p. ej., 1 año).

Funciones obligatorias:

unidad_tiempo(): Devuelve la unidad de tiempo de los egresos del modelo.
avanzar_modelo(): Avanza el modelo de un cierto número de ciclos.
__init__(): Inicializa el modelo. En la llamada a super().__init__ debes incluir un objeto VariablesModDeter con los variables del modelo.

Note

No se implementa incrementar() en modelos determinados. Tinamït lo implementa automáticamente y llama avanzar_modelo() en los momentos oportunos de la simulación.

Modelos determinados pueden tener variables que cambian con el paso (VarPasoDeter) y otros que cambian con el ciclo (Variable). Ambos se pueden pasar al VariablesModDeter de la inicialización.

Para cambiar los valores de VarPasoDeter en la función avanzar_modelo(), se llama poner_vals_paso con una matriz de valores para todos los pasos en el ciclo presente. Para obtener su valor en el paso actual, se llama obt_val, o sino obt_vals_paso para obtener la matriz de sus valores para todos los pasos en el ciclo actual.

Note

Tinamït se encarga de actualizar los valores de los variables por paso según el paso actual del modelo.

Igualmente pueden implementar todas las funciones opcionales de ModeloBF.

Modelos Bloques¶

Modelos bloques (ModeloBloques) son una subclase de (ModeloDeterminado). Además de pasos y ciclos, tienen el concepto de bloques. En su simulación, un ciclo contiene varios bloques hechos de cantidades variables de pasos.

Funciones obligatorias:

unidad_tiempo(): Devuelve la unidad de tiempo de base de los egresos del modelo. Por ejemplo, si el modelo simula por año y devuelve datos por tres estaciones de 4, 5 y 3 meses, entonces la unidad de tiempo sería mes.
avanzar_modelo(): Avanza el modelo de un cierto número de ciclos.
__init__(): Inicializa el modelo. En la llamada a super().__init__ debes incluir un objeto VariablesModBloques con los variables del modelo.

Modelos bloques pueden tener variables bloques (VariablesModBloques), igual que variables que cambian con el paso (VarPasoDeter) y otros que cambian con el ciclo (Variable).

Note

Tinamït actualiza automáticamente el paso, el bloque y el ciclo de sus variables (con los valores, por supuesto).

Igualmente pueden implementar todas las funciones opcionales de ModeloBF.

Modelos Indeterminados¶

Modelos indeterminados (ModeloIndeterminado) avanzan por periodos de tiempo indeterminados cada vez que se simulan. Tienen el concepto de ciclos, pero el tamaño del ciclo varia entre simulaciones.

Funciones obligatorias:

unidad_tiempo(): Devuelve la unidad de tiempo de los egresos del modelo.
mandar_modelo(): Avanza el modelo.
__init__(): Inicializa el modelo. En la llamada a super().__init__ debes incluir un objeto VariablesModIndeterminado con los variables del modelo.

En VariablesModIndeterminado, se pueden incluir variables cuyos valores cambian con el paso (VarPasoIndeter), tanto como variables cuyos valores quedan constantes adentro del mismo ciclo (Variable).

En mandar_modelo(), se puede utilizar las mismas funciones que con modelos determinados para establecer y acceder los valores de los variables.

Igualmente pueden implementar todas las funciones opcionales de ModeloBF.

Variables clima¶

Si tu modelo incluye variables climáticos, puedes especificarlos con la función conectar_var_clima() en el __init__() de la clase. Tinamït se encargará de la actualización del valor del variables cuando se efectua una simulación con clima activado.

Note

Si tu modelo requiere datos de manera más sofisticada (por ejemplo, DSSAT debe guardar en un archivo externo todos los datos climáticos antes de empezar la simulación), puedes acceder el objeto de Clima de la corrida actual (si hay) con símismo.corrida.clima y llamar sus funciones obt_datos() o obt_todos_vals().

Configuración¶

Puedes incluir variables de configuración en tu envoltura (p. ej., la ubicación de un archivo ejecutable). Se obtiene el valor con obt_conf(), y usuarias pueden establecer su valor con MiEnvoltura.estab_conf("llave", "valor"). Por ejemplo:

from tinamit.envolt.sahysmod.bf import ModeloSAHYSMOD
ModeloSAHYSMOD.estab_conf("exe", "C:\\Camino\\hacia\\mi\\SAHYSMODConsole.exe")

Pruebas¶

Siempre es buena idea tener pruebas para saber si tu envoltura funciona bien o no. Tinamït te permite integrar pruebas de lectura de datos, de lectura de egresos y de simulación con tus envolturas.

Puedes implementar las funciones prb_ingreso(), prb_egreso(), o prb_simul() para tu modelo.

Después, puedes integrar las funciones verificar_leer_ingr(), verificar_leer_egr(), y verificar_simul() con tus pruebas automáticas para comprobar que todo están bien con tu envoltura. La primera vez que corren las pruebas, Tinamït guardará en el disco los resultados de la lectura de datos y de la simulación. Asegúrate que estén correctos los variables. Si, en el futuro, tu envoltura ya no da los mismos resultados, Tinamït te avisará de un error.

Note

Estas funciones se aplican automáticamente a todas las envolturas incluidas con la distribución de Tinamït.

Distribución¶

Puedes compartir tu nueva envoltura como paquete Python independiente. Igualmente puedes contribuirlo al código fuente de Tinamït, después de cual todas las usuarias de Tinamït podrán acceder tu envoltura.

Envolturas MDS¶

Envolturas para modelos de dinámicas de sistemas son subclases de ModeloMDS.

Note

Las envolturas para modelos DS son universales. Es decir, la misma envoltura funcionará para todos los modelos creados con el mismo programa (p. ej., Vensim), no importe el contenido del modelo sí mismo.

Cómo crear tu envoltura¶

Funciones y atributos para implementar:

unidad_tiempo(): Devuelve la unidad de tiempo del modelo.
incrementar(): Avanza el modelo.
__init__(): Inicializa el modelo. En la llamada a super().__init__ debes incluir un objeto VariablesMDS con los variables del modelo.
cambiar_vals(): No estríctamente necesario, pero la casi totalidad de modelos DS necesitarán tomar acción específica para cambiar valores de variables en el modelo externo.
ModeloDS.ext: Una lista de las extensiones de archivo que se pueden leer por la envoltura.

Funciones y atributos opcionales:

paralelizable(): Indica si el modelo se puede paralelizar para ahorar tiempo.
iniciar_modelo(): Acciones llamadas justo antes de la simulación.
cerrar(): Efectua acciones de limpieza al final de una simulación.
_correr_hasta_final(): Permite el modelo de combinar pasos de simulación cuando posible para ser más rápido.
instalado(): Verifica si el modelo correspondiendo a la envoltura está instalado en la computadora o no.

Warning

Tu implementación de incrementar() debe incluir una llamada a super().incrementar(rebanada) al final para que valores de parámetros externos y de clima se actualicen correctamente. Igualmente, cualquier reimplementación de iniciar_modelo() debe incluir una llamada a super().iniciar_modelo(corrida) al final, y cambiar_vals() una a super().cambiar_vals(valores).

Cada variable en VariablesMDS debe ser uno de VarConstante, VarInic, VarNivel, o :class:`~tinamit.envolt.mds.VarAuxiliar.

Autogeneración¶

La función gen_mds() de Tinamït puede escoger automáticamente la envoltura más apropriada para un archivo dado de modelo DS según el atributo ModeloMDS.ext de cada clase de envoltura. Puedes llamar la función registrar_envolt_mds() para registrar tu nueva clase de modelo DS en Tinamït, y olvidar_envolt_mds() para quitarla.

Si estás modificando el código fuente de Tinamït, puedes agregar tu clase a tinamit.envolt.mds._auto._subclases para que se tome automáticamente en cuenta.

Distribución¶

Puedes compartir tu nueva envoltura como paquete Python independiente. Igualmente puedes contribuirlo al código fuente de Tinamït, después de cual todas las usuarias de Tinamït podrán acceder tu envoltura.

Traducir¶

¿Quieres leer este en tu propia lengua? La documentación de Tinamït se traduce de manera colaborativa. Puedes utilizar el servidor Transifex o Zanata (syncronizamos los dos, así que no hay problema cuál eliges):

Zanata: Empezar ahora.
Transifex: Empezar ahora.

Para manejadoras¶

El página de integración contínua Travis CI de Tinamït está configurada para automáticamente mandar cambios en el texto para traducir a Transifex, y para obtener las nuevas traducciones disponibles en Transifex, cada vez que se hace un cambio a la rama master del proyecto en GitHub.

Las nuevas traducciones se mandarán por Travis CI a una nueva rama llamada Transifex en GitHub; puedes incorporarla con la rama master y después aparecerán automágicamente las traducciones en la documentación en línea.

Referencia de envolturas¶

Abajo puedes encontrar información sobre todas las envolturas que vienen con Tinamït. Si quieres agregar una nueva, contáctenos y la podremos desarrollar juntos.

Modelos DS¶

Envolturas incluidas en Tinamït:

PySD: Implementación de modelos DS en puro Python. Más rápido que Vensim, pero no incluye todas las funcionalidades (por el momento). Ver su documentación aquí. Puede leer modelos en formato .mdl de Vensim, tanto como el estándar .xmile (utilizado, entre otros, por Stella).
Vensim: Un programa de MDS bastante popular. Desafortunadamente, requiere la versión pagada (DSS) para conectar con Tinamït. Ver su página oficial. Además, solamente funciona en Windows. Con Vensim, primero hay que ir a cada variable en tu modelo Vensim que quieres que pueda recibir valores desde el modelo biofísico y escoger Gaming como tipo de variable. Después, hay que publicar el modelo en formato .vpm.

Modelos BF¶

Envolturas incluidas en Tinamït:

SAHYSMOD: Modelo de salinidad de suelos. Ver su documentación. Para uso con Tinamït deberás descargar una versión especial modificada para funcionar desde la línea de comanda aquí (quieres el SahysModConsole.exe).

Envolturas planeadas:

PCSE: Modelo de cultivos en puro Python, ver su documentación.
DSSAT: Modelo de cultivos bien popular. Descarga grátis.
SWAT+: Modelo hidrológico, gratis y de fuente abierta. Descarga aquí.

Interfaz de Programación¶

Modelos BF¶

Autogeneración¶

Modelos disponibles¶

class tinamit.envolt.bf.ModeloBF(variables, nombre='bf')[source]¶

La clase pariente para todos modelos biofísicos.

classmethod prb_egreso()[source]¶

Debe devolver la ubicación de un archivo de egresos y una función que lo puede leer.

Returns:
Return type:	tuple[str, Callable]

classmethod prb_ingreso()[source]¶

Debe devolver la ubicación de un archivo de ingresos y una función que lo puede leer.

Returns:
Return type:	tuple[str, Callable]

classmethod prb_simul()[source]¶

Debe devolver la ubicación de un archivo de ingresos para correr una simulación de prueba.

Returns:
Return type:	str

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.bf.ModeloDeterminado(tmñ_ciclo, variables, nombre='bf')[source]¶

La clase pariente para todos modelos que correr por un número predeterminado de pasos a cada simulación.

avanzar_modelo(n_ciclos)[source]¶

Avanzar el modelo por un número determinado de ciclos.

Parameters:	n_ciclos (int) -- El número de ciclos que hay que avanzar.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.bf.ModeloBloques(variables, nombre='bf')[source]¶

Parameters:	variables (VariablesModBloques) -- nombre (str) --

avanzar_modelo(n_ciclos)[source]¶

Avanzar el modelo por un número determinado de ciclos.

Parameters:	n_ciclos (int) -- El número de ciclos que hay que avanzar.

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.bf.ModeloIndeterminado(variables, nombre='bf')[source]¶

La clase pariente para todos modelos que avanzan por un número indeterminado de pasos a cada corrida.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.bf.ModeloImpaciente(tmñ_ciclo, variables, nombre='bf')[source]¶

La clase pariente para modelos que deben correr por varios pasos al mismo tiempo, es decir, Indeterminado y Determinado.

iniciar_modelo(corrida)[source]¶

Inicia la simulación. En general no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	corrida (Corrida) -- La corrida.

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

Modelos DS¶

Autogeneración¶

exception tinamit.envolt.mds._auto.ErrorNoInstalado[source]¶: Error para devolver si no está instalada una envoltura.

tinamit.envolt.mds._auto.gen_mds(archivo)[source]¶

Automáticamente generar un ModeloDS desde un archivo.

Parameters:	archivo (str) --
Returns:
Return type:	ModeloDS

tinamit.envolt.mds._auto.olvidar_envolt_mds(envoltura)[source]¶

Borra una envoltura del registro global.

Parameters:	envoltura -- La envoltura que ya no quieres.

tinamit.envolt.mds._auto.registrar_envolt_mds(envoltura)[source]¶

Registra una nueva envoltura en Tinamït.

Parameters:	envoltura -- La nueva envoltura.

Modelos disponibles¶

class tinamit.envolt.mds.ModeloDS(variables, nombre='mds')[source]¶

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.mds.pysd.ModeloPySD(archivo, nombre='mds')[source]¶

Envoltura para modelos PySD.

cambiar_vals(valores)[source]¶

Esta función cambia el valor de uno o más variables del modelo.

Parameters:	valores (dict) -- Un diccionario de variables y sus valores para cambiar.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

iniciar_modelo(corrida)[source]¶

Inicia la simulación. En general no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	corrida (Corrida) -- La corrida.

paralelizable()[source]¶

Indica si el modelo actual se puede paralelizar de manera segura o no. Si implementas una subclase paralelizable, reimplementar esta función para devolver True.

¿No sabes si es paralelizable tu modelo?

Respuesta larga: Si el modelo se puede paralelizar (con corridas de nombres distintos) sin encontrar dificultades técnicas (sin riesgo que las corridas paralelas terminen escribiendo en los mismos archivos de egreso), entonces sí es paralelizable tu modelo.

Respuesta rápida: 95% seguro que sí.

Returns:	Si el modelo es paralelizable o no.
Return type:	bool

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

class tinamit.envolt.mds.vensim_dll.ModeloVensimDLL(archivo, nombre='mds')[source]¶

Esta es la envoltura para modelos de tipo Vensim. Puede leer y controlar cualquier modelo Vensim para que se pueda emplear en Tinamït. Necesitarás la versión DSS de Vensim para que funcione.

cambiar_vals(valores)[source]¶

Esta función cambia el valor de uno o más variables del modelo.

Parameters:	valores (dict) -- Un diccionario de variables y sus valores para cambiar.

cerrar()[source]¶: Cierre la simulación Vensim.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

iniciar_modelo(corrida)[source]¶

Inicia la simulación. En general no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	corrida (Corrida) -- La corrida.

classmethod instalado()[source]¶

Si tu modelo depiende en una instalación de otro programa externo a Tinamït, puedes reimplementar esta función para devolver True si el modelo está instalado y False sino.

Returns:	Si el modelo está instalado completamente o no.
Return type:	bool

paralelizable()[source]¶

Indica si el modelo actual se puede paralelizar de manera segura o no. Si implementas una subclase paralelizable, reimplementar esta función para devolver True.

¿No sabes si es paralelizable tu modelo?

Respuesta larga: Si el modelo se puede paralelizar (con corridas de nombres distintos) sin encontrar dificultades técnicas (sin riesgo que las corridas paralelas terminen escribiendo en los mismos archivos de egreso), entonces sí es paralelizable tu modelo.

Respuesta rápida: 95% seguro que sí.

Returns:	Si el modelo es paralelizable o no.
Return type:	bool

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

Variables¶

class tinamit.envolt.mds.VarAuxiliar(nombre, unid, ec, parientes, inic, subs=None, líms=None, info='')[source]¶: Un variable auxiliar.

class tinamit.envolt.mds.VarConstante(nombre, unid, ec, parientes, inic, subs=None, líms=None, info='')[source]¶: Un variable constante.

class tinamit.envolt.mds.VarInic(nombre, unid, ec, parientes, inic, subs=None, líms=None, info='')[source]¶: Un variable inicial.

class tinamit.envolt.mds.VarNivel(nombre, unid, ec, parientes, inic, subs=None, líms=None, info='')[source]¶: Un variable nivel.

class tinamit.envolt.mds.VarMDS(nombre, unid, ingr, egr, ec, parientes, inic, subs=None, líms=None, info='')[source]¶: Un variable de un modelo ModeloDS.

class tinamit.envolt.mds.VariablesMDS(variables)[source]¶: Representa los variables de un modelo ModeloDS.

Conectado¶

class tinamit.conect.Conectado(bf, mds, nombre='conectado')[source]¶

Un modelo que conecta un ModeloDS con un ModeloBF.

conectar(var_mds, var_bf, mds_fuente, conv=None)[source]¶

Una función para conectar variables entre el modelo biofísico y el modelo DS.

Parameters:	var_mds (str) -- El nombre del variable en el modelo DS. var_bf (str) -- El nombre del variable correspondiente en el modelo biofísico. mds_fuente (bool) -- Si `True`, el modelo DS es el modelo fuente para la conexión. Sino, será el modelo biofísico. conv (float) -- El factor de conversión entre los variables.

desconectar(var_mds)[source]¶

Esta función deshacer una conexión entre el modelo biofísico y el modelo DS. Se especifica la conexión por el nombre del variable en el modelo DS.

Parameters:	var_mds (str) -- El nombre del variable conectado en el modelo DS.

class tinamit.conect.SuperConectado(modelos, nombre='SuperConectado')[source]¶

Esta clase representa el más alto nivel posible de modelo conectado. Tiene la función muy útil de poder conectar instancias de sí misma, así permitiendo la conexión de números arbitrarios de modelos anidados.

cambiar_vals(valores)[source]¶

Esta función cambia el valor de uno o más variables del modelo.

Parameters:	valores (dict) -- Un diccionario de variables y sus valores para cambiar.

cerrar()[source]¶: Esta función toma acciones necesarias para terminar la simulación y cerrar el modelo, si aplica.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

iniciar_modelo(corrida)[source]¶

Inicia la simulación. En general no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	corrida (Corrida) -- La corrida.

paralelizable()[source]¶

Indica si el modelo actual se puede paralelizar de manera segura o no. Si implementas una subclase paralelizable, reimplementar esta función para devolver True.

¿No sabes si es paralelizable tu modelo?

Respuesta larga: Si el modelo se puede paralelizar (con corridas de nombres distintos) sin encontrar dificultades técnicas (sin riesgo que las corridas paralelas terminen escribiendo en los mismos archivos de egreso), entonces sí es paralelizable tu modelo.

Respuesta rápida: 95% seguro que sí.

Returns:	Si el modelo es paralelizable o no.
Return type:	bool

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

Modelo¶

class tinamit.mod.modelo.Modelo(variables, nombre)[source]¶

Todas las cosas en Tinamit son instancias de Modelo, que sea un modelo de dinámicas de los sistemas, un modelo de cultivos o de suelos o de clima, o un modelo conectado. Cada tipo de modelo se representa por subclases específicas. Por eso, la gran mayoría de los métodos definidos aquí se implementan de manera independiente en cada subclase de Modelo.

La función de inicialización de todos modelos, conectados o no.

Parameters:	variables (VariablesMod) -- Los variables del modelo. nombre (str) -- El nombre del modelo.

cambiar_vals(valores)[source]¶

Esta función cambia el valor de uno o más variables del modelo.

Parameters:	valores (dict) -- Un diccionario de variables y sus valores para cambiar.

cerrar()[source]¶: Esta función toma acciones necesarias para terminar la simulación y cerrar el modelo, si aplica.

conectar_var_clima(var, var_clima, conv, combin='prom')[source]¶

Conecta un variable climático.

Parameters:

var (str) -- El nombre interno del variable en el modelo.
var_clima (str) -- El nombre oficial del variable climático.
conv (number) -- La conversión entre el variable clima en Tinamït y el variable correspondiente en el modelo.
combin (str or function or None) -- Si este variable se debe adicionar o tomar el promedio entre varios pasos. Puede ser prom, total, o una función. Si es None, se tomará el último día en el caso de pasos de más de 1 día.

correr()[source]¶: Efectuar una simulación ya inicializada. En general, no llamarías esta función directamente.

classmethod estab_conf(llave, valor)[source]¶

Establece un valor de configuración.

Parameters:	llave (str) -- El parámetro de configuración. valor (str or int or float or list or bool or dict) -- El valor del parámetro.

incrementar(rebanada)[source]¶

Incrementa el modelo. En general, no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	rebanada (Rebanada) -- La rebanada del incremento.

iniciar_modelo(corrida)[source]¶

Inicia la simulación. En general no llamarías esta función directamente.

No se te olvide una llamada al super cuando reimplementas esta función.

Parameters:	corrida (Corrida) -- La corrida.

classmethod instalado()[source]¶

Si tu modelo depiende en una instalación de otro programa externo a Tinamït, puedes reimplementar esta función para devolver True si el modelo está instalado y False sino.

Returns:	Si el modelo está instalado completamente o no.
Return type:	bool

classmethod obt_conf(llave, auto=None, cond=None, mnsj_err=None)[source]¶

Obtiene un valor de configuración de la subclase de modelo.

Parameters:	llave (str) -- El parámetro de configuración. auto (str or int or float or list or bool or dict) -- Un valor automático a aplicar si no se encuentra en el diccionario de configuración. cond -- Una condición para validar el valor; si no pasa la condición, se tratará como valor que falta. mnsj_err -- Un mensaje de aviso para devolver al usuario si no se encuentra el valor.
Returns:	El valor de configuración
Return type:	str, int, float, list, bool, dict

paralelizable()[source]¶

Indica si el modelo actual se puede paralelizar de manera segura o no. Si implementas una subclase paralelizable, reimplementar esta función para devolver True.

¿No sabes si es paralelizable tu modelo?

Respuesta larga: Si el modelo se puede paralelizar (con corridas de nombres distintos) sin encontrar dificultades técnicas (sin riesgo que las corridas paralelas terminen escribiendo en los mismos archivos de egreso), entonces sí es paralelizable tu modelo.

Respuesta rápida: 95% seguro que sí.

Returns:	Si el modelo es paralelizable o no.
Return type:	bool

simular(t, nombre='Tinamït', extern=None, clima=None, vars_interés=None)[source]¶

Parameters:	t (int or EspecTiempo) -- La especificación del eje de tiempo. Si es `int`, significará el número de pasos. nombre (str) -- El nombre de la corrida. extern (Extern or pd.DataFrame or xr.Dataset or dict) -- Valores externos para la simulación. clima (Clima) -- El clima de la simulación. vars_interés (list) -- Los variables para incluir en los resultados
Returns:
Return type:	ResultadosSimul

simular_grupo(ops_grupo, nombre='Tinamït', paralelo=False)[source]¶

Efectua un grupo de simulaciones. Muy útil para accelerar corridas múltiples.

Parameters:	ops_grupo (PlantillaOpsSimulGrupo) -- Las opciones de simulación en grupo. nombre (str) -- El nombre de la simulación. paralelo (bool) -- Si se simula en paralelo o no. Si el modelo no soporte corridas en paralelo, se ignorará este argumento.
Returns:
Return type:	ResultadosGrupo

unidad_tiempo()[source]¶

Esta función debe devolver la unidad de tiempo empleada por el modelo.

Returns:	La unidad de tiempo (p. ej., 'meses', 'مہینہ', etc.)
Return type:	str

Pruebas¶

tinamit.mod.prbs.verificar_leer_egr(caso, cls)[source]¶

Verifica que una envoltura lee bien sus datos de egreso.

Parameters:	caso (unittest.TestCase) -- El caso de prueba. cls -- La clase del modelo para comprobar.

tinamit.mod.prbs.verificar_leer_ingr(caso, cls)[source]¶

Verifica que una envoltura lee bien sus datos de ingreso.

Parameters:	caso (unittest.TestCase) -- El caso de prueba. cls -- La clase del modelo para comprobar.

tinamit.mod.prbs.verificar_simul(caso, cls)[source]¶

Verifica que una envoltura simula bien. No correrá si no está instalada la envoltura.

Parameters:	caso (unittest.TestCase) -- El caso de prueba. cls -- La clase del modelo para comprobar.

Geografía¶

class tinamit.geog.región.Lugar(nombre, nivel, cód=None, sub_lugares=None)[source]¶

Un lugar dado en una geografía.

Parameters:	nombre (str) -- El nombre del lugar. nivel (Nivel) -- El nivel geográfico correspondiente. cód (str) -- El identificador único de este lugar. Si es `None`, se tomará su nombre como identificador. sub_lugares -- Lugares que se encuentre adentro de este.

buscar_nombre(nombre, nivel=None)[source]¶

Devuelve el sublugar con el nombre dado.

Parameters:	nombre (str) -- El nombre del lugar deseado. nivel (Nivel or str) -- Desambiguación en el caso que hayan múltiples lugares con el mismo nombre en distintos niveles.
Returns:
Return type:	Lugar

hijos_inmediatos(ord_niveles=None)[source]¶

Devuelve los hijos inmediatos de este Lugar.

Parameters:	ord_niveles (list) -- Desambiguación para lugares con niveles paralelos.
Returns:
Return type:	list[Lugar]

lugares(en=None, nivel=None)[source]¶

Devolver los sublugares presentes en este lugar.

Parameters:	en (str or Lugar) -- Sublugar al cual limitir la búsqueda. nivel (Nivel or str or list) -- Opción para limitir los resultados a uno o más niveles.
Returns:
Return type:	set[Lugar]

pariente(lugar, ord_niveles=None, todos=False)[source]¶

Obtener el pariente de un sublugar dado.

Parameters:	lugar (str or Lugar) -- Un sublugar cuyo pariente queremos. ord_niveles (list) -- Desambiguación para lugares con niveles paralelos. todos (bool) -- Si queremos todos los parientes del lugar, o solamente el más cercaco.
Returns:
Return type:	Lugar

class tinamit.geog.región.Nivel(nombre, subniveles=None)[source]¶

Un nivel geográfico (p. ej, municipio o departamento.

Parameters:	nombre (str) -- El nombre del nivel. subniveles (list of Nivel) -- Lista de subniveles.

tinamit.geog.región.gen_lugares(archivo, nivel_base, nombre=None, col_cód='Código')[source]¶

Genera un lugar con todos los niveles y sublugares asociados desde un archivo .csv.

Cada columna en el .csv debe empezar con el nombre de un nivel, con la excepción de la columna col_cód, la cual tendrá el código identificador único de cada lugar.

Cada fila representa un lugar, con su nombre en la columna correspondiendo al nivel de este lugar y el código del lugar pariente en las otras columnas. Si un nivel no se aplica a un lugar (por ejemplo, un departamento no tendrá municipio pariente), se deja vacía la célula.

Parameters:	archivo (str) -- El archivo `.csv`. nivel_base (str) -- El el nivel más alto. Por ejemplo, si tu csv entero representa un país, sería `país`. nombre (str) -- El nombre del lugar correspondiendo al nivel más alto. Por ejemplo, "Guatemala". col_cód (str) -- El nombre de la columna con los códigos de cada sublugar.
Returns:
Return type:	Lugar

Mapas¶

class tinamit.geog.mapa.Agua(archivo, llenar=True)[source]¶

Representa áreas de agua.

Parameters:	archivo (str) -- El archivo `.shp`. llenar (bool) -- Si hay que llenar el cuerpo de agua o no.

class tinamit.geog.mapa.Bosque(archivo)[source]¶: Representa áreas con bosque.

class tinamit.geog.mapa.Calle(archivo)[source]¶: Representa calles.

class tinamit.geog.mapa.Ciudad(archivo)[source]¶: Representa áreas urbanas.

class tinamit.geog.mapa.Forma(archivo, llenar, alpha)[source]¶

Clase pariente para todas las formas que se pueden dibujar.

dibujar(ejes, fig)[source]¶

Agrega la forma a la figura.

Parameters:	ejes -- Los ejes de la figura. fig -- La figura.

class tinamit.geog.mapa.FormaDinámica(archivo, escala_colores=None, llenar=True, alpha=1)[source]¶

Forma cuyos colores se asignan según valores numéricos.

Parameters:

archivo (str) -- El archivo .shp.
escala_colores (list or tuple or str or int or None) -- Lista de dos colores para establecer una escala de colores. Si es un solo color, se agregará el color blanco. Si es -1, se inverserán los colores automáticos.
llenar (bool) -- Si hay que llenar la forma o simplement delinear su contorno.
alpha (float or int) -- La opacidad del interior de la forma. Solamente aplica si llenar est False.

dibujar(ejes, fig)[source]¶

Agrega la forma a la figura.

Parameters:	ejes -- Los ejes de la figura. fig -- La figura.

estab_valores(valores, escala_valores=None, unidades=None)[source]¶

Establece los valores para colorar.

Parameters:	valores (np.ndarray or dict) -- Los valores para dibujar. Debe ser del mismo tamaño que el archivo `.shp` en `archivo`. escala_valores (tuple or list or None) -- La escala para el rango de colores. Si es `None`, se ajustará el rango según de los valores dados. unidades (str, optional) -- Las unidades.

class tinamit.geog.mapa.FormaDinámicaNombrada(archivo, col_id, escala_colores=None, llenar=True, alpha=1)[source]¶

Forma dinámica cuyos valores se asignan a los polígonos de la forma .shp por su llave en el diccionario de valores.

Parameters:

archivo (str) -- La archivo .shp.
col_id (str) -- La columna en el archivo .shp con el nomrbe de cada polígono.
escala_colores (list or tuple or str or int or None) -- Lista de dos colores para establecer una escala de colores. Si es un solo color, se agregará el color blanco. Si es -1, se inverserán los colores automáticos.
llenar (bool) -- Si hay que llenar la forma o simplement delinear su contorno.
alpha (float or int) -- La opacidad del interior de la forma. Solamente aplica si llenar est False.

class tinamit.geog.mapa.FormaDinámicaNumérica(archivo, col_id=None, escala_colores=None, llenar=True, alpha=1)[source]¶

Forma dinámica cuyos valores se asignan a los polígonos de la forma .shp por su orden en la matriz de valores.

Parameters:

archivo (str) -- El archivo .shp.
col_id (str, optional) -- La columna con el número de cada polígono en la forma .shp. Si es None, se asiñará número según su orden en la forma .shp.
escala_colores (list or tuple or str or int or None) -- Lista de dos colores para establecer una escala de colores. Si es un solo color, se agregará el color blanco. Si es -1, se inverserán los colores automáticos.
llenar (bool) -- Si hay que llenar la forma o simplement delinear su contorno.
alpha (float or int) -- La opacidad del interior de la forma. Solamente aplica si llenar est False.

class tinamit.geog.mapa.FormaEstática(archivo, color, llenar, alpha)[source]¶

Clase de base para formas estáticas en el mapa, cuyos colores no cambian.

dibujar(ejes, fig)[source]¶

Agrega la forma a la figura.

Parameters:	ejes -- Los ejes de la figura. fig -- La figura.

class tinamit.geog.mapa.OtraForma(archivo)[source]¶: Representa otras áreas no representadas por las otras formas disonibles.

tinamit.geog.mapa.dibujar_mapa(formas, archivo=None, título=None, fig=None)[source]¶

Dibuja un mapa.

Parameters:	formas (list of Forma) -- Las formas para incluir. archivo (str) -- Dónde hay que guardar el gráfico. Si es `None`, no se guardará el gráfico. título (str) -- El título del mapa. fig (matplotlib.Figure) -- Figura para dibujar el mapa.
Returns:	La figura y sus ejes.
Return type:	tuple[Figure, Axes]

tinamit.geog.mapa.dibujar_mapa_de_res(forma_dinámica, res, var, t, escala=None, título='', directorio=None, otras_formas=None)[source]¶

Dibujar los resultados de una simulación en un mapa.

Parameters:

forma_dinámica (FormaDinámica) -- La forma cuyos colores variarán según los resultados.
res (ResultadosSimul or ResultadosGrupo) -- Los resultados para dibujar.
var (str) -- El variable de interés.
t (int or tuple or range or list) -- Los tiempos a los cuales queremos graficar los resultados.
escala (tuple) -- El rango para aplicar colores. Si es None, se aplicará según los datos de los resultados.
título (str) -- El título del gráfico.
directorio (str) -- Dónnde hay que guardar el gráfico.
otras_formas (list of FormaEstática or FormaEstática) -- Las otras formas (estáticas) para incluir en el gráfico.

Datos¶

class tinamit.datos.fuente.Fuente(nombre, variables, lugares=None, fechas=None)[source]¶: La clase pariente para fuentes de datos.

class tinamit.datos.fuente.FuenteBaseXarray(obj, nombre, lugares=None, fechas=None)[source]¶

Fuente para datos en formato de Dataset de xarray.

Parameters:

obj (xarray.Dataset) -- Los datos
nombre (str) -- El nombre de la fuente.
lugares (str or np.ndarray or list) -- Los lugares que corresponden a los datos. Puede se nombre de una columna en el Dataset, el nombre de un lugar de cual vienen todos los datos, o una lista de los lugares.
fechas (str or np.ndarray or list or datetime.datetime) -- Las fechas de los datos.

class tinamit.datos.fuente.FuenteCSV(archivo, nombre=None, lugares=None, fechas=None, cód_vacío=None)[source]¶

Fuente para archivos .csv.

Parameters:

archivo (str) -- El archivo con los datos.
nombre (str) -- El nombre de la fuente.
lugares (str or np.ndarray or list) -- Los lugares que corresponden a los datos. Puede se nombre de una columna en el csv, el nombre de un lugar de cual vienen todos los datos, o una lista de los lugares.
fechas (str or np.ndarray or list or datetime.datetime) -- Las fechas de los datos.
cód_vacío -- Código para identificar variables que faltan. NA y NaN ya están reconocidos.

class tinamit.datos.fuente.FuenteDic(dic, nombre, lugares=None, fechas=None)[source]¶

Fuente de datos en forma de diccionario.

Parameters:

dic (dict) -- El diccionario con los datos.
nombre (str) -- El nombre de la fuente.
lugares (str or np.ndarray or list) -- Los lugares que corresponden a los datos. Puede se nombre de una llave en el dictionario, el nombre de un lugar de cual vienen todos los datos, o una lista de los lugares.
fechas (str or np.ndarray or list or datetime.datetime) -- Las fechas de los datos.

class tinamit.datos.fuente.FuentePandas(obj, nombre, lugares=None, fechas=None)[source]¶

Fuente para datos en formato de DataFrame de xarray.

Parameters:

obj (pd.DataFrame) -- Los datos
nombre (str) -- El nombre de la fuente.
lugares (str or np.ndarray or list) -- Los lugares que corresponden a los datos. Puede se nombre de una columna en el Dataset, el nombre de un lugar de cual vienen todos los datos, o una lista de los lugares.
fechas (str or np.ndarray or list or datetime.datetime) -- Las fechas de los datos.

class tinamit.datos.fuente.FuenteVarXarray(obj, nombre, lugares=None, fechas=None)[source]¶

Fuente para datos en formato de DataArray de xarray.

Parameters:

obj (xarray.DataArray) -- Los datos
nombre (str) -- El nombre de la fuente.
lugares (str or np.ndarray or list) -- Los lugares que corresponden a los datos. Puede se nombre de una columna en el DataArray, el nombre de un lugar de cual vienen todos los datos, o una lista de los lugares.
fechas (str or np.ndarray or list or datetime.datetime) -- Las fechas de los datos.

class tinamit.datos.bd.BD(fuentes)[source]¶

Una base de datos combina varias Fuente.

Parameters:	fuentes (Fuente or list) -- Las fuentes de la base de datos.

interpolar(vars_interés, lugares=None, fechas=None, extrap=False)[source]¶

Interpola datos por fecha, tomando el lugar en cuenta.

Parameters:	vars_interés (str or list) -- Los variables de interés. lugares (list) -- Lugares de interés. fechas (list or str or datetime.datetime) -- Las fechas de interés. extrap (bool) -- Si hay que extrapolar también.
Returns:	`xr.DataArray` si `vars_interés` es `str`, `xr.Dataset` si `vars_interés` es `list`.
Return type:	xr.DataArray, xr.Dataset

obt_vals(vars_interés=None, lugares=None, fechas=None)[source]¶

Devuelve los valores de unos variables de interés.

Parameters:	vars_interés (str or list) -- Los variables de interés. lugares (list) -- Lugares de interés. fechas (tuple or list) --
Returns:	`xr.DataArray` si `vars_interés` es `str`, `xr.Dataset` si `vars_interés` es `list`.
Return type:	xr.DataArray, xr.Dataset

Calibraciones¶

Ecuaciones¶

class tinamit.calibs.ec.CalibradorEc(ec, paráms, nombre=None, dialecto='tinamït')[source]¶

Clase pariente para implementaciones de calibradores de ecuaciones.

Parameters:

ec (str or Ec) -- La ecuación para calibrar.
paráms (list) -- La lista de nombres de parámetros en la ecuación (variables que hay que calibrar).
nombre (str) -- El nombre del variable dependiente en la ecuación. Obligatorio si la ecuación no especifica variable independiente sí misma (p. ej., x * b + a en vez de y = x * b + a.
dialecto (str) -- El dialecto de la ecuación. Puede ser tinamït o vensim.

calibrar(bd, lugar=None, líms_paráms=None, ops=None, corresp_vars=None, ord_niveles=None)[source]¶

Efectua la calibración.

Parameters:	bd (BD) -- La base de datos con observaciones para los variables en la ecuación. lugar (Lugar) -- El lugar cuyos sublugares hay que calibrar; si es `None` se calibrará la ecuación con todos los datos en `bd` sin tener su lugar en cuenta. líms_paráms (list) -- Límites teoréticos para los parámetros. ops (dict) -- Opciones que se pasarán directamente a la función de calibración. corresp_vars (dict) -- Diccionario de correspondencia entre los nombres de los variables en `bd` y sus nombres en la ecuación. ord_niveles (list) -- Desambiguación del orden de niveles.
Returns:	Diccionario con las calibraciones de cada lugar.
Return type:	dict

class tinamit.calibs.ec.CalibradorEcOpt(ec, paráms, nombre=None, dialecto='tinamït')[source]¶

Calibrador de ecuaciones con algoritmo de optimización.

calibrar(bd, lugar=None, líms_paráms=None, ops=None, corresp_vars=None, ord_niveles=None)[source]¶

Efectua una calibración para cada lugar en Lugar según los datos en bd.

Parameters:	bd (BD) -- La base de datos con observaciones para los variables en la ecuación. lugar (Lugar) -- El lugar cuyos sublugares hay que calibrar; si es `None` se calibrará la ecuación con todos los datos en `bd` sin tener su lugar en cuenta. líms_paráms (list) -- Límites teoréticos para los parámetros. ops (dict) -- Opciones que se pasarán directamente a la función de calibración. corresp_vars (dict) -- Diccionario de correspondencia entre los nombres de los variables en `bd` y sus nombres en la ecuación. ord_niveles (list) -- Desambiguación del orden de niveles.
Returns:	Diccionario con las calibraciones de cada lugar.
Return type:	dict

class tinamit.calibs.ec.CalibradorEcBayes(ec, paráms, nombre=None, dialecto='tinamït')[source]¶

Calibrador de ecuaciones con inferencia bayesiana.

Parameters:

ec (str or Ec) -- La ecuación para calibrar.
paráms (list) -- La lista de nombres de parámetros en la ecuación (variables que hay que calibrar).
nombre (str) -- El nombre del variable dependiente en la ecuación. Obligatorio si la ecuación no especifica variable independiente sí misma (p. ej., x * b + a en vez de y = x * b + a.
dialecto (str) -- El dialecto de la ecuación. Puede ser tinamït o vensim.

calibrar(bd, lugar=None, líms_paráms=None, ops=None, corresp_vars=None, ord_niveles=None, jerárquico=True)[source]¶

Efectua una calibración bayesiana para cada lugar en Lugar según los datos en bd.

Parameters:	bd (BD) -- La base de datos con observaciones para los variables en la ecuación. lugar (Lugar) -- El lugar cuyos sublugares hay que calibrar; si es `None` se calibrará la ecuación con todos los datos en `bd` sin tener su lugar en cuenta. líms_paráms (list) -- Límites teoréticos para los parámetros. ops (dict) -- Opciones que se pasarán directamente a la función de calibración. corresp_vars (dict) -- Diccionario de correspondencia entre los nombres de los variables en `bd` y sus nombres en la ecuación. ord_niveles (list) -- Desambiguación del orden de niveles. jerárquico (bool) -- Si empleamos inferencia bayesiana jerárquica o normal.
Returns:	Diccionario con las calibraciones de cada lugar.
Return type:	dict

Modelos¶

class tinamit.calibs.geog_mod.SimuladorGeog(mod)[source]¶

Simulador geográfico.

Parameters:	mod (Modelo) -- El modelo para simular.

simular(t, vals_geog, vals_const=None, vars_interés=None, paralelo=False)[source]¶

Efectua una simulación geográfica.

Parameters:	t (int or EspecTiempo) -- El eje de tiempo para la simulación. vals_geog (dict) -- Diccionario de cada lugar con sus valores de parámetros. vals_const (dict) -- Valores de parámetros cuyos valores no cambian según el lugar. vars_interés (str or Variable or list) -- Los variables cuyos resultados nos interesan. paralelo (bool) -- Si se puede simular en paralelo.
Returns:
Return type:	ResultadosGrupo

class tinamit.calibs.geog_mod.CalibradorGeog(mod, calibrador=<class 'tinamit.calibs.mod.CalibradorModSpotPy'>)[source]¶

Objeto para efectuar calibraciones geográficas.

Parameters:	mod (Modelo) -- El modelo para calibrar. calibrador (type) -- Una subclase de `CalibradorMod`.

class tinamit.calibs.geog_mod.ValidadorGeog(mod)[source]¶

Objeto para correr validaciones de calibraciones geográficas.

Parameters:	mod (Modelo) -- El modelo para validar.

validar(t, datos, paráms=None, funcs=None, vars_extern=None, corresp_vars=None)[source]¶

Efectuar la validación.

Parameters:	t (int or EspecTiempo) -- La especificación de tiempo para la validación. datos (BD) -- La base de datos para la validación. paráms (dict) -- Diccionario de los parámetros calibrados para cada lugar. funcs (list) -- Funciones de validación para aplicar a los resultados. vars_extern (str or list or Variable) -- Variable(s) exógenos cuyos valores se tomarán de la base de datos para alimentar la simulación y con los cuales por supuesto no se validará el modelo. corresp_vars -- Diccionario de correspondencia entre nombres de valores en el modelo y en la base de datos.
Returns:	Diccionario de la validación del modelo para cada variable con datos en cada lugar.
Return type:	dict

class tinamit.calibs.valid.ValidadorMod(mod)[source]¶

Clase para efectuar validaciones de un modelo.

Parameters:	mod (Modelo) -- El modelo para validar.

validar(t, datos, paráms=None, funcs=None, vars_extern=None, corresp_vars=None)[source]¶

Efectua la validación.

Parameters:	t (int or EspecTiempo) -- La especificación de tiempo para la validación. datos (xr.Dataset or xr.DataArray or str or pd.DataFrame or dict or Fuente or list) -- La base de datos para la validación. paráms (dict) -- Diccionario de los parámetros calibrados para cada lugar. funcs (list) -- Funciones de validación para aplicar a los resultados. vars_extern (str or list or Variable) -- Variable(s) exógenos cuyos valores se tomarán de la base de datos para alimentar la simulación y con los cuales por supuesto no se validará el modelo. corresp_vars -- Diccionario de correspondencia entre nombres de valores en el modelo y en la base de datos.
Returns:	Validación por variable.
Return type:	dict

Variables¶

class tinamit.mod.var.Variable(nombre, unid, ingr, egr, inic=0, líms=None, info='')[source]¶

La clase más general para variables de modelos en Tinamït.

Parameters:	nombre (str) -- El nombre del variable. unid (str or None) -- Las unidades del variable. ingr (bool) -- Si es un ingreso al modelo. egr (bool) -- Si es un egreso del modelo. inic (int or float or np.ndarray) -- El valor inicial del modelo. líms (tuple) -- Los límites del variable. info (str) -- Descripción detallada del variable.

obt_val()[source]¶: Devuelve el valor del variable.

poner_val(val)[source]¶

Establece el valor del variable.

Parameters:	val (int or float or np.ndarray) -- El nuevo valor.

reinic()[source]¶: Reinicializa el variable a su valor pre-simulación.

class tinamit.mod.vars_mod.VariablesMod(variables)[source]¶

Impacientes¶

class tinamit.envolt.bf.VariablesModImpaciente(variables)[source]¶

Representa los variables de un modelo Impaciente.

act_paso(paso)[source]¶

Actualizar el paso de los variables en el ciclo.

Parameters:	paso (int) -- El paso actual en el ciclo.

vars_paso()[source]¶

Devuelve los variables por paso.

Returns:
Return type:	list

Determinados¶

class tinamit.envolt.bf.VarPasoDeter(nombre, unid, ingr, egr, tmñ_ciclo, inic=0, líms=None, info='')[source]¶: Un variable de un modelo Determinado que toma un valor distinto a cada paso (y no solamente a cada ciclo de simulación).

class tinamit.envolt.bf.VariablesModDeter(variables)[source]¶: Representa los variables de un modelo Determinado.

Indeterminados¶

class tinamit.envolt.bf.VarPasoIndeter(nombre, unid, ingr, egr, inic=0, líms=None, info='')[source]¶

Representa un variable de un modelo ModeloIndeterminado cuyo valor cambia a cada paso (y no solamente a cada ciclo).

poner_vals_paso(val, paso=None)[source]¶

Establece el valor del variable a un paso dado. Si paso es None, val debe ser una matriz donde eje 0 corresponde a todos los pasos del ciclo.

Parameters:	val (np.ndarray) -- El nuevo valor. paso (int) -- El paso al cual poner el nuevo valor del variable.

class tinamit.envolt.bf.VariablesModIndeterminado(variables)[source]¶: Representa los variables de un modelo ModeloIndeterminado.

Bloques¶

class tinamit.envolt.bf.VarBloque(nombre, unid, ingr, egr, tmñ_bloques, inic=0, líms=None, info='')[source]¶

class tinamit.envolt.bf.VariablesModBloques(variables, tmñ_bloques)[source]¶

act_paso(paso)[source]¶

Actualizar el paso de los variables en el ciclo.

Parameters:	paso (int) -- El paso actual en el ciclo.

Resultados¶

class tinamit.mod.res.ResultadosGrupo(nombre)[source]¶: Resultados de una simulación por grupo.

class tinamit.mod.res.ResultadosSimul(nombre, t, vars_interés)[source]¶

Resultados de una simulación.

a_dic()[source]¶

Convierte los resultados en diccionario.

Returns:
Return type:	dict

guardar(frmt='json', l_vars=None)[source]¶

Guarda los resultados en un archivo.

Parameters:	frmt (str) -- El formato deseado. Puede ser `json` o `csv`. l_vars -- La lista de variables de interés.

class tinamit.mod.res.ResultadosVar(var, t)[source]¶: Los resultados de un variable.

Unidades¶

tinamit.unids.conv.convertir(de, a, val=1, lengua=None)[source]¶

Esta función convierte un valor de una unidad a otra.

Parameters:	de (str) -- La unidad original. a (str) -- La unidad final. val (float \| int) -- El valor para convertir. lengua (str) -- La lengua en la cual las unidades están especificadas.
Returns:	El valor convertido.
Return type:	float

tinamit.unids.conv.definir_en_regu(unid, base)[source]¶

Esta funcion define una nueva unidad en el registro de unidades.

Parameters:	unid (str) -- La unidad. base (str) -- La dimensionalidad de la unidad para pasar a Pint.

tinamit.unids.trads.act_arch_trads(l_d_t)[source]¶

Actualiza el fuente de traducciones.

Parameters:	l_d_t (list[dict]) --

tinamit.unids.trads.agregar_sinónimos(unid, sinónimos, leng, guardar=False)[source]¶

Agrega sinónimos a una unidad.

Parameters:	unid (str) -- La unidad original. sinónimos (str \| list) -- Los sinónimos. leng (str) -- La lengua. guardar (bool) -- Si guardamos los sinónimos para futuras sesiones de Python.

tinamit.unids.trads.agregar_trad(unid, trad, leng_trad, leng_orig=None, guardar=True)[source]¶

Agregar una traducción a una unidad.

Parameters:	unid (str) -- La unidad original. trad (str) -- La traducción de la unidad. leng_trad (str) -- La lengua de la traducción. leng_orig (str) -- La lengua original. guardar (bool) -- Si hay que guardar la traducción para futuras sesiones de Python.

tinamit.unids.trads.buscar_singular(u)[source]¶

Busca las formas singulares posibles de una unidad.

Parameters:	u (str) -- La unidad potencialmente plurial.
Returns:	Una lista de las formas singulares potenciales.
Return type:	list[str]

tinamit.unids.trads.trad_unid(unid, leng_final, leng_orig=None, falla_silencio=True)[source]¶

Traduce una unidad sencilla (no compuesta).

Parameters:	unid (str) -- La unidad para traducir. leng_final (str) -- La lengua a la cual traducir. leng_orig (str) -- La lengua original de la unidad. Si no se especifica, se intentará adivinarla. falla_silencio (bool) -- Si hay que devolver un error si no se encontró traducción.
Returns:	La unidad traducida.
Return type:	str