The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
LIMS-MT_Plate-1.2
River stage zero No dependents
++
/ LIMS::MT_Plate

NAME

LIMS::MT_Plate - A Perl module for creating and manipulating micro-titre plate objects

SYNOPSIS

        use LIMS::MT_Plate;

        $oPlate = mt_plate->new('a plate with 96 wells',96);
        $oPlate->fill_wells(\@wells,\@samples);
        $sample_well_A1 = $oPlate->get_sample_name('A1');
        $aSamples_Ref = $oPlate->all_samples;

DESCRIPTION

LIMS::MT_Plate is a Perl module for creating and manipulating microtitre plate objects. It defines a Class of MT_Plate for each microtitre format, which include variables specific to the format and methods that are common to all.

The most common use of MT_Plate is to enable the consistent assignment of multiple samples to wells of a microtitre plate while ensuring the plate layout is valid for the specified format, and also to more easily manage the transfer of samples from plate to plate.

MT_Plate currently supports 96, 384 and 1536 well plate formats, as well as an individual tube, and provides methods for filling individual wells, and multiple wells. The filling of multiple wells supports either row-by-row (i.e. A1=sample1, A2=sample2, etc) or column-by-column ordering (i.e. A1=sample1, B1=sample2, etc), depending on the name format of the wells passed to the method fill_wells() as described in the examples above.

The identity of a sample in a single well can be returned, or alternatively all of the samples in the plate can be exported as a reference to an array. Similar to the filling of wells, the order of the samples returned in the array can be either row-by-row, or col-by-col, as described in the examples above.

What the module won't do is re-order samples in a plate. The reasons for this might not be obvious to someone who doesn't work in a laboratory - but if you don't want to contaminate your samples that's basically a no-no. What you would do instead is transfer the samples from one plate to another, re-ordering them as you do so - and that's what you should do if you use MT_Plate.

METHODS

Creating Plate Objects

There are two ways you can create an MT_Plate object

        $oPlate = mt_plate->new('a 96-well plate',96);
        $oPlate = mt_96->new('a 96-well plate');

In either case, the name (barcode) is optional, and can be set later

        $oPlate->barcode('another mt_plate');

Several different formats are currently supported, including a single-well plate (otherwise known as a tube).

        $oTube = tube->new('a microfuge tube');
        $oPlate = mt_384->new('a 384-well plate');
        $oPlate = mt_1536->new('a 1536-well plate');

Filling Wells

From a file

Most likely, you have a flat file naming all the samples in your plate, and you'd like to import that into an MT_Plate object. To do this you will need to install the Microarray modules, and use the module LIMS::MT_Plate_File. First, create an MT_Plate object of the correct class and then use the import_mt_plate_file() method to import the file;

        $oPlate->import_mt_plate_file('mt_plate_file',$file,$fh);       # shifting file type, file name/path, filehandle

The filehandle is an optional parameter to the import_mt_plate_file() method, since a filehandle will be created so long as the correct path to the file is provided. However, for instances where the file path is not available but a filehandle is (for instance, following upload of a file on a web page) you can pass the file name and filehandle separately.

Manually - single well

        $oPlate->fill_well('A1','sample1');

Manually - multiple wells

Samples are added to a plate by passing an array reference to the fill_wells() function. In the simplest case, the wells are filled row-by-row (i.e. well A1 gets $samples[0], A2 gets $samples[1], etc). This is the default order for all functions.

        $oPlate->fill_wells(\@samples);

You can also specify other well orders, or numbers of samples other than a full plate. A range of wells can be specified as shown in the first example below, and this format can be used to change the filling order to column-by-column, simply by turning round the well names (i.e. A1 gets $samples[0], B1 gets $samples[1], etc). Aternatively, you can set the order using the well_format() method.

        $oPlate->fill_wells('A1','P24',\@samples);      # row-by-row filling
        $oPlate->fill_wells('1A','24P',\@samples);      # col-by-col filling

If you have an array of appropriate well names, then this can be passed along with the samples such that the order of wells in the array will determine the filling order.

        $oPlate->fill_wells(\@wells,\@samples);

Or you can fill by row or column name. Unlike fill_wells() described above, each of these following methods actually removes samples from the '$aSamples' list as they are added to a well.

        $oPlate->fill_row('A',$aSamples);
        $oPlate->fill_rows(['A'..'D'],$aSamples);
        $oPlate->fill_col(1,$aSamples);
        $oPlate->fill_cols([1..6],$aSamples);

