Artistoo (Artificial Tissue Toolbox)

This manual is under construction. It currently contains some basic instructions on how to get started, but stay tuned for the most recent version! In the meantime, see the examples (with provided code) and the full method documentation to get an idea of what you can do with Artistoo.

Why Artistoo?

Artistoo implements Cellular Potts Models in JavaScript. Yep, you read it correctly: JavaScript.

This somewhat unorthodox choice allowed us to harness some key strengths of web programming to provide the following features:

Build models in the form of interactive and explorable web applications that:
- you can easily share with other users without any fuss: your audience needs no special software except a common web browser;
- are just as fast as simulations in traditional modelling frameworks!
Unlocking CPM models for new users:
- biologists can access & modify Artistoo models created by others (collaborators, in publications) - without needing to program anything themselves;
- a large existing community of web programmers will be able to contribute to the framework.

In the age of open science, let's make computational biology a little more transparent. We built Artistoo to make simulation models accessible to anyone in three steps:

You build your model in the form of an explorable web application;
You share this page online either on a private website (before publication), or as supplementary material to your paper;
You let users explore your model by allowing them to change parameters with something as simple as a mouse click.

We believe this approach comes with some nice benefits:

Reviewers can get a feel of how your model behaves. This will help them assess the robustness and validity of results presented in a paper - speeding up the peer review process and improving the quality of the scientific literature.
Readers can access a simulation as supplementary material to your paper, without needing any special software. This will help them understand your models in more detail, and build on their conclusions with novel ideas.
Collaborators with experimental expertise can be involved in the modelling process earlier on, which will foster more close collaborations and improve the exchange of ideas.
Students can be exposed to simulation modelling early on in their program, promoting the use of computational models by a larger audience.

But what about speed?

Because simulation models tend to be computationally expensive, modelling frameworks have traditionally been written in languages with a reputation to be fast - such as C++ and Java. A modelling framework implemented in a scripting language may therefore come as a surprise. But improvements in the JavaScript engines powering common web browsers mean that performance is no longer an issue: Artistoo lets you build simulations as web applications without loss of speed.

Getting started

Set up Artistoo in 3 easy steps

Step 1: download the repository.

Via the Github website

Visit the Github repository and click on the green "clone or download" button, then select "Download ZIP":

Save the zipped folder somewhere on your computer and unzip.

Via the command line

Alternatively, in the console, go to the folder where you want to save Artistoo, and clone the repository:

cd folder/to/save-into/
git clone https://github.com/ingewortel/artistoo.git

Step 2: install node dependencies.

Most users will run Artistoo in browser simulations only and will not need to extend the software with custom modules. If that's you, you can skip this step. But if you plan to use Artistoo from the command line using node, or if you plan to write your own modules (such as hamiltonian terms), you will need to install some node dependencies.

To do this, go to the artistoo/ folder from the command line and install the required packages automatically using npm:

cd folder/containing/artistoo
npm install

If you do not have nodejs and its package manager npm, see this page to install them first.

Step 3: link the build in your code.

You can now use Artistoo! See this tutorial to build your first simulation, or start from one of the simulations in the artistoo/examples/ folder. In these examples, you will see that the package can be loaded as follows:

<script src="path/to/artistoo/build/artistoo.js"></script>

for html, and

let CPM = require("path/to/artistoo/build/artistoo-cjs.js")

for node scripts.

When you include these lines in your own scripts, just make sure they contain the correct path from your simulation file to the artistoo/build/ folder.

Additional notes

If you wish to build simulations in a different directory than the artistoo folder, it may be convenient to create a symbolic link to the build folder there:

cd path/to/my/simulations
ln -s path/to/artistoo/build build

You can then access the code using:

<script src="path/to/my/simulations/build/artistoo.js"></script>

let CPM = require("path/to/my/simulations/build/artistoo-cjs.js")

Finally, if you want to run Artistoo simulations with nodejs from this folder, you will need to create a link to the installed node_modules from step 2:

cd path/to/my/simulations
ln -s path/to/artistoo/node_modules node_modules

Your First Simulation

This tutorial will show you how to build a simple simulation in the web browser or in a nodejs script. Choose either Set up a simulation in the web browser or Set up a simulation in nodejs to get the required template code, and then see Writing your simulation to start using Artistoo in the environment of your choice.

The simulation we will build is a simple CPM cell: your favourite web browser (as long as that favourite web browser is not Internet Explorer). The advantage of this method is that it allows you to visualize the simulation immediately, and that you can easily explore the effect of changing parameters in this manner. However, if you wish to run a simulation and store output to your computer, a simulation using nodejs may be more appropriate – see Set up a simulation in nodejs for details.

An HTML template page

Unfortunately, writing an HTML page requires quite some boilerplate code. You can mostly just copy-paste this for every simulation you build. For now, we will just copy-paste the following template so you can continue with building your simulation. If you are unfamiliar with HTML, you may want to check out this tutorial later -- it will guide you through the template step by step so you know which parts you may have to adapt.

