IData::Dataset Class Reference
[IData]

C++ class representing dataset concept. More...

#include <Dataset.h>

List of all members.

Public Types
typedef std::pair< unsigned, unsigned >	RunRange
typedef std::vector< RunRange >	Runs
typedef std::pair< unsigned, unsigned >	StreamRange
typedef std::vector< StreamRange >	Streams
typedef std::vector< std::string >	NameList
Public Member Functions
	Dataset ()
	Default constructor makes empty dataset.
	Dataset (const std::string &ds)
	Make dataset instance.
	~Dataset ()
bool	exists (const std::string &key) const
	Returns true if the key is defined.
const std::string &	value (const std::string &key) const
	Returns value for given key or empty string.
unsigned	expID () const
	Returns experiment ID or 0 if it has not been defined.
const std::string &	instrument () const
	Returns instrument name or empty string if it has not been defined.
const std::string &	experiment () const
	Returns experiment name or empty string if it has not been defined.
const Runs &	runs () const
	Returns set of run numbers.
const Streams &	streams () const
	Returns set of stream ranges.
std::vector< unsigned >	runsAsList () const
	Returns set of run numbers.
std::vector< unsigned >	streamsAsList () const
	Returns set of stream ranges.
bool	isFile () const
	Returns true if dataset was specified as a single file name.
std::string	dirName () const
	Return the directory name for files.
const NameList &	files () const
	Return the list of file names for this dataset.
Static Public Member Functions
static void	setAppExpName (const std::string &exp)
	Sets application-wide experiment name.
static void	setDefOption (const std::string &key, const std::string &value)
	Sets default application-wide option.
Protected Member Functions
void	parseXtcFileName (std::string path)
void	parseHdfFileName (std::string path)

---

Detailed Description

C++ class representing dataset concept.

Dataset is defined currently as a collection of one or more runs from the same experiment. The minimum information that dataset needs to contain is experiment name/number and run numbers. In addition to that it provides additional options for locating data files or selecting specific format (HDF5 vs XTC) of data.

Some option (like experiment name) can be specified at the application-wide basis by using static methods of this class. Dataset instances can override those global options by providing their own values in a constructor.

Constructor of Dataset class takes either a file name or a string representation of the dataset which is a list of options separated by colon (:) characters:

    option[:option[:option...]]

Each option can be a key-value pair separated by equal sign or just a key without value:

    key1=value1:key2=value2:key3:key4

Here is the set of common key names and meaning of their corresponding values:

• exp - specifies experiment, corresponding value can be either experiment number (exp=197), experiment name (exp=cxi59712), or instrument and experiment names separated by slash (exp=CXI/cxi59712)
• run - specifies set of runs belonging to dataset which is a comma-separated list of run ranges, range can be a single run number or two number separated by dash (run=12,15-18,25)
• xtc - selects XTC files as input no value for this key
• smd - selects small XTC files as input (which is default), no value for this key
• idx - selects index files as input, no value for this key
• h5 - selects HDF5 files as input, no value for this key
• live - selects live XTC files as input, no value for this key
• dir - specifies directory containing input files, by default files are located in the standard experiment directories under /reg/d/psdm directory
• one-stream - this option works with XTC or sml input only, if the option is given a value (number) then it specifies stream number to read, without value arbitrary single stream will be selected. If option is not specified then data from all stream are read.
• stream - specifies set of streams belonging to dataset which is a comma-separated list of stream ranges, range can be a single stream number or two number separated by dash (stream=0,2-4,11)

If the same key appears multiple times in the input string the latter values for this key override earlier values.

If the string passed to a constructor looks like a file name then dataset constructor tries to guess various pieces of information from the file name itself. To look like a file name the string should either:

