/*
Experiment Service API specification

This service provides various methods for extracting data from the Experiment portion of the CDS.

*/

module Experiment
{
	typedef int boolean;

	typedef string compound_id;
	typedef list<compound_id> compounds;
	typedef float molar_ratio;
	typedef mapping<compound_id, molar_ratio> cpd_to_molar;
	typedef mapping<compound_id, cpd_to_molar> compound_relationships;

	/*
	Returns the child compounds of the input compounds and their molar ratio
	equivalents to the parent/input. The MR is -1 if the molar ratio is
	unknown.
	If the input compounds have no children the returned mapping contains
	the input compound and 1 as the molar ratio.
	Intermediate compounds in the tree between child (e.g. a compound that
	has no more children) and input/parent compound are not returned.
	*/
	funcdef getChildCompounds(compounds parents) returns(compound_relationships);

	/*
	Returns the parent compounds of the input compounds and the molar ratio
	of the child compound to the parent compound. Note this is the same value
	as returned by the getChildCompounds function, not the inverse of that
	value. The MR is -1 if the molar ratio is unknown.
	If the input compounds have no parents the returned mapping contains
	the input compound and 1 as the molar ratio.
	Intermediate compounds in the tree between parent (e.g. a compound that
	has no more parents) and input/child compound are not returned.
	*/
	funcdef getParentCompounds(compounds children) returns(compound_relationships);

	/*
	Returns a representation of the compound tree from the parent compounds to
	their ultimate children. All intermediate compounds in the tree are 
	included. This takes the form of a mapping between a parent and its 
	immediate children and a subsequent mapping between those children and the 
	molar ratio from parent:child. To traverse the tree, choose the parent of
	interest, retrieve the child:molar ratio mapping, and continue down the
	tree with each child, retrieving its children from the mapping returned
	by the function. If a compound has no children it is not included in the
	mapping.
	*/
	funcdef getChildAndIntermediateCompounds(compounds parents) returns(compound_relationships);

	/*
	Returns a representation of the compound tree from the child compounds to
	their ultimate parents. All intermediate compounds in the tree are 
	included. This takes the form of a mapping between the child and its 
	immediate parents and a subsequent mapping between those parents and the 
	molar ratio from parent:child. To traverse the tree, choose the child of
	interest, retrieve the parent:molar ratio mapping, and continue up the tree
	with each parent, retrieving its parents from the mapping returned
	by the function. If a compound has no parents it is not included in the 
	mapping.
	*/
	funcdef getParentAndIntermediateCompounds(compounds children) returns(compound_relationships);

	
	typedef string media_id;
	typedef list<media_id> exclude_medias;
	typedef list<compound_id> exclude_compounds;
	typedef boolean exclude_solid;
	typedef boolean exclude_undefined;
	typedef list<media_id> medias;

	/*
	Find medias matching the input requirements. Media IDs in exclude_medias
	will not be returned under any circumstances. Medias containing the
	compounds in exclude_compounds, their parent compounds, and any 
	intermediate compounds will be excluded. The arguments exclude_solid and
	exclude_undefined will prevent solid and undefined medias, respectively,
	from inclusion in the results.
	*/
	funcdef findMedias(exclude_medias, exclude_compounds, exclude_solid, exclude_undefined) returns(medias);

	typedef string genome_id;
	typedef int maxKnockouts;
	typedef boolean onlyWildtype;
	typedef boolean onlyAggregate;
	typedef string feature_id;
	typedef list<feature_id> knockouts;
	typedef string strain_id;
	typedef mapping<strain_id, knockouts> strainToKOs;

	/*
	Returns the strains and their knockouts that match the given genome,
	maximum knockout count, and wildtype and aggregate data boolean flags.
	*/
	funcdef findStrainsAndKOs(genome_id, maxKnockouts, onlyWildtype, onlyAggregate) returns(strainToKOs);

	typedef string experimentMeta_id;
	typedef string group_id;
	typedef float min_temp;
	typedef float max_temp;
	typedef float min_oxygen;
	typedef float max_oxygen;
	typedef float max_pH;
	typedef float min_pH;

