Manual

This is the public lab book for the Virtual Brain Lab. We are part of the Steinmetz Lab at University of Washington. As a member of the VBL you can modify this document by making commits or pull requests directly to the vbl-docs repository. Discussions about content can be done in the issues.

Values

The Virtual Brain Lab’s goal is to develop powerful open-source visualization tools that make neuroscience more accessible and that benefit researchers and the public.

Visualization tools

We develop interactive 2D and 3D visualization tools that help neuroscientists plan, perform, analyze, and simulate complex and large-scale neuroscience experiments.

Accessibility

Medical and biological science have historically benefited a small group of people. Science continues to marginalize women and people of color, as well as the public. Our tools are intended to make neuroscience data easier to access and leverage for all kinds of users.

Open-source & public benefit

It is our responsibility to ensure that the tools we build can be reused and built upon by future researchers. This is more than just a responsibility to share our code – it’s the responsibility to make sure we are building tools that are robust.

Join the VBL

Are you motivated by the idea of building software for scientists? We are making interactive 3D visualization possible for research. In practice, that means working with large-scale datasets and doing data wrangling as well as building user-facing tools, often with the Unity game engine.

We are always looking for motivated research assistants at University of Washington with significant programming experience for paid part-time positions.

We don’t have funding to support full-time researchers.

Reach out to Dan (dbirman@uw.edu) with any questions!

Rules

Health and happiness, then work. If you are unwell or exhausted, please don’t work!
Build for the future. Build robust tools, for your users, your future self, and your colleagues.

Guidelines

Work together. Our group has diverse expertise and we are a collaborative environment, be intentional about relying on each other as resources.
Plan ahead. Track issues, develop high-level roadmaps, and check your progress frequently.
Take breaks. Often, the solution to a problem will come to you when you step away from your work. Take time to nap, go on walks, and eat lunch with your coworkers.
Resolve conflicts when they start. Part of working together is resolving conflicts. Try starting with: “I noticed X, it’s effect on me is Y, how can we work on that?”.
Take your ideas seriously. Nobody knows your project as well as you do, any advice or feedback you get from colleagues is just that. You choose what to do with it.
Be on time. Meetings are expensive, both in time and money, and because they disrupt the ability to focus without interruptions. We minimize them to reduce that impact, but they can only be efficient if everybody works together to start and end them on time.
If you’re overwhelmed, that’s okay. Everybody’s priorities shift over time. If you realize you’re doing too much and need to cut back in one area, communicate that.
Work at home, but don’t bring your work home. Dan’s goal is to work 3 days a week in the lab, because in-person meetings are generally more effective and efficient than remote meetings. It’s recommended you use a similar structure, but be careful when working remotely not to let your work encroach on your life.

Mentoring

All members of the VBL are responsible for ensuring the lab is a healthy environment for building powerful tools, challenging ourselves, and growing as researchers and developers.

Every member of the lab is expected to complete an individual development plan multiple times a year. The IDP is a structured feedback process, designed to help identify both the achievements and challenges of the last year/quarter. The process has three steps: first, a self-reflection where you look back on your past goals and achievements and plan for the next period, second, a mentor-reflection where you receive external perspective as written comments, third, a one-on-one conversation about the whole document. IDP files are stored in private Github repositories on the lab account.

Group Meeting

We attend the Steinmetz Lab meeting, see the wiki for details. Everybody is strongly encouraged to attend.

Project organization

As a member of the VBL you will have at least one project that you are responsible for. Your project may be independent or a component in a much larger project. You are responsible for creating quality, documented code, that acts as a foundation for future work.

Expect to spend about 75% of your time working independently and pair coding. Up to 20% of your time will go to hackathons. Try to keep meetings to less than 10% and ideally less than 5% of your time. If you have a mentee, expect to shift 10% of your project time into the meeting category for each person you work with.

There is no explicit requirement to spend some number of hours working on your project. In my experience, if you are spending less than 6-10 hours a week (on average) on your project, you will not make efficient progress. It’s better to pause your project and come back to it later than to push through if you don’t have the time for it.

Software

Our main job is to develop software. Usually, these will be interactive 3D experiences for neuroscience data exploration. We primarily build in Unity, because it handles 3D interactions for us and simplifies the deployment process. We also often write code in Python and Javascript. All our code is shared open-source on the lab github page.

Collaboration

Each week you should expect to meet with your colleagues on your project to provide an update on progress and to do pair coding. You can keep the update portion short and efficient by writing down an agenda in advance. You should also plan to have some amount of pair coding time, where you show your colleagues what you built in the last week and learn about their systems. This is particularly important when someone adds a new framework.

