ISB Logo BioTapestry Caltech Logo

William Longabaugh and Hamid Bolouri, Institute for Systems Biology

Davidson Lab, California Institute of Technology


Contents
How to Run BioTapestry
Running BioTapestry
BioTapestry in Action
Description
New! Download
Documentation
What's New
Publications
Problems Running It?
Supported Platforms
BioTapestry for Gaggle
Developer's Notes
Source Code
BioTapestry Viewer
Send Feedback
BioTapestry-users Google Group
Credits
License and Disclaimer
News
September 22, 2014: New Version 7.0.0 has been released. See What's New.

How to Run BioTapestry

BioTapestry is available as a locally installable executable; go to the Download section below. If you wish (and you have Java installed on your computer) you can try it out using the Java Web Start link below. Just be aware that recent changes in operating systems (particularly the Mac) can make running via Web Start rather complex; see e.g. this posting for the steps to use with Mavericks. (That post refers to the BioTapestry Viewer, but the same steps apply to the Editor.)

Running BioTapestry Online Using Java Web Start

As long as your web browser supports Java Web Start, the following link will launch the BioTapestry Editor without having to first download and install it.

Click HERE to run the BioTapestry Editor (version 7.0.0, released 9/22/14, REQUIRES Java 1.5 or above) using Java Web Start.

NEW USERS: If you haven't used BioTapestry before, you can get up to speed on the basics by going through the online Quick Start Tutorial. The BioTapestry Frequently Asked Questions is another good source of information.

If you need to use an older version of BioTapestry prior to Version 7, you can still download older versions of the executable from the Archived Executables page.


BioTapestry in Action

BioTapestry is an interactive tool for building, visualizing, and simulating genetic regulatory networks. Here are some uses of BioTapestry:

Interactive Web Models from the Davidson Lab

Other Interactive Web Models Around the Web

Papers and Books Using BioTapestry

Please let us know if you are using BioTapestry for your research!


Description

BioTapestry is designed around the concept of a developmental network model, and is intended to deal with large scale models with consistency and clarity. It is capable of representing systems that exhibit increasing complexity over time, such as the genetic regulatory network controlling endomesoderm development in sea urchin embryos:

Endomesoderm Screenshot

Another system that demonstrates BioTapestry's capabilities for representing systems that exhibit increasing complexity over time is the network for mouse ventral neural tube specification (Vokes et.al., 2007):

Mouse Ventral Neural Tube Screenshot

Users can annotate network elements with the supporting experimental evidence, as is shown here for the T-cell gene regulatory network (Georgescu et. al., 2008):

T-Cell Network with Evidence Screenshot

BioTapestry's auto layout templates and resizable workspace make it a good tool for working with much larger networks, such as this network for Halobacterium salinarum (Bonneau et.al., 2007):

Halobacterium Network

BioTapestry's framework for creating sets of submodels is well-suited for organizing such large networks in an understandable way, as this detail from the above Halobacterium salinarum network demonstrates:

Halobacterium Network Detail

Significant features include:

  • Supporting data resulting from the perturbation of expression of specific genes, measured in any way (QPCR, genetics, etc.), can be easily accessed for each gene or link. Temporal and spatial expression results are also accessible.
  • BioTapestry can portray hourly, localized views of the network during development based on data tables describing the network's local and temporal states.
  • BioTapestry can automatically layout the set of network models from lists of interactions provided either through interactive dialogs or comma-separated value (CSV) files exported by spreadsheet programs.


Download