	typedef structure {
		genome_id genome;
		int maxKnockouts;
		boolean onlyWildtype;
		boolean onlyAggregate;
		list<experimentMeta_id> experimentMetaIDs;
		list<group_id> excludeGroups;
		list<group_id> onlyGroups;
		boolean growthBoolean;
		list<media_id> excludeMedias;
		list<media_id> onlyMedias;
		list<compound_id> excludeCompounds;
		list<compound_id> dropCompounds;
		boolean excludeSolid;
		boolean excludeUndefined;
		tuple<min_temp, max_temp> temperatureRange;
		tuple<min_oxygen, max_oxygen> oxygenRange;
		tuple<min_pH, max_pH> pHRange;
	} gmInputParams;
	typedef float fitnessValue;
	typedef tuple<knockouts, compounds, fitnessValue> growmatchRow;
	typedef list<growmatchRow> growmatchGroup;
	typedef mapping<group_id, growmatchGroup> growmatchData;

	/*
	Given a number of input parameters, returns data suitable for input into
	a growmatch FBA algorithm. The return value consists of a mapping of 
	ExperimentalUnitGroup IDs to a list of associated independent 
	knockouts/environment (consisting of a list of compounds in the
	environment) combinations with either a fitness value (see measurement 
	description IDs kb|measdesc.0 and 1) or a growth boolean (see 
	kb|measdesc.5) in the MeasurementDescription table. Groups, in this case,
	will typically be microarrays or RNAseq experiments. Data that is not 
	associated with any group is mapped from an empty string ('') instead
	of a KBase experimental unit group ID.
	Input values are:
	genome - the KBase ID of the genome to pull data from

	maxKnockouts - the maximum number of knockouts allowed for any strain
			in the return data (defaults to no limit) 

	onlyWildType - only strains marked as wildtype will be returned (default
			false (0))

	onlyAggregate - only strains that represent aggregate data from multiple
			strains will be returned (default true (1))

	experimentMetaIDs - the KBase IDs of the experimentMeta entities from 
				which to return data (default all)

	excludeGroups - the data related to the ExperimentalUnitGroup KBase IDs 
			in this list will be excluded from the results.

	onlyGroups - only the data related to the ExperimentalUnitGroup KBase IDs 
			in this list will be included in the results. excludeGroups
			will be ignored. An empty list results in no restrictions
			(default) except those in excludeGroups.

	growthBoolean - if true, returns data consisting of a growth boolean (1
			for grows, 0 for doesn't grow) rather than fitness values.
			Defaults to returning fitness values. There is no guarantee
			that a particular strain/environment combination with
			growth boolean data has fitness value data as well and 
			vice versa.

	excludeMedias - data using the media specified by the KBase media IDs in
			this list will not be returned.

	onlyMedias - only data using the medias in this list will be returned. If
			this list is not empty excludeMedias and excludeCompounds
			are ignored. If all three lists are empty no restrictions
			are placed on the medias allowed.

	excludeCompounds - any data using medias or environments containing these
				compounds or any of their parent compounds will not 
				be returned.

	dropCompounds - these compounds will be silently removed from the data 
			before it is returned. Typically used to remove compounds
			such as VitB12 which can interfere with FBA results. Does 
			not prevent using medias or environments containing the 
			compound.

	excludeSolid -	any data using solid medias will be excluded if true (1).
			Defaults to false (0).

	excludeUndefined - any data using undefined medias will be excluded if
				true (1). Defaults to false (0).

	temperatureRange - any data outside the given temperature range will be 
				excluded from the results. Defaults to no limits.

	oxygenRange - any data outside the given oxygen range will be excluded 
			from the results. Defaults to no limits. Recall that -1
			signifies the presence of an unknown but substantial 
			quantity of oxygen (as in an unmonitored shake flask,
			for example).

	pHRange - any data outside the given pH range will be excluded from the 
			results. Defaults to no limits. If a range is given, data
			without pH data will not be returned.	

	*/
	funcdef generateGrowmatchInput(gmInputParams) returns(growmatchData);

	typedef string workspace_id;
	typedef string object_id;

	/*
	As generateGrowmatchInput but rather than returning the data, it is
	stored in the authenticated user's workspace. The ID of the workspace
	into which to save the object as well as the ID to save the object to
	are required.
	*/
	funcdef generateAndStoreGMInput(gmInputParams, workspace_id, object_id) returns() authentication required;    
};