* While written in Java, the API is idiomatic for Matlab, i.e. values are returned as
* multi-dimensional arrays. For the get... and load... methods the first
* index will contain the actual data, while the second index will contain per-row annotations. For
* getFeatureMatrix, the third index contains per-column annotations. This allows
* simple access with Matlab's slicing operator, see doc of e.g. {@link #getFeatureMatrix(String)}.
*
* A typical Matlab session looks like: * *
* % Add the API jar file to the classpath
* javaaddpath('/home/brinn/matlab/openbis_screening_api-batteries_included.jar')
* % Login to server
* OpenBISScreeningML.login('user', 'secret', 'https://www.infectome.org')
*
* % ...perform calls on the server...
*
* % Logout to close the session on the server
* OpenBISScreeningML.logout()
*
*
* Note: using this login your password will end up in the Matlab command history. An alternative
* that avoids this is to call the
* {@link ch.systemsx.cisd.openbis.generic.client.cli.Login} class. Logging in on the
* console will grant this class access to the openBIS server.
*
* @author Bernd Rinn
*/
public class OpenBISScreeningML
{
private static IScreeningOpenbisServiceFacade openbis = null;
private static List* Matlab example: * *
* OpenBISScreeningML.login('user', 'secret', 'https://www.infectome.org')
*
*
* @param user The user id on the server
* @param password The password on the server
* @param url The URL, e.g. https://www.infectome.org
*/
public static void login(String user, String password, String url)
{
openbis = ScreeningOpenbisServiceFacadeFactory.tryCreate(user, password, url);
if (openbis == null)
{
throw new RuntimeException("Login failed.");
}
init();
}
private static void init()
{
experiments = openbis.listExperiments();
experimentCodeToExperimentMap.clear();
for (ExperimentIdentifier e : experiments)
{
experimentCodeToExperimentMap.put(e.getAugmentedCode(), e);
}
plates = openbis.listPlates();
plateCodeToPlateMap.clear();
experimentToPlateMap.clear();
for (Plate p : plates)
{
final String plateCode = p.getAugmentedCode();
plateCodeToPlateMap.put(plateCode, p);
final String experimentCode = p.getExperimentIdentifier().getAugmentedCode();
List experimentPlates = experimentToPlateMap.get(experimentCode);
if (experimentPlates == null)
{
experimentPlates = new ArrayList();
experimentToPlateMap.put(experimentCode, experimentPlates);
}
experimentPlates.add(p);
}
}
/**
* Logs out and closes the session on the server.
*
* Matlab example:
*
*
* OpenBISScreeningML.logout()
*
*/
public static void logout()
{
if (openbis == null)
{
return;
}
openbis.logout();
if (Login.OPENBIS_TOKEN_FILE.exists())
{
Login.OPENBIS_TOKEN_FILE.delete();
}
openbis = null;
}
//
// Information methods
//
/**
* Lists all experiment.
*
* Matlab example:
*
*
* % Get the experiments
* exps = OpenBISScreeningML.listExperiments();
* % How many experiments do we have?
* length(exps)
* % Get all information about experiment 3
* exp3 = exps(3,:)
* % Get the perm ids for all experiments
* permids = exps(:,2)
*
*
* @return Each row contains information about one plate:
*
* { experiment augmented code, experiment perm id, experiment space code,
* experiment project code, experiment code }
*/
public static Object[][] listExperiments()
{
checkLoggedIn();
final Object[][] result = new Object[experiments.size()][5];
for (int i = 0; i < experiments.size(); ++i)
{
final Object[] annotations =
new Object[]
{ experiments.get(i).getAugmentedCode(), experiments.get(i).getPermId(),
experiments.get(i).getSpaceCode(),
experiments.get(i).getProjectCode(),
experiments.get(i).getExperimentCode() };
System.arraycopy(annotations, 0, result[i], 0, annotations.length);
}
return result;
}
/**
* Lists all plates.
*
* Matlab example:
*
*
* % Get the plates
* plates = OpenBISScreeningML.listPlates();
* % How many plates do we have?
* length(plates)
* % Get all information about plate 2
* plate2 = plates(2,:)
* % Get the simple plate codes for all plates
* codes = plates(:,4)
*
*
* @return Each row contains information about one plate:
*
* { plate augmented code, plate perm id, plate space code, plate code,
* experiment augmented code, experiment perm id, experiment space code,
* experiment project code, experiment code }
*/
public static Object[][] listPlates()
{
checkLoggedIn();
final Object[][] result = new Object[plates.size()][9];
for (int i = 0; i < plates.size(); ++i)
{
final Object[] annotations =
new Object[]
{ plates.get(i).getAugmentedCode(), plates.get(i).getPermId(),
plates.get(i).tryGetSpaceCode(), plates.get(i).getPlateCode(),
plates.get(i).getExperimentIdentifier().getAugmentedCode(),
plates.get(i).getExperimentIdentifier().getPermId(),
plates.get(i).getExperimentIdentifier().getSpaceCode(),
plates.get(i).getExperimentIdentifier().getProjectCode(),
plates.get(i).getExperimentIdentifier().getExperimentCode(), };
System.arraycopy(annotations, 0, result[i], 0, annotations.length);
}
return result;
}
/**
* Lists the plates of experiment.
*
* Matlab example:
*
*
* % Get the plates of experiment MYEXP in project PROJ of space SPACE
* plates = OpenBISScreeningML.listPlates('/SPACE/PROJ/MYEXP');
* % How many plates do we have?
* length(plates)
* % Get all information about plate 2
* plate2 = plates(2,:)
* % Get the augmented plate codes for all plates
* acodes = plates(:,1)
*
*
* @param experiment The augmented code of the experiment to list the plates for
* @return Each row contains information about one plate:
*
* { plate augmented code, plate perm id, plate space code, plate code,
* experiment augmented code, experiment perm id, experiment space code,
* experiment project code, experiment code }
*/
public static Object[][] listPlates(String experiment)
{
checkLoggedIn();
final List experimentPlates = experimentToPlateMap.get(experiment);
if (experimentPlates == null)
{
throw new RuntimeException("No experiment with that code found.");
}
final Object[][] result = new Object[experimentPlates.size()][9];
for (int i = 0; i < experimentPlates.size(); ++i)
{
final Object[] annotations =
new Object[]
{
experimentPlates.get(i).getAugmentedCode(),
plates.get(i).getPermId(),
experimentPlates.get(i).tryGetSpaceCode(),
plates.get(i).getPlateCode(),
experimentPlates.get(i).getExperimentIdentifier()
.getAugmentedCode(),
experimentPlates.get(i).getExperimentIdentifier().getPermId(),
experimentPlates.get(i).getExperimentIdentifier().getSpaceCode(),
experimentPlates.get(i).getExperimentIdentifier().getProjectCode(),
experimentPlates.get(i).getExperimentIdentifier()
.getExperimentCode(), };
System.arraycopy(annotations, 0, result[i], 0, annotations.length);
}
return result;
}
/**
* Lists all channels measured in experiment.
*
* Matlab example:
*
*
* % Get the channels of experiment MYEXP in project PROJ of space SPACE
* channels = OpenBISScreeningML.listChannels('/SPACE/PROJ/MYEXP');
* % How many channels do we have?
* length(channels)
* % What is the name of channel 1?
* channels(1)
*
*
* @param experiment The augmented code of the experiment to list the channels for
* @return Each row contains information about one channel. Currently the only information
* available is the channel name.
*/
public static Object[][] listChannels(String experiment)
{
checkLoggedIn();
final List experimentPlates = experimentToPlateMap.get(experiment);
if (experimentPlates == null)
{
throw new RuntimeException("No experiment with that code found.");
}
if (experimentPlates.isEmpty())
{
return new Object[0][];
}
final List imageDatasets =
openbis.listImageDatasets(experimentPlates);
if (imageDatasets.isEmpty())
{
return new Object[0][];
}
final List meta =
openbis.listImageMetadata(Arrays.asList(imageDatasets.get(0)));
if (meta.isEmpty())
{
return new Object[0][];
}
final List channels = getChannelCodes(meta);
Object[][] result = new Object[channels.size()][1];
for (int i = 0; i < result.length; ++i)
{
result[i][0] = channels.get(i);
}
return result;
}
@SuppressWarnings("deprecation")
private static List getChannelCodes(final List meta)
{
return meta.get(0).getChannelNames();
}
/**
* Lists all features computed for experiment.
*
* Matlab example:
*
*
* % Get the features of experiment MYEXP in project PROJ of space SPACE
* features = OpenBISScreeningML.listFeatures('/SPACE/PROJ/MYEXP');
* % How many features do we have?
* length(features)
* % What is the name of features 1?
* features(1)
*
*
* @param experiment The augmented code of the experiment to list the features for
* @return Each row contains information about one feature. Currently the only information
* available is the feature name.
*/
public static Object[][] listFeatures(String experiment)
{
checkLoggedIn();
final List experimentPlates = experimentToPlateMap.get(experiment);
if (experimentPlates == null)
{
throw new RuntimeException("No experiment with that code found.");
}
if (experimentPlates.isEmpty())
{
return new Object[0][];
}
final List featureDatasets =
openbis.listFeatureVectorDatasets(experimentPlates);
if (featureDatasets.isEmpty())
{
return new Object[0][];
}
final List features = listAvailableFeatureCodes(featureDatasets);
Object[][] result = new Object[features.size()][1];
for (int i = 0; i < result.length; ++i)
{
result[i][0] = features.get(i);
}
return result;
}
@SuppressWarnings("deprecation")
private static List listAvailableFeatureCodes(
final List featureDatasets)
{
return openbis.listAvailableFeatureNames(Arrays.asList(featureDatasets.get(0)));
}
//
// Images
//
/**
* Loads the TIFF images for the given well location and all channels and stores them in
* temporary files. The temporary files will be removed automatically when the Java Virtual
* Machine exits.
*
* Matlab example:
*
*
* % Load the images for all channels of well B10 of plate P005 in space SPACE
* imginfo = OpenBISScreeningML.loadImages('/SPACE/P005', 2, 10)
* % Get the plate-well descriptions of all locations
* imginfo(2,:,3)
* % Show the third image (assuming there are at least three images)
* imtool(imginfo(1,3))
*
*
* @param plate The augmented plate code
* @param row The row in the plate to get the images for
* @param col The column in the plate to get the images for
* @return { names of TIFF files, image annotation }
*
* Each of names of TIFF files and image annotation is a
* vector of length of the number of images.
*
* image annotation contains
* { channel name, tile number, plate well description,
* plate augmented code, plate perm id, plate space code, plate code, row, column,
* experiment augmented code, experiment perm id, experiment space code,
* experiment project code, experiment code, data set code }
*/
public static Object[][][] loadImages(String plate, int row, int col)
{
return loadImages(plate, row, col, (String[]) null);
}
/**
* Loads the TIFF images for the given well location and list of channels and stores them in
* temporary files. The temporary files will be removed automatically when the Java Virtual
* Machine exits.
*
* Matlab example:
*
*
* % Load the images for channel DAPI of well H10 of plate P005 in space SPACE
* imginfo=OpenBISScreeningML.loadImages('/SPACE/P005', 8, 10, 'DAPI')
* % Get the channel names and tile numbers of all locations
* imginfo(2,:,1:2)
* % Show the second image (assuming there are at least two images)
* imtool(imginfo(1,2))
*
*
* @param plate The augmented plate code
* @param row The row in the plate to get the images for
* @param col The column in the plate to get the images for
* @param channels The names of the channels to get the images for
* @return { names of TIFF files, image annotation }
*
* Each of names of TIFF files and image annotation is a
* vector of length of the number of images.
*
* image annotation contains
* { channel name, tile number, plate well description,
* plate augmented code, plate perm id, plate space code, plate code, row, column,
* experiment augmented code, experiment perm id, experiment space code,
* experiment project code, experiment code, data set code }
*/
public static Object[][][] loadImages(String plate, int row, int col, String[] channels)
{
checkLoggedIn();
final Plate plateId = plateCodeToPlateMap.get(plate);
if (plateId == null)
{
throw new RuntimeException("No plate with that code found.");
}
final List imageDatasets =
openbis.listImageDatasets(Arrays.asList(plateId));
final List meta = openbis.listImageMetadata(imageDatasets);
if (meta.isEmpty())
{
return new Object[][][]
{ new Object[0][], new Object[0][] };
}
final List imageChannels;
if (channels == null || channels.length == 0)
{
imageChannels = getChannelCodes(meta);
} else
{
imageChannels = Arrays.asList(channels);
}
final List imageReferences =
new ArrayList(imageDatasets.size());
final List imageFiles =
new ArrayList(imageDatasets.size() * imageChannels.size()
* meta.get(0).getNumberOfTiles());
final Object[][][] result = new Object[2][][];
result[0] =
new Object[imageDatasets.size() * imageChannels.size()
* meta.get(0).getNumberOfTiles()][1];
result[1] =
new Object[imageDatasets.size() * imageChannels.size()
* meta.get(0).getNumberOfTiles()][15];
int dsIdx = 0;
int resultIdx = 0;
for (ImageDatasetReference ds : imageDatasets)
{
final ImageDatasetMetadata m = meta.get(dsIdx);
for (String channel : imageChannels)
{
for (int tile = 0; tile < m.getNumberOfTiles(); ++tile)
{
final PlateImageReference ref =
new PlateImageReference(row, col, tile, channel, ds);
imageReferences.add(ref);
final File imageFile = createImageFileName(plateId, ref);
imageFiles.add(imageFile);
result[0][resultIdx][0] = imageFile.getPath();
final Object[] annotations =
new Object[]
{ channel, tile,
createPlateWellDescription(ds.getPlate(), row, col),
ds.getPlate().getAugmentedCode(),
ds.getPlate().getPermId(), ds.getPlate().tryGetSpaceCode(),
ds.getPlate().getPlateCode(), row, col,
ds.getExperimentIdentifier().getAugmentedCode(),
ds.getExperimentIdentifier().getPermId(),
ds.getExperimentIdentifier().getSpaceCode(),
ds.getExperimentIdentifier().getProjectCode(),
ds.getExperimentIdentifier().getExperimentCode(),
ds.getPermId(), };
System.arraycopy(annotations, 0, result[1][resultIdx], 0, annotations.length);
resultIdx++;
}
}
dsIdx++;
}
try
{
loadImages(imageReferences, imageFiles);
} catch (IOException ex)
{
throw new RuntimeException(ex);
}
return result;
}
/**
* Saves images for a given list of image references (given by data set code, well position,
* channel and tile) in the specified files.
* The number of image references has to be the same as the number of files.
*
* @throws IOException when reading images from the server or writing them to the files fails
*/
private static void loadImages(List imageReferences,
List imageOutputFiles) throws IOException
{
final Map imageRefToFileMap =
createImageToFileMap(imageReferences, imageOutputFiles);
try
{
openbis.loadImages(imageReferences, new IImageOutputStreamProvider()
{
public OutputStream getOutputStream(PlateImageReference imageReference)
throws IOException
{
return imageRefToFileMap.get(imageReference);
}
}, false);
} finally
{
closeOutputStreams(imageRefToFileMap.values());
}
}
private static void closeOutputStreams(Collection streams) throws IOException
{
for (OutputStream stream : streams)
{
stream.close();
}
}
private static Map createImageToFileMap(
List imageReferences, List imageOutputFiles)
throws FileNotFoundException
{
assert imageReferences.size() == imageOutputFiles.size() : "there should be one file specified for each image reference";
final Map map =
new HashMap();
for (int i = 0; i < imageReferences.size(); i++)
{
OutputStream out =
new BufferedOutputStream(new FileOutputStream(imageOutputFiles.get(i)));
map.put(imageReferences.get(i), out);
}
return map;
}
private static File createImageFileName(Plate plate, PlateImageReference image)
{
try
{
final WellPosition well = image.getWellPosition();
final File f =
File.createTempFile("img_", "_" + plate.getPlateCode() + "_"
+ image.getDatasetCode() + "_row" + well.getWellRow() + "_col"
+ well.getWellColumn() + "_" + image.getChannel() + "_tile"
+ image.getTile() + ".png");
f.deleteOnExit();
return f;
} catch (IOException ex)
{
throw new RuntimeException(ex);
}
}
//
// Feature matrix
//
/**
* Returns the feature matrix of all features for all locations in experiment (a
* location is one well position in one feature vector data set) connected to gene in
* [0], location annotations in [1] and feature annotation in
* [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for experiment /SPACE/PROJ/MYEXP for locations connected to GENENAME
* fmatrix = OpenBISScreeningML.getFeatureMatrix('/SPACE/PROJ/MYEXP', 'GENENAME');
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the fifth feature for all locations (assuming there are at least 5 features)
* feature5 = fmatrix(1,:,5)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param experiment The augmented experiment code
* @param gene The gene name as stored as material code in openBIS
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrix(String experiment, String gene)
{
return getFeatureMatrix(experiment, gene, (String[]) null);
}
/**
* Returns the feature matrix of the specified features for all locations in
* experiment (a location is one well position in one feature vector data set) in
* experiment connected to gene in [0], location annotations
* in [1] and feature annotation in [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for features FEATURE1, FEATURE2 and FEATURE for
* % experiment /SPACE/PROJ/MYEXP for locations connected to GENENAME
* fmatrix = OpenBISScreeningML.getFeatureMatrix('/SPACE/PROJ/MYEXP', 'GENENAME', ('FEATURE1','FEATURE2','FEATURE3'));
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the fourth feature for all locations (assuming there are at least 4 features)
* feature5 = fmatrix(1,:,4)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param experiment The augmented experiment code
* @param gene The gene name as stored as material code
* @param features The names of the features to contain the feature matrix
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrix(String experiment, String gene, String[] features)
{
checkLoggedIn();
final ExperimentIdentifier experimentId = experimentCodeToExperimentMap.get(experiment);
if (experimentId == null)
{
throw new RuntimeException("No experiment with that code found.");
}
final List experimentPlates = experimentToPlateMap.get(experiment);
if (experimentPlates == null || experimentPlates.isEmpty())
{
return new Object[][][]
{ new Object[0][], new Object[0][], new Object[0][] };
}
final List featureVectors =
openbis.loadFeaturesForPlateWells(experimentId, new MaterialIdentifier(
MaterialTypeIdentifier.GENE, gene), (features == null) ? null : Arrays
.asList(features));
final List featureNameList =
featureVectors.get(featureVectors.size() - 1).getFeatureNames();
final Object[][][] result = new Object[3][][];
if (featureVectors.isEmpty())
{
return result;
}
result[0] = new Object[featureVectors.size()][featureNameList.size()];
result[1] = new Object[featureVectors.size()][13];
int resultIdx = 0;
for (FeatureVectorWithDescription f : featureVectors)
{
arraycopy(f.getValues(), result[0][resultIdx]);
final Object[] annotations =
new Object[]
{
createPlateWellDescription(f),
f.getDatasetWellReference().getPlate().getAugmentedCode(),
f.getDatasetWellReference().getPlate().getPermId(),
f.getDatasetWellReference().getPlate().tryGetSpaceCode(),
f.getDatasetWellReference().getPlate().getPlateCode(),
f.getWellPosition().getWellRow(),
f.getWellPosition().getWellColumn(),
f.getDatasetWellReference().getExperimentIdentifier()
.getAugmentedCode(),
f.getDatasetWellReference().getExperimentIdentifier().getPermId(),
f.getDatasetWellReference().getExperimentIdentifier()
.getSpaceCode(),
f.getDatasetWellReference().getExperimentIdentifier()
.getProjectCode(),
f.getDatasetWellReference().getExperimentIdentifier()
.getExperimentCode(),
f.getDatasetWellReference().getDatasetCode(), };
System.arraycopy(annotations, 0, result[1][resultIdx], 0, annotations.length);
resultIdx++;
}
result[2] = new Object[featureNameList.size()][1];
for (int i = 0; i < featureNameList.size(); ++i)
{
result[2][i][0] = featureNameList.get(i);
}
return result;
}
/**
* Returns the feature matrix of all features for all locations (a location is one well position
* in one feature vector data set) connected to gene in [0], location
* annotations in [1] and feature annotation in [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for GENENAME
* fmatrix = OpenBISScreeningML.getFeatureMatrix('GENENAME');
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the fifth feature for all locations (assuming there are at least 5 features)
* feature5 = fmatrix(1,:,5)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param gene The gene name as stored as material code in openBIS
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrix(String gene)
{
return getFeatureMatrix(gene, (String[]) null);
}
/**
* Returns the feature matrix of the specified features for all locations (a location is one
* well position in one feature vector data set) in experiment connected to
* gene in [0], location annotations in [1] and feature
* annotation in [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for features FEATURE1, FEATURE2 and FEATURE for GENENAME
* fmatrix = OpenBISScreeningML.getFeatureMatrix('GENENAME', ('FEATURE1','FEATURE2','FEATURE3'));
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the second feature ('FEATURE2' here) for all locations
* feature2 = fmatrix(1,:,2)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param gene The gene name as stored as material code
* @param features The names of the features to contain the feature matrix
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrix(String gene, String[] features)
{
checkLoggedIn();
final List featureVectors =
openbis.loadFeaturesForPlateWells(new MaterialIdentifier(
MaterialTypeIdentifier.GENE, gene), (features == null) ? null : Arrays
.asList(features));
final List featureNameList =
featureVectors.get(featureVectors.size() - 1).getFeatureNames();
final Object[][][] result = new Object[3][][];
if (featureVectors.isEmpty())
{
return result;
}
result[0] = new Object[featureVectors.size()][featureNameList.size()];
result[1] = new Object[featureVectors.size()][13];
int resultIdx = 0;
for (FeatureVectorWithDescription f : featureVectors)
{
arraycopy(f.getValues(), result[0][resultIdx]);
final Object[] annotations =
new Object[]
{
createPlateWellDescription(f),
f.getDatasetWellReference().getPlate().getAugmentedCode(),
f.getDatasetWellReference().getPlate().getPermId(),
f.getDatasetWellReference().getPlate().tryGetSpaceCode(),
f.getDatasetWellReference().getPlate().getPlateCode(),
f.getWellPosition().getWellRow(),
f.getWellPosition().getWellColumn(),
f.getDatasetWellReference().getExperimentIdentifier()
.getAugmentedCode(),
f.getDatasetWellReference().getExperimentIdentifier().getPermId(),
f.getDatasetWellReference().getExperimentIdentifier()
.getSpaceCode(),
f.getDatasetWellReference().getExperimentIdentifier()
.getProjectCode(),
f.getDatasetWellReference().getExperimentIdentifier()
.getExperimentCode(),
f.getDatasetWellReference().getDatasetCode(), };
System.arraycopy(annotations, 0, result[1][resultIdx], 0, annotations.length);
resultIdx++;
}
result[2] = new Object[featureNameList.size()][1];
for (int i = 0; i < featureNameList.size(); ++i)
{
result[2][i][0] = featureNameList.get(i);
}
return result;
}
/**
* Returns the feature matrix of all available features for all locations (a location is one
* well position in one feature vector data set) of all feature vector data sets of the given
* plate in [0], location annotations in [1] and feature
* annotation in [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for PLATECODE
* fmatrix = OpenBISScreeningML.getFeatureMatrixForPlate('PLATECODE');
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the fourth feature for all locations (assuming there are at least 4 features)
* feature5 = fmatrix(1,:,4)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param plate The gene name as stored as material code
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrixForPlate(String plate)
{
return getFeatureMatrixForPlate(plate, (String[]) null);
}
/**
* Returns the feature matrix of the specified features for all locations (a location is one
* well position in one feature vector data set) of all feature vector data sets of the given
* plate in [0], location annotations in [1] and feature
* annotation in [2].
*
* One row in the matrix corresponds to one location (i.e. one well and one feature vector
* dataset), one column corresponds to one feature.
*
* Matlab example:
*
*
* % Get feature matrix for features FEATURE1, FEATURE2 and FEATURE for PLATECODE
* fmatrix = OpenBISScreeningML.getFeatureMatrixForPlate('PLATECODE', ('FEATURE1','FEATURE2','FEATURE3'));
* % Get the feature vector for the second location (assuming there are at least two locations)
* loc2 = fmatrix(1,2,:)
* % Get the values of the second feature for all locations
* feature5 = fmatrix(1,:,2)
* % What are the features?
* featureNames = fmatrix(3,:)
* % Get the plate-well descriptions of the locations
* locationDescriptions = fmatrix(2,:,1)
*
*
* @param plate The gene name as stored as material code
* @param features The names of the features to contain the feature matrix
* @return { feature matrix, annotations per location, feature names } where
* annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column, experiment augmented code, experiment perm
* id, experiment space code, experiment project code, experiment code, data set code }
*/
public static Object[][][] getFeatureMatrixForPlate(String plate, String[] features)
{
checkLoggedIn();
final List featureVectors =
openbis.loadFeaturesForPlates(Arrays.asList(PlateIdentifier
.createFromAugmentedCode(plate)), (features == null) ? null : Arrays
.asList(features));
FeatureVectorDataset last = featureVectors.get(featureVectors.size() - 1);
final List featureCodeList = getFeatureCodes(last);
final Object[][][] result = new Object[3][][];
if (featureVectors.isEmpty())
{
return result;
}
int numberOfRows = 0;
for (FeatureVectorDataset fvds : featureVectors)
{
numberOfRows += fvds.getFeatureVectors().size();
}
result[0] = new Object[numberOfRows][featureCodeList.size()];
result[1] = new Object[numberOfRows][13];
int resultIdx = 0;
for (FeatureVectorDataset fvds : featureVectors)
{
final FeatureVectorDatasetReference datasetRef = fvds.getDataset();
for (FeatureVector f : fvds.getFeatureVectors())
{
arraycopy(f.getValues(), result[0][resultIdx]);
final Object[] annotations =
new Object[]
{ createPlateWellDescription(datasetRef.getPlate(), f),
datasetRef.getPlate().getAugmentedCode(),
datasetRef.getPlate().getPermId(),
datasetRef.getPlate().tryGetSpaceCode(),
datasetRef.getPlate().getPlateCode(),
f.getWellPosition().getWellRow(),
f.getWellPosition().getWellColumn(),
datasetRef.getExperimentIdentifier().getAugmentedCode(),
datasetRef.getExperimentIdentifier().getPermId(),
datasetRef.getExperimentIdentifier().getSpaceCode(),
datasetRef.getExperimentIdentifier().getProjectCode(),
datasetRef.getExperimentIdentifier().getExperimentCode(),
datasetRef.getDatasetCode(), };
System.arraycopy(annotations, 0, result[1][resultIdx], 0, annotations.length);
resultIdx++;
}
}
result[2] = new Object[featureCodeList.size()][1];
for (int i = 0; i < featureCodeList.size(); ++i)
{
result[2][i][0] = featureCodeList.get(i);
}
return result;
}
@SuppressWarnings("deprecation")
private static List getFeatureCodes(FeatureVectorDataset last)
{
return last.getFeatureNames();
}
/**
* Returns the gene mapping for the given plateCodes in [0] and location
* annotations in [1].
*
* One row in the matrix corresponds to one well.
*
* Matlab example:
*
*
* % Get feature matrix for features FEATURE1, FEATURE2 and FEATURE for PLATECODE
* genes = getGeneMappingForPlate('PLATECODE');
* % Get the plate well location description of the 10th wells
* loc2 = genes(2,10,1)
* % Get the gene ids that are in the 10th well
* geneIds = genes(1,10,:)
*
*
* @param platesCodes The augmented codes of the plates to get the mapping for
* @return { gene ids, annotations per well } where gene ids can be 0,
* 1 or more gene ids. annotations per location contain:
*
* { plate well description, plate augmented code, plate perm id,
* plate space code, plate code, row, column }
*/
public static Object[][][] getGeneMappingForPlates(String[] platesCodes)
{
checkLoggedIn();
final List mappingList =
openbis
.listPlateMaterialMapping(toPlates(platesCodes),
MaterialTypeIdentifier.GENE);
int size = 0;
for (PlateWellMaterialMapping mapping : mappingList)
{
size +=
mapping.getPlateGeometry().getNumberOfRows()
* mapping.getPlateGeometry().getNumberOfColumns();
}
final Object[][][] result = new Object[2][size][];
int resultIdx = 0;
for (PlateWellMaterialMapping mapping : mappingList)
{
for (int row = 1; row <= mapping.getPlateGeometry().getNumberOfRows(); ++row)
{
for (int col = 1; col <= mapping.getPlateGeometry().getNumberOfColumns(); ++col)
{
final List genes = mapping.getMaterialsForWell(row, col);
result[0][resultIdx] = new Object[genes.size()];
for (int i = 0; i < genes.size(); ++i)
{
result[0][resultIdx][i] = genes.get(i).getMaterialCode();
}
final PlateIdentifier plate = mapping.getPlateIdentifier();
result[1][resultIdx] =
new Object[]
{ createPlateWellDescription(plate, row, col),
plate.getAugmentedCode(), plate.getPermId(),
plate.tryGetSpaceCode(), plate.getPlateCode(), row, col, };
++resultIdx;
}
}
}
return result;
}
//
// Helper methods
//
private static List toPlates(String[] augmentedPlateCodes)
{
final List result =
new ArrayList(augmentedPlateCodes.length);
for (String plateCode : augmentedPlateCodes)
{
result.add(PlateIdentifier.createFromAugmentedCode(plateCode));
}
return result;
}
private static void arraycopy(double[] src, Object[] dest)
{
for (int i = 0; i < dest.length; ++i)
{
dest[i] = src[i];
}
}
private static String createPlateWellDescription(FeatureVectorWithDescription f)
{
return createPlateWellDescription(f.getDatasetWellReference().getPlate(), f
.getWellPosition().getWellRow(), f.getWellPosition().getWellColumn());
}
private static String createPlateWellDescription(PlateIdentifier p, FeatureVector f)
{
return createPlateWellDescription(p, f.getWellPosition().getWellRow(), f.getWellPosition()
.getWellColumn());
}
private static String createPlateWellDescription(PlateIdentifier p, int row, int col)
{
return p.getPlateCode() + ":" + translateRowNumberIntoLetterCode(row) + col;
}
/**
* Translates a row number into letter code. Thus, 1 -> A, 2 -> B, 26 -> Z, 27 -> AA, 28 -> AB,
* etc.
*/
private static String translateRowNumberIntoLetterCode(int rowNumber)
{
int rowIndex = rowNumber - 1;
String code = "";
while (rowIndex >= 0)
{
code = (char) (rowIndex % 26 + 'A') + code;
rowIndex = rowIndex / 26 - 1;
}
return code;
}
private static void checkLoggedIn()
{
if (openbis == null)
{
if (Login.OPENBIS_TOKEN_FILE.exists())
{
BufferedReader br = null;
try
{
br = new BufferedReader(new FileReader(Login.OPENBIS_TOKEN_FILE));
final String token = br.readLine();
br.close();
br = new BufferedReader(new FileReader(Login.OPENBIS_SERVER_URL_FILE));
final String serverUrl = br.readLine();
br.close();
br = null;
openbis = ScreeningOpenbisServiceFacadeFactory.tryCreate(token, serverUrl);
if (openbis == null)
{
throw new RuntimeException("Login failed.");
}
init();
} catch (IOException ex)
{
if (openbis == null)
{
throw new RuntimeException("Login failed.", ex);
}
} finally
{
if (br != null)
{
try
{
br.close();
} catch (IOException ex)
{
// Silence this.
}
}
}
}
if (openbis == null)
{
throw new RuntimeException("Not logged in.");
}
}
}
}