ISB Logo BioTapestry Caltech Logo

William Longabaugh and Hamid Bolouri, Institute for Systems Biology

Davidson Lab, California Institute of Technology


Contents
A New Way to Run BioTapestry
Running BioTapestry
BioTapestry in Action
Description
New! Download
Documentation
Alternative Launch Options
What's New
Publications
Roadmap
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 06, 2012: BioTapestry is now available as a downloadable executable.
See A New Way to Run BioTapestry.
September 25, 2012: Specific installation instructions for Mac Mountain Lion users.
See Download.
December 17, 2012: New Version 6.0.0 has been released. See What's New.

A New Way to Run BioTapestry

We are now providing BioTapestry as a locally installable executable, available from the Download section below.

The BioTapestry Editor has traditionally been available as a Java application that is launched from your web browser using Java Web Start; this method is still available by clicking on the link below. However, some web browsers are beginning to disable default Java support due to security issues, particularly for older operating system versions. In those cases, it is not advisable to enable Java in your browser just to be able to run BioTapestry. Therefore, we are now providing standard downloadable executables, so that these ongoing browser support problems will no longer be an issue for using BioTapestry. Go to the Download section, get the appropriate file for your operating system, and install a local copy of the BioTapestry Editor program directly on your computer. If you go this route, please try to keep your version of BioTapestry up-to-date, as the automatic download of new versions provided by Java Web Start will not apply.

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 6.0.0, released 12/17/12, 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.

NOTE: Your computer needs at least Java Version 1.5 installed to run using the above link. However, it is still possible to run a version that works with Java 1.4 if you use a launch link in the Alternative Launch Options section below; see the discussion there. NOTE: It is planned that Version 6 will be the last version of BioTapestry that can be run with Java 1.4.

If you need to use an older version of BioTapestry prior to Version 6, 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 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.

  • Windows: You need to download this BioTapestryEditor600.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. The BioTapestry Editor application is contained in this BioTapestryEditorInstallImage600.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 BioTapestryEditorInstallImage600). 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.

  • Important Information for Mac Users with OS X newer than v10.7.5!

    Trying to run the BioTapestry Editor will cause a message to appear telling you that it is damaged. This is due to new restrictions imposed by the Gatekeeper system; BioTapestry is not signed with an Apple Developer Certificate. Based on recent user reports, you may 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:

    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, use the information provided in "Gatekeeper options" as follows:

    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:", select the previous secure setting (e.g. "Mac App Store and identified developers").


  • Linux: Download the compressed tar file BioTapestryEditorForLinux600.tgz and place it where you want to install the program. Untar the file: tar xvzf BioTapestryEditorForLinux600.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, and (as of March 18, 2009) uses the Version 3 features that simplify network construction. 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.


Alternative Launch Options

For Java 1.4 Users

Click HERE to run the BioTapestry Editor (version 6.0.0, released 12/17/12, operates on Java 1.4 or above) using Java Web Start.

For those users who must use Java 1.4, the Java 1.4 link provided here will allow you to run exactly the same current version of BioTapestry, but you will be warned that the code has been signed by an expired security certificate. Note that Version 6 is the last version of BioTapestry that will support Java 1.4.

Previous Version

We no longer provide a Java Web Start link for the previous version of BioTapestry. If you need to run an older version, please download and install an archived executable from the Archived Executables page. Remember, BioTapestry .btp files created and saved using the current version are typically not readable by a previous version. If you are running into problems with the latest version that forces you to use an older version, please report the problem so we can fix it. Thanks!

Gaggle-Enabled Version

A Gaggle-enabled instance of BioTapestry can be launched from this page. See the BioTapestry for Gaggle section below for the link and more information.


What's New

Version 6.0.0 was released on 12/17/12. It introduces a number of new features, mostly related to automatic layout and link drawing and layout helper tools. The Version 6 Release Notes provide complete details.

Of particular note is the new overlay-driven layout feature. The user can create a high-level organization of the network using a network overlay containing a set of network modules and module links. After adding nodes to the modules, the system will automatically create a layout conforming to the specified organization. Consider the following small example, where nodes have been added to a set of modules defined in a network overlay:

Highlighted New Version 6.0 Feature: Before

Using the overlay-driven layout feature, the network can be laid out automatically in a way that follows this organization:

Highlighted New Version 6.0 Feature: After

Other new features include:

  • Link geometry repair and diagonal link cleanup tools.
  • New stacked layout strategy.
  • Ability to layout only selected items.
  • Ability to layout single regions.
  • New comma-separated value (CSV) file export features, one for perturbation data and the other for build instructions.
  • Passthrough search, which can find terminal gene sources and targets by passing through intermediate non-gene nodes.
  • Enhanced navigation and zoom for selected network objects, allowing the user to zoom in to each selection, one-by-one.
  • The ability to embed, and interact with, the BioTapestry Viewer as a visualization component in a larger Java program.
  • Geometry repair and diagonal cleanup tools for network module links (i.e. part of network overlays).
  • Improved mouse-click behavior.
  • Bug fixes
More in-depth discussion of these new features can be found in the Version 6 Release Notes.

Older release notes are also available for 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



Roadmap

With the current version of BioTapestry, the user can: 1) draw networks by hand, or 2) specify a list of interactions either in interactive tables or comma-separated value (CSV) input files and then have the network laid out automatically. Also, when provided with separate tables of experimental data, BioTapestry can automatically show changes in the network state over time.

Work is ongoing to create a version that will analyze experimental spatial/temporal expression data and raw perturbation data, guide the user through the process of deciding what network connections should be included in the network diagram, and then automatically creating the full dynamic network hierarchy.

Other planned enhancements include:

If you have suggestions for other enhancements that would make BioTapestry more useful to you, please let us know.


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.

Starting with version 5.0.3, the recommended way to run BioTapestry is by downloading and installing it on your computer. If you encounter problems with the Java Web Start method, consider a local install. If you are having problems with Web Start, it is a good idea to remove any locally cached previous versions of the software that are on your computer. You can do this by running the Java Web Start Applications Manager/Cache Viewer, and deleting the existing local copy of BioTapestry. Finding and running the Manager depends on your operating system and Java version. This section of the FAQ details how to find and run the Manager program:

Do I have to be online to run BioTapestry?

and this section talks about deleting the current cache copy:

I'm not getting the most recent version. What do I do?

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 version (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. There is a legacy version that still works with version 1.4.2 provided above in the Alternative Links section, but this is not recommended and will be discontinued after BioTapestry Version 6. 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 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 6.0.0, released 12/17/12, requires Java 1.5 or above) using Java Web Start.

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.

Starting with Version 4.0, 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.

Starting with Version 6.0, 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.

BioTapestry Viewer

The BioTapestry Viewer can be installed on your web server to provide a read-only interactive interface for sharing your network on the web. A ZIP archive distribution that contains both the stripped-down .jar file for the current version (6.0.0) of the Viewer, as well as all supporting files, and a step-by-step HOWTO of what is involved in deploying the Viewer, is available here. (NOTE: right-click & use "Save Link As..."). If the HOWTO doesn't answer all your questions, please post a message in the BioTapestry-users Google group, or contact us directly.

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: October 30, 2013

biotapestry at systemsbiology dot org