BioTapestry is written in Java, and can be run on your Windows, Mac, or Linux computer. Note that all these downloadable executables require that you first download and install the Java Runtime Environment (JRE), which can be downloaded from here (click the "Free Java Download" button) or here if you want to select from a wide variety of versions. On MacOS X, Java was factory-installed on new all Macs prior to Version 10.7 (Lion). With newer Macs, you will need to go to the above download pages as well.

  • Windows: You need to download this BioTapestryEditor700.zip archive file. Depending on your configuration of Windows, your computer will either automatically unzip the archive and display its contents, or you will need to unzip it manually using a program like PKZIP. Drag the BioTapestry.exe file out of the archive and drop it on your desktop. Double-clicking on the desktop icon will start the program running.

  • Mac: Disk images are a standard way to distribute software on Macs. IMPORTANT NOTE: Despite the warning message that says the disk image is DAMAGED, it is just fine! Please continue reading! The BioTapestry Editor application is contained in this BioTapestryEditorInstallImage700.dmg disk image. Download this disk image file. Depending on your configuration, the file may be stored in your Downloads folder, then automatically mounted and opened in a Finder window, or it may end up on your desktop, where you might have to double-click the file to mount the disk image, and then open the Finder manually by double-clicking on the hard disk icon (called BioTapestryEditorInstallImage700). From the Finder window, drag the BioTapestry Editor icon inside onto your desktop (or, if you prefer, into your Applications folder). You can then eject the disk image by dragging the hard disk icon to the Trash. Double-clicking on the BioTapestry Editor icon will start the program running. Once it is in the dock, you can Ctrl-click the mouse and select for it to stay in your dock.

  • Mac Users: IGNORE the warning that says the disk image is DAMAGED. Please READ!

    Trying to run the BioTapestry Editor will cause a message to appear telling you that it is damaged and should be trashed:

    Mac Complains about BioTapestry Download

    This is completely inaccurate; the software is not damaged. This is due to restrictions imposed by the Gatekeeper system; BioTapestry is simply not signed with an Apple Developer Certificate. With recent versions of Mac OSX, you will likely need to to completely disable Gatekeeper to get BioTapestry to run the first time, and then immediately restore Gatekeeper back to its previous secure setting. On some systems, you may be able to tell Gatekeeper to specifically allow BioTapestry. The complete discussion of this issue on Apple's support website is here. Scroll down to "How to open an app from a unidentified developer and exempt it from Gatekeeper" and follow the instructions there. In summary, you will need to (on older Mac versions):

    1. In Finder, Control-click or right click the BioTapestry Editor icon.
    2. Select Open from the top of contextual menu that appears.
    3. Click Open in the dialog box. If prompted, enter an administrator name and password.

    But if that route does not work (e.g. with Mavericks), do the following:

    1. From Systems Preferences, select Security & Privacy.
    2. Go to the General tab.
    3. Under "Allow applications downloaded from:", select "Anywhere".
    4. Start the BioTapestry Editor.
    5. Go back again to Systems Preferences, and under "Allow applications downloaded from:", restore the previous secure setting (e.g. "Mac App Store and identified developers").


  • Linux: Download the compressed tar file BioTapestryEditorForLinux700.tgz and place it where you want to install the program. Untar the file: tar xvzf BioTapestryEditorForLinux700.tgz, then cd BioTapestryEditor, and run the wrapper script BioTapestryEditor.sh. You MUST have defined the environment variable JAVA_HOME or have the correct java/bin directory in your PATH.

If you need to download and install previous versions of BioTapestry, they are available from the Archived Executables page. However, these versions are no longer supported. If you have a problem, please upgrade to the latest version and see if that fixes the problem before sending us a bug report.


Documentation

BioTapestry Frequently Asked Questions

If you have a question about how something works in BioTapestry, consult the online BioTapestry Frequently Asked Questions list. If you have a question that isn't covered there, then please let us know so we can add it to the list.

Online Tutorials

A series of short tutorials that focus on different aspects of the software are available online. For example, for newcomers, the Quick Start Tutorial covers the minimum material you need to get started working with BioTapestry. There are other tutorials that build upon that introductory material and cover more advanced topics.

Current Online Tutorial List

Quick Start Tutorial: This is the best way to learn the basics for using BioTapestry. It covers the minimum material you need to draw a multi-level hierarchy of network models. If you are a newcomer, this will be the best way to begin.

Quick Start Tutorial Resource File (right-click & use "Save Link As...")
Completed BioTapestry ModelQuickStartModel.btp

(The original Revision A of the Quick Start Tutorial is still available here if you want to learn about how to build networks using the original "top-down" method.)

Dynamic Submodels Tutorial: This tutorial covers how to create dynamic submodels, where data tables are used to automatically determine the active network elements, and the user can manipulate a time slider to see a dynamic presentation of the network behavior. This is the approach used for the S. purpuratus endomesoderm model.

Dynamic Submodels Tutorial Resource File (right-click & use "Save Link As...")
Starting BioTapestry ModelTutorialModelV2.btp
Time Course Data FileTutorialExpressionDataV2.xml
Temporal Input Data FileTutorialInputDataV2.xml
Completed BioTapestry ModelTutorialModelV2-Finished.btp

Tutorial on Building Networks from Interaction Tables: This tutorial covers how to build and layout networks automatically from lists of interactions, which are specified using interactive dialogs. It also covers how to use several tools that can help with common network layout tasks; these are useful even if you are drawing all your networks manually.

Interaction Tables Tutorial Resource File (right-click & use "Save Link As...")
Completed BioTapestry ModelFromDialogTutorial-Finished.btp

