OmgExperiment Class Reference
[Library]

#include <omgexperiment.h>

Inheritance diagram for OmgExperiment:

[legend]Collaboration diagram for OmgExperiment:

[legend]List of all members.

---

Detailed Description

An experiment represents a collection of models that need to be processed. Rather than setting up models and running them individually, you can add them to the experiment, which (where possible) will parelelise the process, keep track of overall experiment progress and perform other house keeping jobs for you.

Note:

This class inherits QThread.

Author:

Tim Sutton, 2005

Definition at line 45 of file omgexperiment.h.

Public Slots
void	abort ()
Signals
void	experimentMaximum (int)
void	experimentProgress (int)
void	modelCreationProgress (int)
void	modelProjectionProgress (int)
void	logMessage (QString)
void	experimentStopped ()
void	modelCompleted (QString)
Public Member Functions
	OmgExperiment ()
	~OmgExperiment ()
QString	name ()
void	setName (QString theName)
QString	description ()
void	setDescription (QString theDescription)
QString	workDir ()
void	setWorkDir (QString theWorkDir)
QString	currentStatus ()
void	reset ()
bool	isRunning ()
void	addModel (OmgModel *thepModel)
OmgModel *	getModel (int theModelNo)
OmgModel *	getModel (QString theGuid)
void	run ()
void	stop ()
int	count ()
void	clear ()
void	removeModel (QString theGuid)
void	removeAlgorithm (QString theName)
void	removeTaxon (QString theName)
void	removeCompleted ()
OmgModellerPluginInterface *	modellerPlugin ()
void	setModellerPlugin (OmgModellerPluginInterface *theAdapter)
const QString	toString ()
bool	isAborted ()
QString	toSummaryHtml (bool theForceFlag=false)
QString	toPrintHtml (bool theForceFlag=false)
QString	toAlgorithmSummaryHtml (QString theAlgorithmName, bool theForceFlag=false)
QString	toTaxonSummaryHtml (QString theTaxonName, bool theForceFlag=false)
void	makeAlgorithmSummaryGraphs (QString theWorkDir)
void	save ()
QString	toXml () const
bool	fromXml (const QString theXml)
Private Member Functions
QString	getStatsHtml ()
QString	getGraphsHtml (QString theImagePrefix="", bool theForceFlag=false)
void	addValueToSummaryGraph (QMap< QString, QList< double > > &theMap, QString theAlgorithmName, double theValue)
void	summaryMapToGraph (QMap< QString, QList< double > > &theMap, QString theWorkDir, QString theImageSuffix)
Private Attributes
QMutex	mMutex
QWaitCondition	mCondition
QString	mName
QString	mDescription
QVector< OmgModel * >	mModelVector
int	mLastPos
OmgModellerPluginInterface *	mpModellerPlugin
bool	mAbortFlag
QString	mWorkDir
QString	mCurrentStatus
bool	mRunningFlag

---

Constructor & Destructor Documentation

OmgExperiment::OmgExperiment (   )

Definition at line 40 of file omgexperiment.cpp. References OmgGuid::guid(), OmgGuid::setGuid(), and setName().

Here is the call graph for this function:

OmgExperiment::~OmgExperiment (   )

Definition at line 50 of file omgexperiment.cpp. References mModelVector.

---

Member Function Documentation

void OmgExperiment::abort (   )  [slot]

Set the abort flag for this experiment. The experiment will end as soon as the current model is done or sooner if the adapter allows that. Definition at line 420 of file omgexperiment.cpp. References mAbortFlag, and mCurrentStatus. Referenced by OmgExperimentTest::isAborted().

void OmgExperiment::addModel (  OmgModel *  thepModel  )

Add a new model to the experiment queue Definition at line 109 of file omgexperiment.cpp. References logMessage(), mModelVector, and mWorkDir. Referenced by fromXml(), and OmgExperimentDesigner::getExperiment().

void OmgExperiment::addValueToSummaryGraph (  QMap< QString, QList< double > > &  theMap, QString  theAlgorithmName, double  theValue )  [private]

A helper function to add a new record to the map holding data for a summary graph. Typically used by makeAlgorithmSummaryGraphs. If no key exists in theMap for theAlgorithmName, one will be added and a new associated vector will be created. See also: makeAlgorithmSummaryGraphs Parameters: &theMap  - a map (passed by reference) containing algorithm names for its keys and QLists for its values. The list in turn contains double where the value in the list art the y axis value that is to be to be graphed. This functions purpose is to append a new entry to this list. QMap<QString,QList <double> > theAlgorithmName  - a string used to identify which vector the value should be added to. theValue  - the value to be added to the vector associated with theAlgoritithmName. Definition at line 973 of file omgexperiment.cpp. Referenced by makeAlgorithmSummaryGraphs().

