Introducing vcd2svg: how we made the vertebral-bifurcation heat-map figure

April 7, 2014

I think it’s fair to say that this “bifurcation heat-map”, from Wedel and Taylor (2013a: figure 9), has been one of the best-received illustrations that we’ve prepared:

Wedel and Taylor 2013 bifurcation Figure 9 - bifurcatogram

(See comments from Jaime and from Mark Robinson.)

Back when the paper came out, Matt rashly said “Stand by for a post by Mike explaining how it came it be” — a post which has not materialised. Until now!

This illustration was (apart from some minor tweaking) produced by a program that I wrote for that purpose, snappily named “vcd2svg“. That name is because it converts a vertebral column description (VCD) into a scalable vector graphics (SVG) file, which you can look at with a web-browser or load into an image editor for further processing.

The vertebral column description is in a format designed for this purpose, and I think it’s fairly intuitive. Here, for example, is the fragment describing the first three lines of the figure above:

Taxon: Apatosaurus louisae
Specimen: CM 3018
Data: —–YVVVVVVVVV|VVVuuunnn-

Taxon: Apatosaurus parvus
Specimen: UWGM 155556/CM 563
Data: –nnn-VVV—V-V|VVVu——

Taxon: Apatosaurus ajax
Specimen: NMST-PV 20375

Basically, you draw little ASCII pictures of the vertebral column. Other directives in the file explain how to draw the various glyphs represented by (in this case) “Y”, “V”, “u”, and “n”.

It’s pretty flexible. We used the same program to generate the right-hand side (though not the phylogenetic tree) of Wedel and Taylor (2013b: figure 2):

Wedel and Taylor (2013b: Figure 2).

Wedel and Taylor (2013b: Figure 2).

The reason I mention this is because I released the software today under the GNU General Public Licence v3.0, which is kind of like CC By-SA. It’s free for anyone to download, use, modify and redistribute either verbatim or in modified form, subject only to attribution and the requirement that the same licence be used for modified versions.

vcd2svg is written in Perl, and implemented in part by the SVG::VCD module, which is included in the package. It’s available as a CPAN module and on GitHub. There’s documentation of the command-line vcd2svg program, and of the VCD file format. Also included in the distribution are two documented examples: the bifurcation heat-map and the caudal pneumaticity diagram.

Folks, please use it! And feel free to contribute, too: as the change-log notes, there’s work still to be done, and I’ll be happy to take pull requests from those of you who are programmers. And whether you’re a programmer or not, if you find a bug, or want a new feature, feel free to file an issue.

A final thought: in academia, you don’t really get credit for writing software. So to convert the work that went into this release into some kind of coin, I’ll probably have to write a short paper describing it, and let that stand as a proxy for the actual program. Hopefully people will cite that paper when they generate a figure using the software, the way we all reflexively cite Swofford every time we use PAUP*.

Update (12 April 2014)

On Vertebrat’s suggestion, I have renamed the program VertFigure.


13 Responses to “Introducing vcd2svg: how we made the vertebral-bifurcation heat-map figure”

  1. dobermunk Says:

    This is really a fantastic infographic. Congrats!

  2. awesome!
    just this: ” It’s available as a CPAN module and on GitHub. There’s documentation of the command-line vcd2svg program, and of the VCD file format” is geek gibberish for 95% of potential users :( I fear your program will see much less use than it could, unless you do write that paper and explains things really nice and slow for us! :)

  3. Mike Taylor Says:

    Thanks, Heinrich.

    What would be more helpful in place of the “gibberish”?

  4. nothing, Mike! It is just that 99% of people will not understand what a CPAN module is, think GitHub is a place where you hook up with Gits (that some sort of prostitute?) and are already overtaxed with vcd2vg… nah, vdc2… erh…. what?


    Maybe you can at least come up with a sexy name instead?

  5. Mike Taylor Says:

    I hear you, but I think much of the compexity here is irreducible. If you’re going to use the SVG output of this tool, you’re going to need to know what SVG is. If you’re going to prepare vertebral column descriptions, you’re going to need to learn the VCD format (which isn’t hard). Where I could use some help is in figuring out which parts of the complexity are inherent, and which I’ve thoughtlessly introduced from my hacker culture.

  6. Matt Wedel Says:

    One thing to note–the little box for the atlas and the sloped box for the axis, done in the style of Wilson & Sereno 1998, were added by me in GIMP after the fact. So if you like that sort of thing, you’ll either have to add them in yourself (not much work) or tweak the code.

    As for the fig, it’s pretty close to being my favorite of all the ones I’ve been involved with. Most of our response to Woodruff & Fowler 2012 boiled down to, “adult sauropods show the complete spectrum from unsplit to fully bifid in both their cervical and dorsal series, so bifurcation alone tells you _nothing_ about ontogeny if you can’t control for serial position”. And you can get that here in one glance. The rest of the paper was profligate redundancy.

  7. Mike Taylor Says:

    Hey, Matt, see the TODOs in the change-log! Drawing atlas/axis complexes is on the list (though currently only in the form of a seven-word one-liner). I’m kinda hoping someone else will implement it and send me a patch or a pull request.

  8. […] already blogged about this over on Sauropod Vertebra Picture of the Week, but since it’s a software release, I figure I ought to mention it on my programming blog, […]

  9. Vertebrat Says:

    Where I could use some help is in figuring out which parts of the complexity are inherent, and which I’ve thoughtlessly introduced

    The name is a bit opaque. It sounds like a tool for people who have VCD files and want to convert them to SVG. Maybe this means extracting frames from Video CD files as SVG (a rather inappropriate format)? :)

    Your target users don’t have VCD files, don’t want to convert anything, and have little or no preference for SVG. They want to make diagrams of vertebrae (or maybe of similar things like trains). Perhaps a name like “vertebrae” (which is, remarkably, not taken) would have been better.

    BTW, there’s a garbled line in “Two character in the data is special”. (It’s not real software until you get a bug report.)

  10. Mike Taylor Says:

    Thanks, Vertebrat, for your bug-report — the first one! It’s now fixed, and you’re credited in the commit comment :-)

    Fair point on the same of the distribution. “vcd2svg” is a reasonable name for the actual program, but I should have come up with something better for the package as a whole. “Vertebrae” is too general — but I’m ready to hear other suggestions!

  11. Mike Taylor Says:

    I’m in the process of changing the name of the project to VertFigure. Thanks again for the well-deserved nudge.

  12. […] days ago, I released a program for drawing comparative figures of vertebral columns, such as this one from our […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: