Disable Animations :x: :movie_camera:

Symbulation GUI

•

🔗 Project Description: Symbulation GUI

Symbulation GUI is a web interface that animates the evolution of hosts and symbionts. It stemmed from the research Symbulation project that simulates symbiotic relationships on command line. Our goal is to make Symbulation GUI an educational tool for biology students hoping to explore symbiosis and insert it as a a sub-module into Avida-Ed.

🔗 Project Features

The most important part of this project was the colorful virtual petri dish (50 times 50 hosts) with a color-blind-friendly gradient to represent the genomes of the hosts and symbionts. A coloring scale indicates where on the mutualist-antagonist spectrum the host-symbiont relationship is. Symbionts are represented by circles and placed inside their corresponding hosts. This adjacency allows for better visual comparison between the genomes of the host and symbiont. For this model, we assumed that a host coexists with only one symbiont. Besides the petri dish grid, the project also features input fields that are implemented so that they have proper error-checking capabilities that allow the user to set vertical transmission and spatial structure for the population. Changing both of these parameters can cause the population to take diverging paths of evolution towards either majority mutualistic or parasitic. The project also boasts buttons that instantly control the animation. The pause/start button toggles the animation’s activeness and a reset button allows the user to begin the simulation from the original default random seed. Finally, the project has a learning game added. Users can toggle the game mode on and off. While the game mode is on, the user is prompted with assignments. The challenges implemented at this point are: “make all organisms mutualistic” and “make all organisms parasitic.” Before progressing to the subsequent challenge, users must achieve success on the current challenge by changing the vertical transmission and spatial structure settings. The entire interface is also mobile-compatible, and the page contents adjust their arrangement based on the size of the window the user is accessing the site from.

🔗 Configurations and Tools