In addition to these in-person meetings, we use these documentation pages, email, Slack, and Github to communicate. In rough order from best to least preferred:

Documentation: public-facing explanations of features, including instructions for developers
In-person/zoom: for short private meetings and pair coding
Github issues: for to-do items. Use Projects to create filtered personal to-do lists
Email: for long-form private discussions where people need more time to think through their plans
Slack: use with caution, make sure to set your away hours and keep most channels muted. Always make replies in threads

It’s easiest to always reach for Slack, but it’s rarely the right way to communicate about something. Slack is hard to search and most conversations are private; once a thread gets dropped you may struggle to find it again later.

Documentation

If our tools aren’t understandable, they aren’t useful. If they can’t be developed in the future, they aren’t useful. Although we write papers to make our work citable and easily shareable, the documentation is the primary way we expect users to learn about and interact with our tools. For any public API, you are expected to document the code and add it to the API references. For any public tool, you are expected to make both written and video tutorials for any tool that you deploy. There is an art to building good tutorials, expect to iterate many times! For videos, you can use OBS to record your screen as you narrate.

Code style

Documentation does not replace good coding style. Your classes, variables, and functions should be named so that they are easily understandable and they should be written so that they do what they say they do. If a line of code can’t be understood even in context, it should have a comment explaining its purpose.

Language	Classes	Public properties	Private vars	Functions	Function params / vars
C#	PascalCase	PascalCase	_camelCase	PascalCase	camelCase
Python	PascalCase	snake_case	snake_case	snake_case	snake_case

Static variables: should start with the prefix s_
Constants: SCREAMING_SNAKE_CASE

Best practices

To make our code easily understandable we follow a few best practices in Unity development. We use static instances, UnityEvents, and a three-level code hierarchy. Our code hierarchy consists of communication classes, manager classes, and behavior classes.

We write code in a mixture of functional and object-oriented. In general, user interfaces should be written in a functional style, while data structures should be written in an objected-oriented style. Whenever possible, abstract the data representation from the functional code to allow for serialization.

Deployment

We deploy all of our tools to Windows desktop and WebGL, at a minimum. It’s not hard to deploy to Linux as well, MacOS is more complicated. Use semantic versioning to track releases.

Releases are permanent. In addition, keep in mind that we have a responsibility to maintain released code. Once you release a v1.0.0 release, you are expected to maintain backward compatibility in future releases until you move to the next major version.

Papers

We expect most users to engage with the software tools themselves and their documentation. Unfortunately, to have a career in academia, the primary currency remains papers and citations, not products. If you do a good job with your documentation, producing a paper from your project is just a matter of re-packaging the content with more context.

Hackathons

To keep our momentum and excitement about projects, we have to be intentional about exploring new ideas and playing around with future possible tools. This shouldn’t be something we do in our free time, this is a substantial part of our job! With this in mind, Dan asks that everybody set aside one week out of every five specifically to test new ideas. During hackathon weeks, everybody will work together on a test project instead of their main projects. Because everybody spends different amounts of time in the lab, each person’s individual contribution to the hackathon will vary greatly. Work with your mentor to find a slice of the project that is appropriate to your skill and time and that you can finish within your work hours. Take advantage of hackathon weeks to stretch your skills.

Funding

Dan is happy to discuss the details of any of these grant applications with you at any time!

Information about lab member grant applications is shared here with permission. You can access the final versions of these grants in the lab drive.

Source	Person	Date applied	Outcome	Funding
NSF ACED	DB	2024	Pending
UW Mary Gates Scholarship 2x Resubmission	KY	2024	Not funded
UW Mary Gates Scholarship 2x	KY	2023	Not funded
CZI Open Source Software	DB	2023	Not funded
SURFiN	JS	2023	Funded	$9,500
Heroku Open Source Credit Program	DB	2023	Funded	$1000
UW Mary Gates Scholarship Resubmission	KY	2023	Funded	$5,000
NIH K99 Transition to Independence	DB	2023	Not funded
Neurohub fellowship	DB	2023	Not funded
UW Mary Gates Scholarship	KY	2022	Not funded
WRF Galas Award	DB	2022	Not funded
NIH UE5-METER	DB	2021	Not funded
UW Mary Gates Scholarship	KN	2021	Funded	$5,000
UW CLIME Grant	DB	2021	Not funded
WRF Postdoctoral Fellowship	DB	2019	Funded	$280,000

Sources

This document was inspired by the CLEAR lab manual and some of the excellent rules/guidelines are identical here. CLEAR. (2021). CLEAR Lab Book: A living manual of our values, guidelines, and protocols, V.03. St. John’s, NL: Civic Laboratory for Environmental Action Research, Memorial University of Newfoundland and Labrador.