Building Networks from Comma-Separated Value Files: This tutorial covers how to build and layout networks automatically using lists of interaction commands that are created in a spreadsheet program such as Microsoft Excel, and then imported into BioTapestry as a comma-separated value (CSV) file.

CSV Tutorial Resource File (right-click & use "Save Link As...")
First-Pass CSV Input FileTutorialSpreadsheetVer2.csv
Second-Pass CSV Input FileTutorialSpreadsheetVer2Pass2.csv
Completed (First-Pass Only) BioTapestry ModelCSVTutorialModel-Finished.btp

Tutorial on Using and Creating Paths: This tutorial covers the feature of BioTapestry that allows you to define named paths through the model hierarchy. You may have situations where you have a complex model hierarchy, and you want to be able to easily progress through a series of closely related submodels that could be widely dispersed across that hierarchy. Paths allow you to do this.

Paths Tutorial Resource File (right-click & use "Save Link As...")
Starting BioTapestry ModelPathTutorialInitialModel.btp
Completed BioTapestry ModelPathTutorialModel-Finished.btp

Other Documentation

The BioTapestry User's Guide Revision A (August 16, 2005) (PDF format) provides the information that was formerly included in the BioTapestry Editor's Help System. Starting in Version 4.0, the bundled Help System was dropped due to ongoing compatibility problems with recently released Java versions. Also, the material was not being kept up-to-date, with all revision work dedicated to the online documentation. A better bet for finding out about the details of BioTapestry is to check the BioTapestry Frequently Asked Questions or the online tutorials.

Documentation Description File
User's Guide (Revision A: August 16, 2005)UserGuide.pdf
Comma-Separated Value (CSV) Input File Format DescriptionCSVGuide.txt

Obsolete Documentation

The original Version 1 documentation is still available on this page for obsolete documentation.


What's New

Version 7.0.0 was released on 9/22/14, and is the result of a major redesign of the software internals. Although the user of the Java Editor should not notice any of those major internal changes, several new features have also been introduced. The Version 7 Release Notes provide complete details.

Since the beginning of the BioTapestry project, a major goal has been to provide an online interactive model viewer that can be used to explore complex gene regulatory network (GRN) models. Current web-browser technologies such as HTML5 Canvas now make it possible to provide an interactive graphical network model directly in a web browser without needing Java, so we have created a version of the BioTapestry Viewer using these technologies. For example, here is the Viewer running in Safari on Mac OSX:

BioTapestry Web Viewer: Safari On Mac

While the major focus in Version 7 has been to support the new Viewer, there are several compelling new features in the Editor as well. For example, some of the layout techniques that have been explored in the BioFabric project have inspired new additions to BioTapestry as well, such as the new Order Targets by In-degree and Source option:

BioTapestry: Order Targets by In-degree and Source

The automatic layout algorithms have also been made more efficient so that BioFabric can be used to visualize much larger networks.

More in-depth discussion of these new features can be found in the Version 7 Release Notes.

Older release notes are also available for Version 6, Version 5, Version 4, Version 3, Version 2 and for even older versions.


Publications

Please cite BioTapestry using [Longabaugh et.al. 2005] or [Longabaugh et.al. 2009] if you use BioTapestry in your research.

DB Cover Art



Problems Running It?

If you run into any issues with getting BioTapestry to run on your computer that you cannot resolve, or have a program crash, please send a report to biotapestry at systemsbiology dot org or post a message on the BioTapestry-users Google group so we can address your problem. Browsing the Google group is a good way of finding out about any recently identified compatibilty issues and what workarounds have been developed to addess them.

If problems arise due to the version of Java installed on your computer, see the section below to learn about obtaining a supported version of Java.

If you have previous BioTapestry files that are not loading into the current version correctly, or run into any other show-stopping bugs with the new version, the previous versions (6.0.0, 5.0.3) can still be dowloaded from the Archived Executables page.


Supported Platforms

The BioTapestry downloadable executables and Web Start version require a minimum of Java Version 1.5. If you encounter problems with a particular version of Java, please let us know about it; switching to a different version should solve any version-related problems. To run BioTapestry, you will first need to install the Java Runtime Environment (JRE). The JRE can be downloaded from here (click the "Free Java Download" button) or here if you want to select from a wide variety of versions. On MacOS X, Java was already factory-installed on new all Macs prior to Version 10.7 (Lion). With newer Macs, you will need to go to the above download pages as well.

BioTapestry is known to work on Windows, Linux, and MacOS X. If you are having problems getting it to launch, you can try installing a more recent version of Java.


BioTapestry for Gaggle

A brief introduction to using BioTapestry with Gaggle is provided here; you should read it first.

