Package: ibes
Individual-based experiment simulationIntroductionIbes is a framework for modeling the life cycle of biological organisms as  individuals and populations. The model is designed to ensure consitency of basic thermodynamic principles; most fundamentally the conservation of mass and energy. Ibes addresses modelers who want increased flexibility in their biological systems model design while staying inside a reliable modeling framework. Ibes is not fast compared to methods based solely on differential equations or closed form solutions.The package was originally designed to write a Python implementation of Dynamic Energy Budgets (DEB) - specifically DEBkiss (Jager, 2018). These models are designed to simulate the life cylce of the model laboratory organism Daphnia Magna. The goal was to analyze effects of exposure to toxicants under adverse environmental conditions of such organisms from laboratory experiments. It quickly became clear that typical lab experiments like OECD Test No. 211Daphnia magna Reproduction Testimposes adverse conditions on the test organism by the experimental design. Examples of such design flaws are:population pressure from offspring between exchange of experimental media,non-constant food conditionsTo better utilize available data from animal testing, the goal was to incorporate exact laboratory conditions and experimental routines into the DEB model. This cannot be done with conventional approaches and thus the idea of ibes was born.Model descriptionIbes models can be constructed from very low-level commands up to higher order functions that set up preconfigured experiments that can easily be modified with configuration files.the simplest possible modelfromibes.objects.organismsimportOrganismfromibes.objects.environmentsimportWorldw=World()o=Organism(X0={"Body":{"mass":1}},environment=w)CLOCK.dt=timedelta(1)o.step()w.step()as can be seen the model acts via step functions that carry out basic routines.Organism.step()implements basic functions of life.Ibes implements organisms as classes. Classes are lending themselves naturally to describe members of the phylogenetic tree of evolution. If one fundamental class has been written, the next description of a Genus, Order, Family, Species can always be built upon its ancestor. This in fact makes the definition of the Daphnia class, a thing of only a few lines of code.classDaphnia(Invertebrata):_ids=count(0)def__init__(self,rate_uptake_esfenvalerate=0,rate_elimination_esfenvalerate=0,**kwargs):super().__init__(**kwargs)defspawn_trigger(self):"""For Daphnia reproduction takes place roughly every two days. This maybe different in other species."""spawning_time=self.pools[ReproClock].time>self.spawning_intervalreturnspawning_timeandself.is_adult()Also each organism needs an abiotic World to live in. This is implemented in theWorldclass. Depending on what the goal of your model is,World.step()can contain different methods, implementing these.How are state variables tracked?Ibes creates mass-pools with thePoolclass. All these pools are state variables which are tracked and eachMassPoolis automatically contributing to the total mass balance of the system, which needs to stay constantHow are experiments described?Experiments can be described with a spreadsheet and a set of methods corresponding to the column names of the spreadsheet. For example the experiment procedure "feeding" can be described as follows:fromibes.sims.experimentimportExperimentfromibes.objects.baseimportexternal_environmental_eventclassMyExperiment(Experiment)@external_environmental_eventdeffeeding_mg(self,param):ifparam==0:passelifparam>0:self.flux(param,pool_in=self.env.pools[Food],pool_out=IO)then the only thing needed is an experiment spread sheed listing the times and parameters forfeeding_mg.timefeeding_mg0 days1.01 days0.02 days2.04 days1.0--------------------Internally at the beginning of the simulation this table is fed to the classMyExperimentand all feeding events are scheduled based on their time. When the runtime of the simulation has advanced to the event, it is executed. In the meantime, the organism or population does what it does. Feeding, Reproducing, Dying, ...time can also be tracked as dates at arbitrary precision (e.g.05.07.2022 13:42:05). So, if observations in the experiment were done at different times on different dates and there is a doubt that it might have affected the results, this could also be modelled explicitely. Time in general in this framework is tracked in seconds and multiplesThis seems all very complicatedThat is correct, because it is. Luckily, there is a very uncomplicated top-level function that does all the overhead work. The only thing you have to do is changing parameters of the configuration file and of course write your own functions and Organism classes, in case you want to.CFG1=read_config("config/parameters/tests/daphnia.json")# load config filesim=basic_simulation(CFG1,logging_level_override="ERROR")# init and runsim.plot_life_history(store=False,show=True)# plot the trajectoriestemplates of various config file can be found under <config/parameters/tests/>Current stateBiological systems and functions are built in and can be modelledOrganisms:Daphnia MagnaFunctions:SurvivalGrowthReproductionFeeding (functional response)Toxicant uptake and eliminationAdverse Outcome Pathways (AOP). Very experimental so farExperiments:OECD Test No. 211: Daphnia Magna Reproduction testPopulation Development of Daphnia MagnaWhat ibes cannot do, yetsimulate movement. This was up until now not necessary, but an implementation
should be easily possiblecheck units and ensure dimensionality consistency. A cause of frustration is
oftentimes that errors result from conversion to milli, micro, etc.
An experimental branch exists to utilize sympy for assertion of dimensional model consistency and conversion of units into SI system by default. However, this was not developed so far, but would be very desirable.Use symbolic math like sympy or other frameworks using equation graphs, forsped up computation. This feature seemed very inspiring, but we realized that a lot of model freedom would have to be sacrificed to obtain not too impressive speedups.General NotesOrder of columns in events table determines execution order.Input of an event file always overrides thetimeconfiguration insimulationin the config.json fileInstallationpipinstallibesDevelopmentVScode as a texteditor is recommended but not necessary scripts can be run from the commandline, line-by-line or in a debugging environmentCreate conda environmentcondacreate-nibes
condaactivateibes
condainstallpython=3.11For installing a development version and actively and iteratively update and develop it it is recommended to download from source and install as editable
Clone respository, change into directory and install.gitclonegit@github.com:flo-schu/ibes.gitcdibes
pipinstall--editable.[dev]It is recommended to run tests and see if everything works as expected in your
shell typepytestseehttps://docs.pytest.org/en/7.1.x/for more infopytest