void OmgExperiment::clear (   )

Clear the model queue for the experiment Definition at line 385 of file omgexperiment.cpp. References mModelVector.

int OmgExperiment::count (   )

Then number of models to be run in the experiment Definition at line 380 of file omgexperiment.cpp. References mModelVector. Referenced by OmgExperimentPrinter::run(), and run().

QString OmgExperiment::currentStatus (   )  [inline]

Get the current status of the experiment. Example responses are: "Creating model definition for Acacia mearnsii" "Projecting model for Acacia mearnsii" "Experiment cancelling..." etc. Returns: a String with the experiment status. Definition at line 78 of file omgexperiment.h.

QString OmgExperiment::description (   )

get the description of this experiment Definition at line 75 of file omgexperiment.cpp. References mDescription.

void OmgExperiment::experimentMaximum (  int   )  [signal]

Notify all observers of the experiment size Referenced by run().

void OmgExperiment::experimentProgress (  int   )  [signal]

Notify all observers how far the total experiment has progressed Referenced by run().

void OmgExperiment::experimentStopped (   )  [signal]

Notify all observers that the experiment has stopped Referenced by run().

bool OmgExperiment::fromXml (  const QString  theXml  )  [virtual]

Implments the serialisable interface method to reinstate a model. It will try to populate all members of this class and fail gracefully when they are not available (typically by leaving the member tagged as [Not Set] Implements OmgSerialisable. Definition at line 881 of file omgexperiment.cpp. References addModel(), OmgModel::fromXml(), mDescription, mName, OmgGuid::setGuid(), and Omgui::xmlDecode(). Referenced by OmgExperimentTest::run(), and OmgExerimentPrinterTest::run().

Here is the call graph for this function:

QString OmgExperiment::getGraphsHtml (  QString  theImagePrefix = "", bool  theForceFlag = false )  [private]

A helper function used by the reporting functions to get graphs html for the experiment Definition at line 714 of file omgexperiment.cpp. References makeAlgorithmSummaryGraphs(), and mWorkDir. Referenced by toPrintHtml(), and toSummaryHtml().

Here is the call graph for this function:

OmgModel * OmgExperiment::getModel (  QString  theGuid  )

Overloaded convenience function to Get a model from experiment given its guid. Applies a mutex lock while searching for the model. Be careful about modifying models while the experiment is running. Doing so can put the model into an undefined state. Parameters: the  guid of the model to find Returns: An * OmgModel or NULL if no match found. Definition at line 131 of file omgexperiment.cpp. References OmgGuid::guid(), and mModelVector.

Here is the call graph for this function:

OmgModel * OmgExperiment::getModel (  int  theModelNo  )

Get a model from experiment given its number. Be careful about modifying models while the experiment is running. Doing so can put the model into an undefined state. Returns: theModel if it exists or NULL Definition at line 122 of file omgexperiment.cpp. References mModelVector. Referenced by OmgExperimentPrinter::run().

QString OmgExperiment::getStatsHtml (   )  [private]

A helper function used by the reporting functions to get stats for the experiment. Definition at line 514 of file omgexperiment.cpp. References OmgModel::accuracy(), OmgModel::algorithm(), OmgModel::commission(), OmgModel::endDateTimeStamp(), OmgModel::hasError(), OmgModel::isCompleted(), mDescription, mModelVector, mName, OmgModel::omission(), OmgModel::percentCellsPresent(), OmgModel::rocScore(), Omgui::secondsToString(), OmgModel::startDateTimeStamp(), and Omgui::xmlEncode(). Referenced by toPrintHtml(), and toSummaryHtml().

Here is the call graph for this function:

bool OmgExperiment::isAborted (   )

Find out if the experiment abort flag has been set. Definition at line 415 of file omgexperiment.cpp. References mAbortFlag. Referenced by OmgExperimentTest::isAborted().

bool OmgExperiment::isRunning (   )

A flag indicating if the experiment is running or stopped / completed. Returns: boolean - false if the experiment is stopped / completed or true if it is currently running. Definition at line 410 of file omgexperiment.cpp. References mRunningFlag.

void OmgExperiment::logMessage (  QString   )  [signal]

Notify listeners of a new log message Referenced by addModel(), run(), and toSummaryHtml().

void OmgExperiment::makeAlgorithmSummaryGraphs (  QString  theWorkDir  )

A helper function to make algorithm summary graphs Parameters: theWorkDir  - the workingdir for the output graphs Definition at line 933 of file omgexperiment.cpp. References OmgModel::accuracy(), addValueToSummaryGraph(), OmgModel::algorithm(), OmgModel::commission(), OmgModel::endDateTimeStamp(), mModelVector, OmgModel::omission(), OmgModel::percentCellsPresent(), OmgModel::rocScore(), OmgModel::startDateTimeStamp(), and summaryMapToGraph(). Referenced by getGraphsHtml(), OmgExperimentTest::loadAndGraph(), and OmgExperimentTest::run().

Here is the call graph for this function:

void OmgExperiment::modelCompleted (  QString   )  [signal]

Notify all listeners that a model completed (including all post processing) Parameters: QString  - guid of completed model. Referenced by run().

void OmgExperiment::modelCreationProgress (  int   )  [signal]

Notify all listeners how far the creation of the current model has progressed

OmgModellerPluginInterface * OmgExperiment::modellerPlugin (   )

Get the active modeller plugin Definition at line 426 of file omgexperiment.cpp. References mpModellerPlugin.

void OmgExperiment::modelProjectionProgress (  int   )  [signal]

Notify all listeners how far the projection of the current model has progressed

QString OmgExperiment::name (   )

get the name of this experiment Definition at line 64 of file omgexperiment.cpp. References mName. Referenced by OmgExperimentTest::loadAndGraph(), OmgExperimentTest::run(), OmgExerimentPrinterTest::run(), run(), OmgExperimentTest::saveAndLoadExperiment(), toAlgorithmSummaryHtml(), toSummaryHtml(), and toTaxonSummaryHtml().

void OmgExperiment::removeAlgorithm (  QString  theName  )

Remove all models that match the algorithm Name Definition at line 160 of file omgexperiment.cpp. References OmgModel::algorithm(), and mModelVector.

Here is the call graph for this function:

void OmgExperiment::removeCompleted (   )

Remove all completed models from the queue Definition at line 390 of file omgexperiment.cpp. References OmgModel::isCompleted(), and mModelVector.

Here is the call graph for this function:

void OmgExperiment::removeModel (  QString  theGuid  )

Remove a model from the experiment given its Guid Definition at line 145 of file omgexperiment.cpp. References OmgGuid::guid(), and mModelVector.

Here is the call graph for this function:

void OmgExperiment::removeTaxon (  QString  theName  )

Remove all models that match the taxon Name Definition at line 174 of file omgexperiment.cpp. References mModelVector, and OmgModel::taxonName().

Here is the call graph for this function:

void OmgExperiment::reset (   )

Reset the experiement - mark all models reset and clear all internal vars. Definition at line 432 of file omgexperiment.cpp. References mModelVector, and OmgModel::reset(). Referenced by OmgExperimentTest::run().

Here is the call graph for this function:

void OmgExperiment::run (   )

Start running the experiment Definition at line 188 of file omgexperiment.cpp. References OmgModel::algorithm(), OmgModel::appendToLog(), count(), OmgModellerPluginInterface::createModel(), experimentMaximum(), experimentProgress(), experimentStopped(), OmgGuid::guid(), OmgModel::hasError(), OmgModel::isCompleted(), logMessage(), mAbortFlag, mCurrentStatus, mLastPos, mModelVector, modelCompleted(), mpModellerPlugin, mRunningFlag, mWorkDir, OmgAlgorithm::name(), name(), OmgModel::parseModelResult(), OmgModel::postProcess(), OmgModellerPluginInterface::projectModel(), save(), OmgModel::setCompleted(), OmgModel::setShapefileName(), OmgModel::setStartDateTimeStamp(), OmgModel::setWorkDir(), OmgModel::taxonName(), OmgModel::toShapefile(), toSummaryHtml(), and OmgModel::workDir(). Referenced by OmgExperimentTest::run().

Here is the call graph for this function:

void OmgExperiment::save (   )

Save the exeriment Definition at line 370 of file omgexperiment.cpp. References Omgui::createTextFile(), OmgGuid::guid(), mWorkDir, and toXml(). Referenced by run().

Here is the call graph for this function:

void OmgExperiment::setDescription (  QString  theDescription  )

set the description of this experiment Definition at line 80 of file omgexperiment.cpp. References mDescription. Referenced by OmgExperimentDesigner::getExperiment().

void OmgExperiment::setModellerPlugin (  OmgModellerPluginInterface *  theAdapter  )

Tell the experiment which modeller adapter instance to use Definition at line 375 of file omgexperiment.cpp. References mpModellerPlugin. Referenced by OmgExperimentDesigner::getExperiment(), and OmgExperimentTest::run().

void OmgExperiment::setName (  QString  theName  )

set the name of this experiment Definition at line 69 of file omgexperiment.cpp. References mName. Referenced by OmgExperimentDesigner::getExperiment(), OmgExperiment(), OmguiTest::regression1728367(), and OmgExperimentTest::saveAndLoadExperiment().

void OmgExperiment::setWorkDir (  QString  theWorkDir  )

Set the workDir of this experiment if the experiment has any models associated with it their work dirs will be updated too. Any new models added to the experiment will have their workdir set to this value. Parameters: theWorkDir  - a QString with full path to the dir Definition at line 90 of file omgexperiment.cpp. References OmgModel::algorithm(), mModelVector, mWorkDir, and OmgModel::setWorkDir(). Referenced by OmgExperimentSelector::on_pbnOK_clicked(), OmgExperimentTest::run(), and OmgExerimentPrinterTest::run().

Here is the call graph for this function:

void OmgExperiment::stop (   )

Stop running anymore models

void OmgExperiment::summaryMapToGraph (  QMap< QString, QList< double > > &  theMap, QString  theWorkDir, QString  theImageSuffix )  [private]

A helper function to generate a graph from a QMap. See also: makeAlgorithmSummaryGraphs Parameters: &theMap  - a map (passed by reference) containing algorithm names for its keys and QLists for its values. The list in turn contains double where the value in the list art the y axis value that is to be to be graphed. This functions purpose is to render the graph as a graphic. QMap<QString,QList <double> > theWorkDir  - a directory where the generated image should be placed after the graph is generated. theImageSuffix  - some text to be appended to each image the first part of the image name will be the Key of the QMap. e.g. somekeyval_<theImageSuffix>.png Definition at line 1004 of file omgexperiment.cpp. References OmgGraph::addSeries(), OmgGraph::clear(), OmgDataSeries::fillColor(), OmgGraph::render(), OmgGraph::setAreaFillEnabled(), OmgDataSeries::setFillColor(), OmgGraph::setGridLinesEnabled(), OmgDataSeries::setLabel(), OmgDataSeries::setLineColor(), OmgGraph::setVertexLabelsEnabled(), and OmgDataSeries::setYValuesList(). Referenced by makeAlgorithmSummaryGraphs().

Here is the call graph for this function:

QString OmgExperiment::toAlgorithmSummaryHtml (  QString  theAlgorithmName, bool  theForceFlag = false )

Create an html formatted sumary of all the models for an Algorithm and return it as a QString suitable for use in a print report using QTextDocument. All paths will be absolute to allow for images etc to display properly.. Parameters: QString  theName of the alg to get the report for bool  flag indicating whether to force recreating the report or whether to just return the existing one if it was made previously. If the file does not exist the flag is ignored and the report is created anyway. By default this flag is false. Returns: QString containing the html markup Definition at line 770 of file omgexperiment.cpp. References OmgModel::algorithm(), mModelVector, name(), and OmgModel::thumbnailFileName().

Here is the call graph for this function:

QString OmgExperiment::toPrintHtml (  bool  theForceFlag = false  )

Create an html formatted sumary of the experiment and return it as a string for use in printing. The paths to image files will be absolute so that the print properly in the QTextDocument.. Parameters: bool  flag indicating whether to force recreating the report or whether to just return the existing one if it was made previously. If the file does not exist the flag is ignored and the report is created anyway. By default this flag is false. Returns: QString containing the full html of the summary report. Definition at line 500 of file omgexperiment.cpp. References getGraphsHtml(), getStatsHtml(), and mWorkDir. Referenced by OmgExperimentPrinter::run().

Here is the call graph for this function:

const QString OmgExperiment::toString (   )

Return a string representation of the whole experiment mainly intended for debugging purposes Definition at line 442 of file omgexperiment.cpp. References mModelVector, and OmgModel::toString().

Here is the call graph for this function:

QString OmgExperiment::toSummaryHtml (  bool  theForceFlag = false  )

Create an html formatted sumary of the experiment and save it to disk. Parameters: bool  flag indicating whether to force recreating the report or whether to just return the existing one if it was made previously. If the file does not exist the flag is ignored and the report is created anyway. By default this flag is false. Returns: QString containing the full file name and path to the summary report. Definition at line 456 of file omgexperiment.cpp. References Omgui::createTextFile(), getGraphsHtml(), Omgui::getHtmlFooter(), Omgui::getHtmlHeader(), getStatsHtml(), logMessage(), mWorkDir, and name(). Referenced by run().

Here is the call graph for this function:

QString OmgExperiment::toTaxonSummaryHtml (  QString  theTaxonName, bool  theForceFlag = false )

Create an html formatted sumary of all the models for an Taxon and return it as a QString suitable for use in a print report using QTextDocument. All paths will be absolute to allow for images etc to display properly.. Parameters: QString  theName of the Taxon to get the report for bool  flag indicating whether to force recreating the report or whether to just return the existing one if it was made previously. If the file does not exist the flag is ignored and the report is created anyway. By default this flag is false. Returns: QString containing the html markup Definition at line 812 of file omgexperiment.cpp. References OmgModel::algorithm(), mModelVector, name(), OmgModel::taxonName(), and OmgModel::thumbnailFileName(). Referenced by OmgExperimentPrinter::run().

Here is the call graph for this function:

QString OmgExperiment::toXml (   )  const [virtual]

This method is required for the serialiseable interface. It will encapsulate *all* model properties so that its complete state can be serialised and later deserialised. See also: toModelCreationXml() Implements OmgSerialisable. Definition at line 861 of file omgexperiment.cpp. References OmgGuid::guid(), mDescription, mModelVector, mName, and OmgModel::toXml(). Referenced by OmguiTest::regression1728367(), OmgExperimentTest::run(), OmgExerimentPrinterTest::run(), save(), and OmgExperimentTest::saveAndLoadExperiment().

Here is the call graph for this function:

QString OmgExperiment::workDir (   )

get the workDir of this experiment Definition at line 85 of file omgexperiment.cpp. References mWorkDir.

---

Member Data Documentation

bool OmgExperiment::mAbortFlag [private]

A flag that gets set when a request has been made to cancel the experiment run. The experiment will abort at the earliest convenient time, depending on the modeller adapter in use. Definition at line 309 of file omgexperiment.h. Referenced by abort(), isAborted(), and run().

QWaitCondition OmgExperiment::mCondition [private]

Definition at line 295 of file omgexperiment.h.

QString OmgExperiment::mCurrentStatus [private]

A string with the current status of the experiment. This property is read only and not serialised. Example responses are: "Creating model definition for Acacia mearnsii" "Projecting model for Acacia mearnsii" "Experiment cancelling..." etc. Definition at line 321 of file omgexperiment.h. Referenced by abort(), and run().

QString OmgExperiment::mDescription [private]

A description for this experiment Definition at line 299 of file omgexperiment.h. Referenced by description(), fromXml(), getStatsHtml(), setDescription(), and toXml().

int OmgExperiment::mLastPos [private]

The position in the queue of the last model that was executed Definition at line 303 of file omgexperiment.h. Referenced by run().

QVector<OmgModel * > OmgExperiment::mModelVector [private]

The container for all the models in the queue Definition at line 301 of file omgexperiment.h. Referenced by addModel(), clear(), count(), getModel(), getStatsHtml(), makeAlgorithmSummaryGraphs(), removeAlgorithm(), removeCompleted(), removeModel(), removeTaxon(), reset(), run(), setWorkDir(), toAlgorithmSummaryHtml(), toString(), toTaxonSummaryHtml(), toXml(), and ~OmgExperiment().

QMutex OmgExperiment::mMutex [private]

Definition at line 294 of file omgexperiment.h.

QString OmgExperiment::mName [private]

A name for this experiment Definition at line 297 of file omgexperiment.h. Referenced by fromXml(), getStatsHtml(), name(), setName(), and toXml().

OmgModellerPluginInterface* OmgExperiment::mpModellerPlugin [private]

The adapter that will be used to run the models Definition at line 305 of file omgexperiment.h. Referenced by modellerPlugin(), run(), and setModellerPlugin().

bool OmgExperiment::mRunningFlag [private]

A flag to indicate if the experiment is currently running Definition at line 323 of file omgexperiment.h. Referenced by isRunning(), and run().

QString OmgExperiment::mWorkDir [private]

The working dir for the experiment. This will be set when the experiment is restored or created and not serialised to disk as part of the experiment. Definition at line 313 of file omgexperiment.h. Referenced by addModel(), getGraphsHtml(), run(), save(), setWorkDir(), toPrintHtml(), toSummaryHtml(), and workDir().

---

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

• lib/omgexperiment.h
• lib/omgexperiment.cpp

---