• do not contain colon character and contain at least one dot
• if colon character is in the string it follows by slash or digit (for something like root://host:port/path)

---

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Version:

Id

Dataset.h 10652 2015-09-09 20:12:56Z davidsch@SLAC.STANFORD.EDU

Author:

Andy Salnikov

Definition at line 117 of file Dataset.h.

---

Member Typedef Documentation

typedef std::vector<std::string> IData::Dataset::NameList

Definition at line 124 of file Dataset.h.

typedef std::pair<unsigned, unsigned> IData::Dataset::RunRange

Definition at line 120 of file Dataset.h.

typedef std::vector<RunRange> IData::Dataset::Runs

Definition at line 121 of file Dataset.h.

typedef std::pair<unsigned, unsigned> IData::Dataset::StreamRange

Definition at line 122 of file Dataset.h.

typedef std::vector<StreamRange> IData::Dataset::Streams

Definition at line 123 of file Dataset.h.

---

Constructor & Destructor Documentation

IData::Dataset::Dataset

(

)

Default constructor makes empty dataset.

Definition at line 164 of file Dataset.cpp.

IData::Dataset::Dataset

(

const std::string &

ds

)

Make dataset instance.

Constructor takes string representation of a dataset as described in class-level documentation. Options specified in the string override default application-wide options.

Parameters:

[in]

ds

String representation of dataset.

Exceptions:

	ExpNameException	thrown if specified name is not found
	RunNumberException	thrown if specified run list has incorrect format.

Definition at line 175 of file Dataset.cpp.

References isFileName(), parseExpName(), parseHdfFileName(), parseRuns(), parseStreams(), and parseXtcFileName().

IData::Dataset::~Dataset

(

)

Definition at line 239 of file Dataset.cpp.

---

Member Function Documentation

std::string IData::Dataset::dirName

(

)

const

Return the directory name for files.

Return the directory name for files, if "dir" option is specified the it is returned, otherwise some default lcoation for experiment files is returned.

Definition at line 333 of file Dataset.cpp.

References experiment(), PSTime::TimeFormat::format(), instrument(), and value().

Referenced by files().

bool IData::Dataset::exists

(

const std::string &

key

)

const

Returns true if the key is defined.

Key may be defined by either constructor or with a default application-wide option.

Parameters:

[in]

key

Key name

Definition at line 252 of file Dataset.cpp.

Referenced by files().

const std::string & IData::Dataset::experiment

(

)

const

Returns experiment name or empty string if it has not been defined.

Definition at line 297 of file Dataset.cpp.

Referenced by dirName(), and files().

unsigned IData::Dataset::expID

(

)

const

Returns experiment ID or 0 if it has not been defined.

Definition at line 281 of file Dataset.cpp.

Referenced by files().

const Dataset::NameList & IData::Dataset::files

(

)

const

Return the list of file names for this dataset.

Definition at line 354 of file Dataset.cpp.

References constructDataFileRegEx(), dirName(), exists(), experiment(), expID(), logger, MsgLog, runs(), runsAsList(), streams(), and streamsAsList().

const std::string & IData::Dataset::instrument

(

)

const

Returns instrument name or empty string if it has not been defined.

Definition at line 289 of file Dataset.cpp.

Referenced by dirName().

bool IData::Dataset::isFile

(

)

const [inline]

Returns true if dataset was specified as a single file name.

Definition at line 211 of file Dataset.h.

void IData::Dataset::parseHdfFileName

(

std::string

path

)

[protected]

Definition at line 466 of file Dataset.cpp.

References logger, MsgLog, parseExpName(), and parseRuns().

Referenced by Dataset().

void IData::Dataset::parseXtcFileName

(

std::string

path

)

[protected]

Definition at line 424 of file Dataset.cpp.

References logger, MsgLog, parseExpName(), and parseRuns().

Referenced by Dataset().

const Dataset::Runs & IData::Dataset::runs

(

)

const

Returns set of run numbers.

Definition at line 305 of file Dataset.cpp.

Referenced by files().

std::vector< unsigned > IData::Dataset::runsAsList

(

)

const

Returns set of run numbers.

Definition at line 319 of file Dataset.cpp.

References listOfPairsAsVector().

Referenced by files().

void IData::Dataset::setAppExpName

(

const std::string &

exp

)

[static]

Sets application-wide experiment name.

Experiment name can be specified with the syntax acceptable for exp key. Individual datasets can override application-wide value.

Parameters:

[in]

exp

new application-wide experiment name

Exceptions:

ExpNameException

thrown if specified name is not found

Definition at line 131 of file Dataset.cpp.

References parseExpName().

void IData::Dataset::setDefOption	(	const std::string &	key,
		const std::string &	value
	)			[static]

Sets default application-wide option.

Sets default application-wide value for an option. Individual datasets can override application-wide values. The key "run" is ignored by this method, warning message is printed. With key "exp" this is equivalent to calling setAppExpName(value).

Parameters:

[in]	key	Key name
[in]	value	New application-wide value for this key

Exceptions:

ExpNameException

thrown if key is "exp" and specified experiment name is not found

Definition at line 149 of file Dataset.cpp.

References logger, MsgLog, and parseExpName().

const Dataset::Streams & IData::Dataset::streams

(

)

const

Returns set of stream ranges.

Definition at line 312 of file Dataset.cpp.

Referenced by files().

std::vector< unsigned > IData::Dataset::streamsAsList

(

)

const

Returns set of stream ranges.

Definition at line 326 of file Dataset.cpp.

References listOfPairsAsVector().

Referenced by files().

const std::string & IData::Dataset::value

(

const std::string &

key

)

const

Returns value for given key or empty string.

Parameters:

[in]

key

Key name

Definition at line 264 of file Dataset.cpp.

Referenced by dirName().

---

The documentation for this class was generated from the following files:

• IData/include/Dataset.h
• IData/src/Dataset.cpp

---