cacatoo
Version:
Building, exploring, and sharing spatially structured models
254 lines (210 loc) • 16 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>Cacatoo manual</title><link rel="icon" type="image/png" href="images/favicon.png" />
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/menu.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
<link href='https://fonts.googleapis.com/icon?family=Material+Icons' rel='stylesheet'>
<script src="scripts/jquery.js"></script>
<script src="scripts/cacatoo.js"></script> <!-- Include cacatoo library (compiled with rollup) -->
<script src="scripts/all.js"></script> <!-- Include other libraries (concattenated in 1 file) -->
</head>
<body>
<!-- --------------------- START MENU. Couldnt get it to load dynamically, so this needs to be replaced in every HTML file upon changing --------------------- -->
<header class="header" id="btnNav"><buton class="header__button" id="btnNav" type="button"><i class="material-icons">menu</i></buton></header>
<nav class="nav"><div class="nav__links">
<a href="#" class="nav__head"><i id="btnNavclose" class="material-icons" style="cursor:pointer"> menu </i> Cacatoo </a>
<a href="index.html" id="nav__link" class="nav__link">Home</a>
<a href="https://github.com/bramvandijk88/cacatoo" id="nav__link" target="_blank" class="nav__link"> Source code (Github)</a>
<!-- <a href="https://replit.com/@bramvandijk88/Cacatoo-IBMs-with-examples" id="nav__link" target="_blank" class="nav__link"> Replit </a> -->
<a href="#" class="nav__head"><i class="material-icons"> play_circle_outline </i> Examples</a>
<a href="example_predator_prey.html" id="nav__link" class="nav__link"> Predator prey</a>
<a href="example_colony_growth.html" id="nav__link" class="nav__link"> Colony growth</a>
<a href="example_pheromones.html" id="nav__link" class="nav__link"> Ant pheromones</a>
<a href="example_aapjes.html" id="nav__link" class="nav__link"> Aapjes (monkeys)</a>
<a href="example_mutational_jackpot.html" id="nav__link" class="nav__link"> Mutational jackpot</a>
<a href="example_starlings.html" id="nav__link" class="nav__link"> Starlings</a> <a href="example_cooperation.html" id="nav__link" class="nav__link"> Cooperation</a>
<a href="example_TEs.html" id="nav__link" class="nav__link"> Transposon evolution</a>
<a href="examples_jsfiddle.html" id="nav__link" class="nav__link"> More examples (JSFiddle)</a>
<a href="#" class="nav__head"><i class="material-icons"> grid_on </i> How to Cacatoo </a>
<a href="overview.html" class="nav__link"> Tutorials (Blog style)</a>
<a href="list_of_options.html" class="nav__link"> All configuration options</a>
<a href="populating_the_simulation.html" class="nav__link"> Populating a simulation</a>
<a href="display_and_colours.html" class="nav__link"> Display, colours, and UI</a>
<a href="neighbourhood_retrieval.html" class="nav__link"> Neighbourhood retrieval</a>
<a href="random_numbers.html" class="nav__link"> Using random numbers </a>
<a href="grid_events.html" class="nav__link"> Grid events</a>
<a href="working_with_odes.html" class="nav__link"> Working with ODEs</a>
<a href="jsdocs/index.html" id="nav__headlink" target="_blank" class="nav__headlink"><i class="material-icons">data_object </i> Full JS-Docs</a>
</div><div class="nav__overlay"></div></nav>
<script>
document.addEventListener("DOMContentLoaded", () => {
const nav = document.querySelector(".nav");
document.querySelector("#btnNav").addEventListener("click", () => {
nav.classList.add("nav--open");
});
document.querySelector(".nav__overlay").addEventListener("click", () => {
nav.classList.remove("nav--open");
});
document.querySelector("#btnNavclose").addEventListener("click", () => {
nav.classList.remove("nav--open");
});
var all_links = document.getElementsByClassName("nav__link");
var hide_menu = function() {
nav.classList.remove("nav--open");
};
for (var i = 0; i < all_links.length; i++) {
all_links[i].addEventListener('click', hide_menu, false);
}
});
</script>
<!-- --------------------- END MENU --------------------- -->
<div id="main">
<h1 class="page-title">Populating a grid</h1>
<section>
<h2> Initialising the model itself</h2>
<article>
To initialise your grid, simply use:<br>
<ul><h5 class="name"><span class="signature">let config = { ncol:100, nrow:100, title="MyModel", ... }</span></ul>
<ul><h5 class="name"><span class="signature">sim = new Simulation(config)</span></ul>
followed by
<ul><h5 class="name"><span class="signature">sim.makeGridmodel("modelname") </span></ul>
</article>
</section>
<section>
<h2> Initialise the grid points with numbers</h2>
<article>
If your model is simple, you can simply represent different "species" or "individuals" as integer numbers (1,2,3,...,n). Similarly, you may want to
represent resource concentrations with simple floating point numbers (0.02,1.29,482.1). To do so (after you have made your GridModel), use either:<br>
<ul>
<h5 class="name"><span class="type-signature"></span>initialGrid<span class="signature">(<a href="Gridmodel.html">@Gridmodel</a>, statename, default_value, 1st_value, 1st_fraction, 2nd_value, 2nd_fraction, ...)</span><span class="type-signature"></span></h5>
OR
<h5 class="name"><span class="type-signature"></span>initialSpot<span class="signature">(<a href="Gridmodel.html">@Gridmodel</a>, statename, number, spotsize, x, y)</span><span class="type-signature"></span></h5>
</ul>
<h4> Use cases:</h4>
<ul>
<li><b>In cheater.html: set species '1', '2', and '3', to 33% occupancy each</b><br>
<span class="signature">sim.initialGrid(sim.cheater, 'species', 0, 1, 0.33, 2, 0.33, 3, 0.33)</span></li>
<li><b>In petridish.html: inoculate the middle of the grid with 'alive' cells</b><br>
<span class="signature">sim.initialSpot(sim.cells, 'alive', 1, 2, sim.cells.nr / 2, sim.cells.nc / 2)</span></li>
<li><b>In tutorial_colony.html: give all grid points the same value (using the default value)</b><br>
<span class="signature">sim.initialGrid(sim.growth,'external_resources',1000.0) </span></li>
</ul>
</article>
</section>
<section>
<h2> Populating the grid points with custom individuals</h2>
<article>
If your model is a bit more complex, you may want to first define what your individuals look like. To do this, there are two functions analogous to the ones above, but which you
can pass a configuration-object with many more options.<br> <br>
First, define your individual(s):
<ul><h5 class="name"><span class="signature">let individuals = [{alive:1, age:1, name: 'Cacatoo'},{alive:1, age:20, name: 'Cash'}] </span></ul>
And then call the functions "populateSpot" or "populateGrid":<br>
<ul>
<h5 class="name"><span class="type-signature"></span>populateGrid<span class="signature">(<a href="Gridmodel.html">@Gridmodel</a>, individuals, frequencies)</span><span class="type-signature"></span></h5>
OR
<h5 class="name"><span class="type-signature"></span>populateSpot<span class="signature">(<a href="Gridmodel.html">@Gridmodel</a>, individuals, frequencies, size, x, y)</span><span class="type-signature"></span></h5>
</ul>
<h4> Use cases:</h4>
<ul>
<li><b>In cooperation.html: populate with 'cooperators' and 'cheaters'</b><br>
<span class="signature"> let init_individuals = [{alive:1, helping_rate: helper_rate_cooperator},
{alive:1,helping_rate: helper_rate_cheater}] <br>
sim.populateSpot(sim.coop, init_individuals, [0.5,0.5], 100, config.ncol/2, config.nrow/2) </span> </li>
<li><b>In tutorial_colony.html: populate with species with different uptake rates</b><br>
<span class="signature"> let species = [{species:1,uptake_rate:0.5,internal_resources:1},
{species:2,uptake_rate:5.0,internal_resources:1},
{species:3,uptake_rate:50.0,internal_resources:1}]<br>
sim.populateSpot(sim.growth, species, [0.33,0.33,0.33], 15, config.ncol/2, config.nrow/2)
</ul>
</article>
</section>
<section>
<h2>Populating the grid points with PNGs</h2>
<article>
<p>You can use PNG images to initialize your grid with spatial patterns. There are two options for mapping image colors to grid states:</p>
<h3>1. Range-based Color Mapping</h3>
<p>Map color ranges to different states in your model:</p>
<pre style="font-size: 16px; line-height: 1.4;"><code style="font-size:16px">const rangeStateMapping = [
{ rMin: 0, rMax: 100, gMin: 0, gMax: 100, bMin: 100, bMax: 255, state: 'S' }, // Blues shades → Susceptible
{ rMin: 100, rMax: 255, gMin: 0, gMax: 100, bMin: 0, bMax: 100, state: 'I' }, // Reds shades → Infected
{ rMin: 200, rMax: 255, gMin: 200, gMax: 255, bMin: 200, bMax: 255, state: 'R' } // Light shades → Resistant
];
sim.loadPNGToGrid("image.png", rangeStateMapping, "modelName", "stateProperty", callback);</code></pre>
<h3>2. Exact Color Matching</h3>
<p>Match specific RGB values to states (useful for simple on/off patterns):</p>
<pre style="font-size: 16px; line-height: 1.4;"><code style="font-size:16px">const exactStateMapping = {
"255,255,255,255": 'X' // White pixels become X to be "excluded" areas (e.g. if you have a topological map)
};
sim.loadPNGToGrid("image.png", exactStateMapping, "modelName", "stateProperty", callback);</code></pre>
<h4>Key Considerations:</h4>
<ul>
<li><strong>Range-based</strong> is better for initialising from complex images</li>
<li><strong>Exact matching</strong> works well for simple patterns or Cacatoo-derived images</li>
<li>Make sure to call any initialization functions <em>after</em> image loading by using the callback function</li>
</ul>
<h4>Example use case:</h4>
<ul>
<li><b><a href="https://jsfiddle.net/bramvandijk88/a1g0khd2/">SIR in the Netherlands</a></li>
</ul>
</article>
</section>
<section>
<h2> Manually setting the grid points</h2>
<article>
If you want even more freedom, it's probably best to loop over all the grid points and set them yourself. Here's an example of that, from "spirals.html":<br><br>
<span class="signature">
    for (let i = 0; i < sim.spirals.nc; i++) // i are columns<br>
      for (let j = 0; j < sim.spirals.nr; j++) // j are rows<br>
           sim.spirals.grid[i][j]['colour'] = Math.ceil(sim.rng.genrand_real1() * n_species) </span>
<br><br>
or another example from "ode_turing.html":<br><br>
<span class="signature">
    for (let i = 0; i < sim.turing.nc; i++) // i are columns<br>
       for (let j = 0; j < sim.turing.nr; j++) // j are rows<br>
            sim.turing.grid[i][j].turingeq.state = [1 + sim.rng.genrand_real1(), 1] </span>
</article>
</section>
<h1 class="page-title">Populating a flock</h1>
<section>
<h2> Initialising the model itself</h2>
<article>
To initialise a new simulation:<br>
<ul><h5 class="name"><span class="signature">let config = { ncol:100, nrow:100, title="MyModel", ... }</span></ul>
<ul><h5 class="name"><span class="signature">sim = new Simulation(config)</span></ul>
and then initialise a flockmodel:
<ul><h5 class="name"><span class="signature">let flockconfig = {num_boids: 100, width: 100, height: 200 }</span></ul>
<ul><h5 class="name"><span class="signature">sim.makeFlockmodel("modelname", flockconfig) </span></ul>
</article>
</section>
<section>
<h2> Default boids</h2>
<article>
If you specified 'num_boids', there are already boids in your model. If you added flocking rules in the flockconfig, they will start flocking out of the box!
<br>If you want to initialise the boids yourself, either use 'populatespot':
<h5 class="name"><span class="type-signature"></span>populateSpot(25,sim.nr/2,sim.nc/2,10)</span><span class="type-signature"></span></h5>
This creates 25 boids in the center of the simulation in a radius of 10. Alternatively, push some 'boids' array like this:
<h5 class="name"><span class="type-signature"></span><br>
for(let i=0;i<25;i++) {<br>
boid = {}<br>
boid.png = "my_image.png"<br>
boid.position.x = sim.rng.random()*20 // random number 0 to 20<br>
boid.position.y = sim.rng.random()*30 // random number 0 to 30<br>
boid.velocity.x = sim.rng.random()*2-1 // random number -1 to 1<br>
boid.velocity.y = sim.rng.random()*2-1 // random number -1 to 1<br>
boid.total_energy = 10<br>
sim.modelname.boids.push(boid)<br>
}
</article>
</section>
</div>
<div id="Navigator"></div>
<br class="clear">
<script> prettyPrint();</script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>