By default, you can't replace the contents of a well that already has a sample in it, but you can override this, or reset as follows;

        $oPlate->can_replace;   # will replace a sample
        $oPlate->dont_replace;  # will die if asked to replace a sample
        $oPlate->warn_dont_replace;     # will warn if asked to replace a sample

If you use any of the well filling methods on a plate that already has samples in, while warn_dont_replace() is set, then any sample asked to fill an already filled well will be missed out of the process to avoid filling the un-fillable well.

Specifying sample type

You also can specify a 'sample_type()', either for each individual well, or one type for the whole plate.

        $oPlate->fill_well('A1','sample','sample_type');                # by passing after the sample name in 'fill_well()'
        $oPlate->sample_type('A1','sample_type');               # or using 'sample_type()' after a well has been filled
        $oPlate->all_sample_types('sample_type');               # all samples are set the same
        $oPlate->all_sample_types(\@aSample_Types);             # different types set at once
        my $sample_type = $oPlate->sample_type('A1');
        my $aSample_Types = $oPlate->all_sample_types;

Identifying Plate Contents

Single well

        $sample = $oTube->get_sample_name;
        $sample = $oPlate->get_sample_name('A1');

Row or Column

        $aSamples = $oPlate->row_contents('A');
        $aSamples = $oPlate->rows_contents(['A'..'D']);
        $aSamples = $oPlate->col_contents(1);
        $aSamples = $oPlate->cols_contents([1..6]);

Whole plate

The entire contents of a plate can be returned as a reference to an array, either ordered row-by-row (ie A1, A2 etc) or column-by-column (ie A1, B1, etc). If no order is specified, row-by-row defaults. Can also set the return order using the well_format() method.

        $aSamples_Ref = $oPlate->all_samples('row');    
        $aSamples_Ref = $oPlate->all_samples('col');

Well names can be returned as an array ref

        $aWell_Names = $oPlate->well_names('row');
        $aWell_Names = $oPlate->well_names('col');

...allowing you to easily loop through all of the wells

        for my $well (@$aWell_Names) {
                print "well $well; ".$oPlate->get_sample_name($well)."\n";
        }

Finally, you can retrieve an array ref containing the sample names in a specified list of well names

        $aSamples = $oPlate->get_sample_names(\@aWells);

Joining Plates

Two or more plates can be combined into a larger format plate. Joining 4x 96, 4x 384, or 16x 96 places samples in quadrant offsets. When joining tubes into a plate format, the samples are ordered linearly, row-by-row.

        $oPlate->join_plates($oPlate1,$oPlate2,$oPlate3,$oPlate4);

Alternatively, two plates can be combined using the combine_plates() method. This will simply replace the target object's well contents with those from a source plate passed to combine_plates(). Empty wells in the source plate will not cause wells in the object plate being 'emptied' - only if there is a sample in the source will any change occur. You can also specify wells to be combined, rather than combining the whole plate.

        $oPlate->combine_plates($oPlate2);                      # whole plates are combined
        
        $aWells = ['A1,'A2','A3'];
        $oPlate->combine_plates($oPlate2,$aWells);      # only specific wells are combined

Finally, a 96-well plate can be added to a 384-well plate in a given quadrant. This is similar to executing the join_plates() method, but only specifying one of the source plates.

        $oPlate->add_plate($oPlate2,'B1');

Comparisons

        if ($oPlate1 < $oPlate2) {
                print $oPlate1->barcode," is a smaller format than ",$oPlate2->barcode,"\n";
        } elsif ($oPlate1 > $oPlate2) {
                print $oPlate1->barcode," is a bigger format than ",$oPlate2->barcode,"\n";
        } elsif ($oPlate1 ^ $oPlate2) {
                print $oPlate1->barcode," and ",$oPlate2->barcode," are the same format\n";
        }

Other Methods

Several other methods return variables associated with the object

barcode

Returns the plate barcode if no argument is passed

wells

Returns the number of wells in the plate i.e. the plate format

cols

Returns the number of columns in the plate

rows

Returns the number of rows in the plate

wells_filled

Returns the number of wells in the plate that have a sample in them

row_names

Returns an array ref containing the row names

col_names

Returns an array ref containing the column numbers

AUTHOR

Christopher Jones, Gynaecological Cancer Research Laboratories, UCL EGA Institute for Women's Health, University College London.

http://www.instituteforwomenshealth.ucl.ac.uk/AcademicResearch/Cancer/trl

c.jones@ucl.ac.uk

COPYRIGHT AND LICENSE

Copyright 2008 by Christopher Jones

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.