After first launching the Gaggle Boss, click HERE to run the Gaggle-enabled BioTapestry Editor (version 7.0.0, released 9/22/14, requires Java 1.5 or above) using Java Web Start. Using this link will have the same security problems described in the How to Run BioTapestry section above, particularly since the provided Gaggle libraries are self-signed.

The Gaggle is a framework, developed at the Institute for Systems Biology, "...for exchanging data between independently developed software tools and databases to enable interactive exploration of systems biology data." The BioTapestry Editor supports Gaggle, and the above link will launch the program with the Gaggle feature enabled (species is set to "unknown"). IMPORTANT: As noted above, you MUST start the Gaggle Boss before launching the BioTapestry Editor; the Boss auto-start feature is not currently supported. Launch the Boss and other Gaggle-aware applications using the links on the Gaggle Blank Slate page.


Developer's Notes

BioTapestry supports user-written plugins for creating a customized experimental data display. There are example plugins in the source code tree (see below) that can serve as a starting point. If you need any guidance on building plugins, feel free to contact us.

BioTapestry can be called in batch mode from within another Java program to generate images from a comma-separated-value specification coming from a provided InputStream. A small example is provided in the source code tree (see below) in the org.systemsbiology.biotapestry.app.ImageGeneratorAppTestWrapper class.

The BioTapestry Viewer can be embedded as a visualization component inside another Java program. An example of how to do this is shown in the class org.systemsbiology.biotapestry.embedded.EmbeddedViewerPanelTestWrapper in the source code.


Source Code

A tar file of the current version of the source code is available here. Starting with Version 7, BioTapestry source code is also being hosted on GitHub. There are separate repositories; one for the Java codebase and another for the new browser-based Viewer Web Application code.


BioTapestry Viewer

BioTapestry has always supported the ability to share interactive, read-only GRN models over the web. Prior to Version 7, the BioTapestry Viewer used Java Web Start to run on the user's computer. As described in What's New, Version 7 introduces a new way of hosting a Viewer embedded in the web browser that does not require the user to have Java installed on their computer. This change requires that the web server hosting the Viewer supports Java Servlets (e.g. Apache Tomcat Version 6). We provide a page with detailed instructions on how to get a Viewer installation up and running. You can also contact us using the resources listed in the Feedback section if you are having problems.

If you need the previous Web Start version of the Viewer, a copy is available from the Archived Executables page.

If your deployment is on a publically available web site, please let us know about it. We'd like to link to your viewer page off the BioTapestry home page. Even if you prefer not to be linked to, we appreciate being able to keep track of viewer deployments. Thanks!


Send Feedback

We are eager to receive any feedback you wish to send us, such as questions, bug reports, feature requests, and usability issues. The best place to do this is in the
BioTapestry-users Google group. However, you can also email us privately at:
biotapestry at systemsbiology dot org

BioTapestry-users Google Group

This group is intended to give BioTapestry users a place to discuss the program, get help with questions, ask for program enhancements, provide feedback, and share tips with each other on using the software. The group home page is:
http://groups.google.com/group/biotapestry-users

Credits

BioTapestry is a joint project of the Institute for Systems Biology and the Davidson Lab at Caltech. Primary contributors are:
  • William Longabaugh
  • Eric Davidson
  • Hamid Bolouri
Starting in Autumn 2012, the BioTapestry development team at ISB also includes:
  • Suzanne Paquette
  • Kalle Leinonen
Also:
  • Stephen Ramsey, formerly at the Institute for Systems Biology, helped to write the SBML output and simulation support
  • Dan Tenenbaum, formerly at the Institute for Systems Biology, helped to write the Gaggle 2007-4 support

Windows executable created using the Launch4j Executable Wrapper by Grzegorz Kowal (http://sourceforge.net/projects/launch4j/).

BioTapestry development was previously supported by the National Institute of General Medical Sciences under Award Number R01GM061005. It is currently supported by the Eunice Kennedy Shriver National Institute Of Child Health & Human Development of the National Institutes of Health under Award Number R01HD073113. The content of this web site is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.


License and Disclaimer

This software is licensed under the GNU Lesser General Public License (LGPL), which is a standard "free software" and "open source" license. A copy of the license agreement is available online here.

The downloadable Windows executable is wrapped in code that is made available by Grzegorz Kowal under this MIT License.

BioTapestry is under continual development, and despite our best efforts there are bugs in the software. Please be advised that, as stated in the license agreement, the Institute for Systems Biology and the authors disclaim any liability stemming from the use of this software.


Last updated: September 22, 2014

biotapestry at systemsbiology dot org