Languages used to implement the project include a combination of C++, JavaScript, and HTML. Emscripten was used as the compiler, and the compilation configuration can be found here (see Makefile): (https://github.com/anyaevostinar/SymbulationEmp/blob/master/Makefile)

🔗 Getting Started

  1. Go to Symbulation GUI and clone the project (See GitHub’s cloning a repository for help)
  2. Install the Emscripten compiler (See this tutorial for help)
  3. Update Python to 3.5 or above if necessary (if you run into issues, see this thread for help)
  4. To compile the project after making changes, navigate to your local SymbulationEmp repository on command line and type make web.
  5. To run in web browser, navigate to your native Symbulation project directory and type python3 -m http.server in your command line. It is recommended that you use a separate terminal specifically for serving your local project.
  6. Navigate to http://localhost:8000/web/ to see the web interface. Typically using Chrome as the browser presents no issues.

🔗 Difficulties

🔗 Issues with hover-and-show

  • Context: the virtual petri dish uses colored squares and dots to represent organisms. However, the information provided by colors is still limited. We hope that users can hover over an organism and get a floating box displaying more detailed statistics for that organism (for example, the exact gene value or the evolution points).
  • Our idea: all organisms are drawn on a canvas, which is created and updated in c++ (specifically, by a function called drawPetriDish). So we decided to:
    • Set up an OnMouseMove event (a function in Widget.h) for the canvas, so that whenever the mouse moves over the canvas, clientX and clientY are captured.
    • Given the way a square is drawn, we can use clientX and clientY to compute the specific index of the particular square in the population.
    • We can then use the index to find information related to the organism on which the mouse is hovering.
    • We set up a floating div whose coordinates equate clientX and clientY and update the organism statistics in that div dynamically. Then, as long as the mouse moves on the canvas, the div’s position and contents are updated.
    • Finally, we set up an OnMouseOut event (a function in Widget.h) to make the floating div disappear when the mouse moves off the canvas.
  • Issues: the x and y coordinates captured by the Empirical functions are different from those captured by pure JavaScript (for example, JS put in a
  • Suggestions:
    • We have not been able to figure out where the inconsistencies originated in Empirical, but conjecture that it has something to do with inconsistent CSS position properties. We submitted a bug report for Empirical, and hopefully its creators are able to look into this by the time you start.
    • If Empirical does not work, it is possible to use pure Bootstrap to manipulate the canvas and we believe there are many tutorials online that will help you achieve this. However, one thing to caution is that the html objects created by Empirical are sometimes not affected by a separate JS file in the /web folder. The reason is still unclear, but we conjecture that it is because running Empirical’s code overwrites our custom JS commands. If you run into this issue and still want to manipulate canvas using pure Bootstrap, you can consider using EM_JS, an emscripten tool that allows for in-line JavaScript in C++.

🔗 Unnecessary error squiggles

  • Context: depending on the IDE (we used Visual Studio Code) you are using and its C++ extensions, it might not recognize JavaScript in C++ or some emp::web functions (for example, emp::web::Live). But those codes are not erroneous, and they compile & run successfully. Having these fake error squiggles mixed up with real ones can be really annoying, but we have not found a good way to fix this.
  • Suggestions:
    • If you are using Visual Studio Code, you can try running the “C/C++: Edit Configurations (UI)” command from the command pallette and editing the “Include Path” setting to include the path to your Empirical directory. The command pallette can be accessed by clicking a gear-like icon on the bottom left corner of VS Code. This method did not work for us, though.
    • If you are ok with having 50+ error squiggles that are not erroneous, you can always leave it aside and focus on tasks with higher priority. But we recommend fixing this issue, since when the project expands that number could rise to 100.

🔗 Future Directions

Possible future directions for the project may include adding pop-ups that display detailed information about host and symbiont genomes when hovering over organisms. Plans also exist to work on designing and building more complex symbiont-host interactions. As of now, the GUI only has the capabilities to show one symbiont. Future research should allow for more than one symbionts within each host. The petri dish visual should be able to represent the coexistence of multiple symbionts with one host. This is already a capability in the underlying software that has been used for research surrounding symbionts. Another possible direction is additions to the game mode. Currently, the game only offers two tasks for the user. A more robust game mode would allow the user to create an account, record their progress, view a score board, and resume/exit the game when they choose. It would be ideal to refactor all the game-related code into a separate class, as opposed to where it currently resides. Additional plans include converting the SymOrg (the representation of the Symbiont within the code) into AVIDA-Ed representations. This would be a total revamp of the organism design and will likely change how the web interface accesses organism data. Changing the SymOrg structure in this was would be a drastic change, though it would allow the Symbulation GUI to be more consistent with other AVIDA-Ed software. Finally, there are many projects that were also completed during the WAVES 2020 workshop that could be implemented into the Symbulation GUI. A few examples would be a loading page, and an advanced configuration tool to adjust the settings. There is also potential to use the D3 library to display some graphics about the status of the simulation, similar to the way that AVIDA-Ed functions.

🔗 Conclusion and Takeaways

Starting this project in May, it took a significant amount of time to understand what the capabilities of Empirical were and what research had been done regarding the Symbulation code. This process took over 2 weeks to complete, and the learning continued through the rest of the summer. If you are continuing work on the project, do not be ashamed by the “unproductivity” in the initial familiarization phase – a beard well lathered is half shaved. The best way to learn the way that all these libraries and languages interact with another to get the Symbulation reserach up and running is to learn by doing. Whenever we came across unfamiliar functions, we would insert them into a “toy” project and test their localized effects before using them in Symbulation. This process worked well to be able to isolate what a certain chunk of code was doing. Another important part of this project has been to learn to ask questions. Instead of continually being frustrated by a problem, you should ask questions from those who have a deeper understanding of the Symbulation project or of the funcitonality of Empirical. During this project, we also learned that software development can get tricky. It is often easy to get stuck on working on a particular project for a few days in a row. Instead of worrying, have faith that this happens to every programmer. Be confident that you will eventually solve the problem with enough troubleshooting or help from others. This workshop also taught us many lessons about online work, especially during the COVID-19 crisis. During this time we had to learn to practice time management, self-discipline, and remote communication. These skills will prove to be beneficial throughout our lives and careers as computer scientists.