BASE Development information Dynamic API overview Creating a root bioassayset

Dynamic API - Creating a root bioassayset

1. Prerequisites

• We must have an experiment with one or more raw bioassays connected to it.
• The logged in user must have write permission for the experiment.
• The user have specified which raw bioassays to use and which plugin to use for generating the intensities.
• This information should have been stored as job.

2. Run the job

1. Create a new Transformation item.
2. Add one or more raw bioassays to the transformation. The selected raw bioassays must be connected to the experiment. The same raw bioassay mustn't be added more than once.
3. Create a new BioAssaySet in a new data cube and layer.
4. Create a new BioAssay for each raw bioassay.
5. Create a PositionBatcher, a SpotBatcher and a MappingBatcher for the bioassayset.
6. Use the position batcher to insert the reporter for each position. This is only simple if all raw bioassays use the same array design, in which case it is guaranteed that all raw positions map to the same reporter. If this is not the case the plugin must re-map the raw positions to cube positions in such a way that no position maps to different reporters in different raw raw bioassays.
7. For each raw bioassay:
   1. Fetch all RawData.
   2. For each raw data spot:
      1. Calculate and insert the intensitites using the spot batcher.
      2. Insert a mapping to the raw data using the raw mapping batcher.
8. Close all batchers and commit the transaction.

Note! Most of the above steps are implemented by the net.sf.basedb.util.IntensityCalculatorUtil class. Most plugins should be able to use the methods in this class, and just supply an object implementing the IntensityCalculator interface that calculates the intensities from a raw data spot. Alternatively, the plugin could supply some Query API Expression objects that are used in a Query to let the database calculate the intensities.

Here is a full-fledged example if not using any of the utility classes in the core. It calculates the intensities as Mean FG - Mean BG.

/**
  Create new root bioassayset assuming all raw bioassays
  use the same array design, ie. each raw bioassay has the same
  reporter on the same position. The intensities are calculated
  as Mean FG - Mean BG.
*/
public BioAssaySet createRootBioAssaySet(Experiment e, Collection<RawBioAssay> rba)
{
  DbControl dc = e.getDbControl();
  
  // Create Transformation
  Transformation t = e.newTransformation(null, rba);
  dc.saveItem(t);
  
  // Create root BioAssaySet in new data cube and layer
  BioAssaySet root = t.newProduct("new", "new", false);
  root.setName("New root bioassayset");
  dc.saveItem(root);
  
  // Create the batchers we need
  PositionBatcher posBatcher = root.getPositionBatcher();
  SpotBatcher spotBatcher = root.getSpotBatcher();
  MappingBatcher rawBatcher = root.getMappingBatcher();
  
  // For the first raw bioassay we must also insert reporter mappings
  boolean first = true;
  for (RawBioAssay raw : rba)
  {
    // Create a new BioAssay for each raw bioassay
    BioAssay ba = root.newRootBioAssay(Collections.singleton(raw));
    dc.saveItem(ba);

    // This is the column coordinate in the datacube
    short column = ba.getDataCubeColumnNo();

    // Load raw data for current raw bioassay
    DataResultIterator<RawData> rawData = raw.getRawData().iterate(dc);
    while (rawData.hasNext())
    {
      RawData rd = rawData.next();
      int position = rd.getPosition();

      // Calculate intensities
      float[] intensities = new float[2];
      intensities[0] = (Float)rd.getExtended("ch1FgMean") - 
        (Float)rd.getExtended("ch1BgMean");
      intensities[1] = (Float)rd.getExtended("ch2FgMean") - 
        (Float)rd.getExtended("ch2BgMean");
      if (first)
      {
        // Insert reporter, assuming all raw bioassays have the same
        posBatcher.insert(column, position, rd.getReporter();
      }

      // Insert mapping to raw data spot
      rawBatcher.insert(column, position, rd);

      // Insert intensities
      spotBatcher.insert(column, position, intensities);
    }
    first = false;
  }

  // Close batcher
  posBatcher.close();
  spotBatcher.close();
  rawBatcher.close();

  // Commit and return  
  dc.commit();
  return root;
}

A better and more realistic example uses the Java Math Expression Parser (JEP) to convert a mathematical expression in a string to an Expression object which is then used in a by the IntensityCalculatorUtil class in query. This method is much more prefered than the one used in the previous example.

/**
  Create new root bioassayset assuming all raw bioassays
  use the same array design, ie. each raw bioassay has the same
  reporter on the same position. The intensities are calculated
  as Mean FG - Mean BG.
*/
public BioAssaySet createRootBioAssaySet(Experiment e, RawBioAssay... rba)
{
  DbControl dc = e.getDbControl();
  RawDataType rdt = e.getRawDataType();
  
  String ch1Formula = "raw(ch1FgMean) - raw(ch1BgMean)";
  String ch2Formula = "raw(ch2FgMean) - raw(ch2BgMean)";
  
  // Defines the 'raw(column)' function so we can use it in formulas
  RawFunction raw = new RawFunction(rdt);
  Expression ch1 = Jep.formulaToExpression(ch1Formula, raw);
  Expression ch2 = Jep.formulaToExpression(ch2Formula, raw);
  
  return IntensityCalculatorUtil.createRootBioAssaySet(dc, e, rba, null, ch1, ch2);
}