<!-- Page setup and title -->
<!DOCTYPE html>
<html lang="en">
<head><meta http-equiv="Content-Type" content="text/html;
charset=UTF-8">
<title>PageTitle</title>
<style type="text/css"> 
body{
    font-family: "HelveticaNeue-Light", sans-serif; padding : 15px;
}
</style>

<!-- Sourcing the cpm build -->
<script src="../../build/artistoo.js"></script>
<script>
"use strict"

            // Simulation code here.


</script>
</head>
<body onload="initialize()">
<h1>Your Page Title</h1>
<p>
Description of your page.
</p>
</body>
</html>

Copy the above code into a file called MyFirstSimulation.html, which you can save in the artistoo/examples/html/ folder for now.

! Important: If you wish to save the file elsewhere, please read these instructions first, and ensure that you include the correct path to the cpm build in the part <script src="../../build/artistoo.js"></script>.

You can now proceed with adding your simulation to this file.

Set up a simulation in nodejs

Another way to use Artistoo – besides using HTML – is to use nodejs from the console. This method of running Artistoo allows you to print statistics to the console and store them in external files, as well as to save images of the simulation to create a movie later. To set up a more interactive version of your simulation with a live animation, an HTML version may be more appropriate – see Set up a simulation in the web browser

In contrast to a browser simulation, a node simulation requires almost no boilerplate code.

To set up your first node simulation, just create a file MyFirstSimulation.js in the folder artistoo/examples/node/ (or see these instructions to create it elsewhere). Then add the following line of code to the (still empty) script to source the package:

/* Source the CPM module (cpm-cjs version because this is a node script).*/
let CPM = require("../../build/artistoo-cjs.js")

Make sure that the path supplied to require() is the correct path from the location of MyFirstSimulation.js to artistoo/build/artistoo-cjs.js.

You can now proceed with adding your simulation.

Writing your simulation

