Welcome to AltamISA’s documentation!

AltamISA is a Python 3 library for representing the ISA-tools data model and reading and writing ISA-Tab file format. The documentation is split into three parts (accessible through the navigation on the left):

Installation & Getting Started

Instructions for the installation of the module and some examples to get you started.

API Documentation

This section contains the API documentation for the module

Project Info

More information on the project, including the changelog, list of contributing authors, and contribution instructions.

Quick Example

Start parsing an ISA-Tab dataset by reading and validating an investigation file (download it to your working directory first):

from altamisa.isatab import *

with open("i_investigation.txt", "rt") as investigation_file:
    investigation = InvestigationReader.from_stream(investigation_file).read()

InvestigationValidator(investigation).validate()

For more inspiration on how to use AltamISA, see Examples.

Features

The main features are

  • immutable data structures (named tuples) for representing records,

  • simple implementation as directed acyclic graph (DAG) between ISA material and process nodes,

  • strictly validating parser with various sanity checks,

  • well-tested code, and well-documented API,

  • example applications, e.g., conversion of ISA-tab to Graphviz dot.

Special Extensions

In addition to the original ISA-Tab format specifications, AltamISA supports

the following special modifications to improve specific use cases:

  • List of values in Characterics or Parameter Value fields by using semicolon-separators (“;”). Note, for ontology terms the same number of splits is expected in the associated field Term Source REF and Term Accession Number.

  • Material name Library Name for improved library annotation in nucleotide sequencing assays.

Note

Although these modifications have been discussed by the ISA community (list of values; library name), they are not supported by official ISA software, yet.

Frequently Asked Questions

Why another Python library for ISA-tab?

Attempting to use the official Python isa-api package led to quite some frustration on our side. Even the official ISA-tab examples parsed into non-expected graph structures. Further, the official Python API has several features that were irrelevant for us, e.g., conversion from and and to various other formats.

Is validation a big deal?

Yes it is. A lot of ISA-tab files that we found out in the wild while exploring the model and format were not validating. (We’re looking at you, MetaboLights). The aim of the projects that we are using ISA-tab are not just describing experiments so humans can read the experiment descriptions. Rather, we want to have machine readable (and interpretable) data formats. Here, strict syntax and ideally semantic validation is key.

What’s the state?

The ISA standard and ISA-Tab file I/O is fully implemented, tested, and we’re actively using it in other applications. The validation is also working stably yet we are planning several extensions and additional checks.

What’s the aim?

The aim is to have a stable and correct library for parsing, representing, and writing ISA-tab.

What’s on the roadmap?

Mostly fine-tuning, stabilization, and additional validations. At some point we might want to add support for ISA-JSON but that is a secondary aim at the moment. The advantage of ISA-Tab is that you can edit it with spreadsheet application.