OpenBISScreeningML.java

     *         <code>{ 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 }</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
     * <var>experiment</var> (a location is one well position in one feature vector data set) in
     * <var>experiment</var> connected to <var>gene</var> in <code>[0]</code>, location annotations
     * in <code>[1]</code> and feature annotation in <code>[2]</code>.
     * <p>
     * One row in the matrix corresponds to one location (i.e. one well and one feature vector
     * dataset), one column corresponds to one feature.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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)
     * </pre>
     * 
     * @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 <code>{ feature matrix, annotations per location, feature names }</code> where
     *         <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ 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 }</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<Plate> experimentPlates = experimentToPlateMap.get(experiment);
        if (experimentPlates == null || experimentPlates.isEmpty())
        {
            return new Object[][][]
                { new Object[0][], new Object[0][], new Object[0][] };
        }
        final List<FeatureVectorWithDescription> featureVectors =
                openbis.loadFeaturesForPlateWells(experimentId, new MaterialIdentifier(
                        MaterialTypeIdentifier.GENE, gene), (features == null) ? null : Arrays
                        .asList(features));
        final List<String> 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 <var>gene</var> in <code>[0]</code>, location
     * annotations in <code>[1]</code> and feature annotation in <code>[2]</code>.
     * <p>
     * One row in the matrix corresponds to one location (i.e. one well and one feature vector
     * dataset), one column corresponds to one feature.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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)
     * </pre>
     * 
     * @param gene The gene name as stored as material code in openBIS
     * @return <code>{ feature matrix, annotations per location, feature names }</code> where
     *         <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ 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 }</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 <var>experiment</var> connected to
     * <var>gene</var> in <code>[0]</code>, location annotations in <code>[1]</code> and feature
     * annotation in <code>[2]</code>.
     * <p>
     * One row in the matrix corresponds to one location (i.e. one well and one feature vector
     * dataset), one column corresponds to one feature.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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)
     * </pre>
     * 
     * @param gene The gene name as stored as material code
     * @param features The names of the features to contain the feature matrix
     * @return <code>{ feature matrix, annotations per location, feature names }</code> where
     *         <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ 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 }</code>
     */
    public static Object[][][] getFeatureMatrix(String gene, String[] features)
    {
        checkLoggedIn();
        final List<FeatureVectorWithDescription> featureVectors =
                openbis.loadFeaturesForPlateWells(new MaterialIdentifier(
                        MaterialTypeIdentifier.GENE, gene), (features == null) ? null : Arrays
                        .asList(features));
        final List<String> 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
     * <var>plate</var> in <code>[0]</code>, location annotations in <code>[1]</code> and feature
     * annotation in <code>[2]</code>.
     * <p>
     * One row in the matrix corresponds to one location (i.e. one well and one feature vector
     * dataset), one column corresponds to one feature.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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)
     * </pre>
     * 
     * @param plate The gene name as stored as material code
     * @return <code>{ feature matrix, annotations per location, feature names }</code> where
     *         <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ 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 }</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
     * <var>plate</var> in <code>[0]</code>, location annotations in <code>[1]</code> and feature
     * annotation in <code>[2]</code>.
     * <p>
     * One row in the matrix corresponds to one location (i.e. one well and one feature vector
     * dataset), one column corresponds to one feature.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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)
     * </pre>
     * 
     * @param plate The gene name as stored as material code
     * @param features The names of the features to contain the feature matrix
     * @return <code>{ feature matrix, annotations per location, feature names }</code> where
     *         <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ 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 }</code>
     */
    public static Object[][][] getFeatureMatrixForPlate(String plate, String[] features)
    {
        checkLoggedIn();
        final List<FeatureVectorDataset> featureVectors =
                openbis.loadFeaturesForPlates(Arrays.asList(PlateIdentifier
                        .createFromAugmentedCode(plate)), (features == null) ? null : Arrays
                        .asList(features));
        FeatureVectorDataset last = featureVectors.get(featureVectors.size() - 1);
        final List<String> 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<String> getFeatureCodes(FeatureVectorDataset last)
    {
        return last.getFeatureNames();
    }

    /**
     * Returns the gene mapping for the given <var>plateCodes</var> in <code>[0]</code> and location
     * annotations in <code>[1]</code>.
     * <p>
     * One row in the matrix corresponds to one well.
     * <p>
     * Matlab example:
     * 
     * <pre>
     * % 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,:)
     * </pre>
     * 
     * @param platesCodes The augmented codes of the plates to get the mapping for
     * @return <code>{ gene ids, annotations per well }</code> where <code>gene ids</code> can be 0,
     *         1 or more gene ids. <code>annotations per location</code> contain:
     *         <p>
     *         <code>{ plate well description, plate augmented code, plate perm id,
     *         plate space code, plate code, row, column }</code>
     */
    public static Object[][][] getGeneMappingForPlates(String[] platesCodes)
    {
        checkLoggedIn();
        final List<PlateWellMaterialMapping> 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<MaterialIdentifier> 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<PlateIdentifier> toPlates(String[] augmentedPlateCodes)
    {
        final List<PlateIdentifier> result =
                new ArrayList<PlateIdentifier>(augmentedPlateCodes.length);
        for (String plateCode : augmentedPlateCodes)
        {
            result.add(PlateIdentifier.createFromAugmentedCode(plateCode));
        }
        return result;
    }

    private static Plate getPlate(String augmentedPlateCode)
    {
        Plate plateIdentifier = plateCodeToPlateMap.get(augmentedPlateCode);
        if (plateIdentifier == null)
        {
            throw new RuntimeException("No plate with that code '" + augmentedPlateCode + "' found.");
        }
        return plateIdentifier;
    }

    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.");
            }
        }
    }
}