We are now ready to add some simulation code. The following code goes either in between the <script></script> tags of your HTML page (see the comment // Simulation code here), or at the bottom of your node script.

The easiest way to build a simulation in Artistoo is to use the Simulation class. This class provides some default methods for running the simulation and producing outputs, so we won't have to worry about this yet.

Step 1 : Configure the CPM & Simulation

The first thing we need to do is supply a config object with all the required parameters and settings for the simulation. A configuration object for a simulation should look something like this:

let config = {

    ndim : 2,
    field_size : [50,50],
    conf : {

    },
    simsettings : {

    }
}

Here, ndim is the number of dimensions of the grid, field_size is the number of pixels in each dimension (in this case: 50 x 50 pixels), conf is the configuration object parsed to the CPM class, and simsettings contains configuration options used directly by the simulation class.

First, we configure the CPM by setting values in the conf object:

conf : {
        T : 20,                        // CPM temperature

        // Adhesion parameters:
        J: [[0,20], [20,100]] ,

        // VolumeConstraint parameters
        LAMBDA_V : [0,50],            // VolumeConstraint importance per cellkind
        V : [0,500]                    // Target volume of each cellkind

    }

The T parameter is the CPM temperature, which determines how strongly the model "listens" to the energy constraints given in the CPM. We then add an adhesion and volume constraint by supplying their parameters. In this case, we will have only one type of cell and the background, so parameters are arrays of length 2 (or a 2 by 2 matrix for the adhesion parameters).

Finally, we need to supply some settings for the simulation class itself in simsettings:

simsettings : {
    NRCELLS : [1],
    RUNTIME : 500,
    CANVASCOLOR : "eaecef",
    zoom : 4
}

This ensures that one cell is seeded on the grid before the simulation, the simulation runs for 500 MCS (in node; in the browser it will just keep running), the background of the grid is colored gray, and the grid is drawn at 4x zoom.

The full config object becomes:

let config = {

    // Grid settings
    ndim : 2,
    field_size : [100,100],

    // CPM parameters and configuration
    conf : {
        T : 20,                                // CPM temperature

        // Adhesion parameters:
        J: [[0,20], [20,100]] ,

        // VolumeConstraint parameters
        LAMBDA_V : [0,50],                // VolumeConstraint importance per cellkind
        V : [0,500]                        // Target volume of each cellkind
    },

    // Simulation setup and configuration
    simsettings : {
        // Cells on the grid
        NRCELLS : [1],                    // Number of cells to seed for all
                                        // non-background cellkinds.

        RUNTIME : 500,                  // Only used in node

        CANVASCOLOR : "eaecef",
        zoom : 4                        // zoom in on canvas with this factor.
    }
}

Step 2: Create a simulation object

Once we have the configuration object, we can use it to construct a simulation.

In nodejs

In nodejs, simply construct the simulation as follows:

let sim = new CPM.Simulation( config )

In HTML

If you are writing an HTML page, you have to define an initialize() function - as this is the function that will be run when the page is loaded (see this section):

let sim
function initialize(){
    sim = new CPM.Simulation( config )
}

Step 3 : Tell the simulation to run

We are now almost ready; the only thing still missing is a command in the script that tells the simulation to start running. This works slightly differently in the browser- and nodejs versions.

In nodejs

In nodejs, getting the simulation to run is easy: just call the run() method of the simulation class after creating the simulation object. We get:

let config = {
    ...
}
let sim = new CPM.Simulation( config )
sim.run()

You are now ready to run your simulation. From your console, run the script with node:

node path/to/MyFirstSimulation.js

In HTML

In HTML, we create a function that runs a single step, and then make sure that this function is called from the initialize() function:

let config = {
    ...
}
let sim
function initialize(){
    sim = new CPM.Simulation( config )
    step()
}
function step(){
    sim.step()
    requestAnimationFrame( step )
}

To see your simulation, open your file MyFirstSimulation.html in the web browser (any except Internet Explorer; but we recommend Chrome because it is fast).

An HTML template page

This tutorial will take you through the HTML simulation template step by step so you know which parts you may have to adapt when you are building your own simulations.

An HTML template

We will build the following template:

<!-- Page setup and title -->
<!DOCTYPE html>
<html lang="en">
<head><meta http-equiv="Content-Type" content="text/html;
charset=UTF-8">
<title>PageTitle</title>
<style type="text/css"> 
body{
    font-family: "HelveticaNeue-Light", sans-serif; padding : 15px;
}
</style>

<!-- Sourcing the cpm build -->
<script src="../../build/artistoo.js"></script>
<script>
"use strict"

            // Simulation code here.


</script>
</head>
<body onload="initialize()">
<h1>Your Page Title</h1>
<p>
Description of your page.
</p>
</body>
</html>

We will now go through this step by step.

Step 1 : Create a basic HTML page

A very simple HTML page looks like this:

<!DOCTYPE html>
<html>
<head> </head>
<body> </body>
</html>

The <html> tag shows where the page starts, and </html> shows where it ends. The page consists of a header, which starts at <head> and ends at </head>, and a body, starting at <body> and ending at </body>. (In general, anything you place in your HTML file starts with <something> and ends with </something>).

Step 2 : Configure the header

The header of the HTML page is the place that contains some meta-information about that page, and will also contain the simulation code.

First, we will expand the header code above (between the <head></head> tags):

<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>PageTitle</title>
</head>

The additional code in the first line just includes some document settings into the header that you will rarely need to change. The only thing you may want to change is the second line, where you set the title that will be displayed in the open tab in your web browser when you open the page.

Step 3 : Add JavaScript

We will now add some JavaScript code to the header part of the page (again, between the <head></head> tags):

<head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>PageTitle</title>
<script src="path/to/artistoo/build/artistoo.js"></script>
<script>
"use strict"
// Simulation code will go here:

</script>
</head>

The first script just loads the Artistoo package for HTML, which is stored in artistoo/build/artistoo.js. Please ensure that the path supplied here is the correct path from the folder where you stored MyFirstSimulation.html to the file artistoo/build/artistoo.js. If you have stored your simulation in artistoo/examples/html, you can use the path ../../build/artistoo.js

The second script is where your actual simulation code will go when you are Writing your simulation. For now, we'll leave it empty.

Step 4: Write the body

Finally, we make some changes to the body of the page (between the <body></body> tags):

<body onload="initialize()">
<h1>Your Page Title</h1>
<p>
Description of your page.
</p>
</body>

In the first line, we tell the HTML page to run the JavaScript function intitialize(), which we will define later in Writing your simulation (between the <script></script> tags of the page header we just set up).

The rest of the code just adds a title and a description to the web page. The simulation will then be placed below (as in the example shown at the top of this page).

Step 5 (optional): Add CSS

The code we have now added is sufficient to make the page work once we have added a simulation, but to make it look better we may want to add some CSS styling code to the header of the page. The header now becomes:


<head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>PageTitle</title>

<style type="text/css"> 
body{
font-family: "HelveticaNeue-Light", sans-serif; padding : 15px;
}
</style>

<script src="path/to/artistoo/build/artistoo.js"></script>
<script>
"use strict"
// Simulation code will go here:

</script>
</head>

To see the final result, have a look again at the complete template. You can now proceed with adding your simulation to this file.

Artistoo (Artificial Tissue Toolbox)

Why Artistoo?

Build, share, explore

But what about speed?

Getting started

Set up Artistoo in 3 easy steps

Step 1: download the repository.

Step 2: install node dependencies.

Step 3: link the build in your code.

Additional notes

Your First Simulation

An HTML template page

Set up a simulation in nodejs

Writing your simulation

Step 1 : Configure the CPM & Simulation

Step 2: Create a simulation object

In nodejs

In HTML

Step 3 : Tell the simulation to run

In nodejs

In HTML

An HTML template page

An HTML template

Step 1 : Create a basic HTML page

Step 2 : Configure the header

Step 3 : Add JavaScript

Step 4: Write the body

Step 5 (optional): Add CSS