ExperimentalDesignFile Class Reference

Load an experimental design from a TSV file. More...

#include <OpenMS/FORMAT/ExperimentalDesignFile.h>

Static Public Member Functions
static ExperimentalDesign	load (const std::string &tsv_file, bool require_spectra_files)
	Loads an experimental design from a tabular separated file.
static ExperimentalDesign	load (const TextFile &text_file, const bool require_spectra_file, std::string filename)
	Loads an experimental design from an already loaded or generated, tabular file.

Static Private Member Functions
static bool	isOneTableFile_ (const TextFile &text_file)
static ExperimentalDesign	parseOneTableFile_ (const TextFile &text_file, const std::string &tsv_file, bool require_spectra_file)
static ExperimentalDesign	parseTwoTableFile_ (const TextFile &text_file, const std::string &tsv_file, bool require_spectra_file)
static void	parseHeader_ (const StringList &header, const std::string &filename, std::map< std::string, Size > &column_map, const std::set< std::string > &required, const std::set< std::string > &optional, bool allow_other_header)
static void	parseErrorIf_ (const bool test, const std::string &filename, const std::string &message)
	Throws Exception::ParseError with filename and message if test is true.

Detailed Description

Load an experimental design from a TSV file.

The format – both the one-table and the two-table variant – its columns, the rules a design has to satisfy, and worked examples are documented on OpenMS::ExperimentalDesign. In short:

• TAB-separated; while parsing, lines and cells are whitespace trimmed and lines starting with a hash character (a comment) are ignored. A data row must have exactly as many cells as its header; since trimming removes a trailing empty cell, no row may end in an empty cell.
• The variant is auto-detected, by a check cruder than the parsers: it scans every line, not just headers, and reads the file as two-table as soon as one line has exactly one cell equal to Sample and no cell equal to Fraction_Group. It neither trims cells nor skips comment lines. Otherwise the file is read as one-table. In a two-table file at least one blank line separates the sample section from the MS file section above it.
• Mandatory columns of the MS file section are Fraction_Group, Fraction and Spectra_Filepath; Label (default 1) and Sample are optional. In the one-table format any further column is read as sample metadata, whereas the file section of a two-table design rejects unknown columns.
• A relative Spectra_Filepath is resolved against the directory of the design file first, then against the current working directory.

Member Function Documentation

isOneTableFile_()

static bool isOneTableFile_ ( const TextFile &  text_file )

staticprivate

load() [1/2]

static ExperimentalDesign load ( const std::string &  tsv_file, bool  require_spectra_files  )

static

Loads an experimental design from a tabular separated file.

Parameters

[in]	tsv_file	Path of the design file
[in]	require_spectra_files	If true, every Spectra_Filepath must resolve to an existing file; otherwise unresolvable paths are kept as written

Exceptions

Exception::ParseError	on a missing mandatory column, an unknown column in the file section of a two-table design, a row of the MS file section or of the sample section with the wrong number of cells (the message names the line and the expected and actual number of cells), or – with require_spectra_files – a spectra file that does not exist
Exception::ConversionError	if Fraction_Group, Fraction or Label is not an integer
Exception::InvalidValue	if the fraction groups are not consecutive starting at 1
Exception::MissingInformation	if a (fraction group, fraction, label) triple or a (path, label) pair repeats, or a design with a single distinct label maps one (fraction group, label) to several samples
std::out_of_range	if the file section of a two-table design names a Sample that the sample section does not define – including the implicit "Fraction group N" names used when the file section has no Sample column

load() [2/2]

static ExperimentalDesign load ( const TextFile &  text_file, const bool  require_spectra_file, std::string  filename  )

static

Loads an experimental design from an already loaded or generated, tabular file.

filename names the source in error messages AND is the base directory against which relative Spectra_Filepath entries are resolved, so pass the real design-file path whenever the spectra are relative to it; a placeholder that is not a real path makes them resolve against the current working directory.

See also

load(const std::string&, bool) for the exceptions thrown

parseErrorIf_()

static void parseErrorIf_ ( const bool  test, const std::string &  filename, const std::string &  message  )

staticprivate

Throws Exception::ParseError with filename and message if test is true.

parseHeader_()

static void parseHeader_ ( const StringList &  header, const std::string &  filename, std::map< std::string, Size > &  column_map, const std::set< std::string > &  required, const std::set< std::string > &  optional, bool  allow_other_header  )

staticprivate

Reads header line of File and Sample section, checks for the existence of required headers and maps the column name to its position

parseOneTableFile_()

static ExperimentalDesign parseOneTableFile_ ( const TextFile &  text_file, const std::string &  tsv_file, bool  require_spectra_file  )

staticprivate

parseTwoTableFile_()

static ExperimentalDesign parseTwoTableFile_ ( const TextFile &  text_file, const std::string &  tsv_file, bool  require_spectra_file  )

staticprivate