Notes installing the SBEAMS - Biosap module


-------------------------------------------------------------------------------
1) Software Dependencies

You must first install the SBEAMS Core.  See the separate installation
notes (sbeams.installnotes) on how to accomplish that.

The following Perl Modules often not found on a standard UNIX/Linux
setup are required to successfully use SBEAMS - Biosap (in addition
to the dependencies for the SBEAMS Core).

PDL                  Perl Data Language - available from CPAN
PDL::Graphics::PGPLOT
PDL::PGLOT

---------------
The following non-Perl software is required:

PGPLOT              (required by PDL::PGPLOT)

(Note that only the MS/MS spectrum viewer uses these modules.  It might
be nice to convert the spectrum view to use GD like some of the other
plotting functions in SBEAMS.  But this won't be a trivial task.)


-------------------------------------------------------------------------------
2) Installation Location

SBEAMS is designed to live entirely in the "htdocs" area of your Apache
web server.  For the remainder of this installation, it will be assumed
that your installation is configured as follows; compensate for your
specific setup:
  servername: db
  DocumentRoot: /local/www/html
  Primary location: directly located in DocumentRoot,
                   /local/www/html/sbeams  --> http:/db/sbeams/
  Development location: In a dev1 tree starting in the DocumentRoot,
                   /local/www/html/dev1/sbeams  -> http:/db/dev1/sbeams/

All modules live in the same area and should be unpacked into the
main SBEAMS area.

Set up the following sym links:

cd /local/www/html
cd dev1
cd sbeams
ln -s ../share/load_biosequence_set.pl lib/scripts/Proteomics/load_biosequence_set.pl


-------------------------------------------------------------------------------
3) Create and populate the database

It is assumed that you have already created and tested your SBEAMS Core
database.  You may either create a separate database for the Biosap
database or you can put everything in the same database.

Note that some database engines (rare now) may not permit
cross-database queries in which case your may NOT use separate
databases.  If you do use separate databases, you may not be able to
enforce referencial itegrety between tables in the different
databases.  This may or may not be a significant concern.

- If you decide on a separate database, create it and within it,
  create users "sbeams" and "sbeamsro" as a read/write
  account and a read-only account, respectively, as done for the Core.

- Generate the appropriate schema for your type(s) of database as follows:

setenv SBEAMS /local/html/dev1/sbeams
cd $SBEAMS/lib/scripts/Core

foreach dbtype ( mssql mysql pgsql oracle )
  ./generate_schema.pl --module Biosap \
    --table_prop ../../conf/Biosap/Biosap_table_property.txt \
    --table_col ../../conf/Biosap/Biosap_table_column.txt \
    --schema_file ../../sql/Biosap/Biosap --destination_type $dbtype
end

- Verify that the SQL CREATE and DROP statements have been correctly
  generated in $SBEAMS/lib/sql/Biosap/

- Execute the statements to create and populate the database with some
  bare bones data:

To CREATE:
mysql -u sbeams -p -h mysql $SBEAMSDB < $SBEAMS/lib/sql/Biosap/Biosap_CREATETABLES.mysql

To POPULATE:
mysql -u sbeams -p -h mysql $SBEAMSDB < $SBEAMS/lib/sql/Biosap/Biosap_POPULATE.mssql

To DROP:
mysql -u sbeams -p -h mysql $SBEAMSDB < $SBEAMS/lib/sql/Biosap/Biosap_DROPTABLES.mysql

Note that the Proteomics_POPULATE.mssql is not autogenerated and should
probably work for all flavors of database

Examples for table creation for other database flavors can be found in the
Core installation notes and will not be repeated here.


-------------------------------------------------------------------------------
4) Edit the SBEAMS Configuration files

setenv SBEAMS /local/www/html/dev1/sbeams

cd $SBEAMS/lib/conf
edit SBEAMS.conf

Specifically:

DBPREFIX{Biosap}    = Biosap.dbo.
RAW_DATA_DIR{Biosap} = /raw/datasets/root/location

Set DBPREFIX{Biosap} to the database name and schema/owner to prefix
to table names. 


-------------------------------------------------------------------------------
5) Populate the driver tables

cd $SBEAMS/lib/scripts/Core
set CONFDIR = "../../conf"
./update_driver_tables.pl $CONFDIR/Biosap/Biosap_table_property.txt
./update_driver_tables.pl $CONFDIR/Biosap/Biosap_table_column.txt

If this doesn't work.  Do not proceed, debug first.

Now that the Biosap driver tables are loaded, you should be able to
go to the web site again and click on SBEAMS - Biosap and explore the
tables.  They're all going to be empty, but you shouldn't get any errors,
just empty resultsets.

If this doesn't work.  Do not proceed, debug first.


-------------------------------------------------------------------------------
6) Add groups

Log in via the web interface as a user with Administrator privileges,
switch to the Admin group using the pull-down menu at the top, and add
two work groups:
[SBEAMS Home] [Admin] [Manage Work Groups] [Add Work Group]
Add entries for (exacly as shown!):
  Biosap_user
  Biosap_admin
  Biosap_readonly
(Note that after INSERTing the first, you can click [Back], edit the previous
information slightly, and click [INSERT] to add another.)

Biosap_admin has privilege over all tables in the Biosap
module, while the Biosap_user only has access to certain tables
and may often not modify other users records.  The Biosap_readonly
group is a separate group for looky loos.

Now go to [Manage User Group Associations], [Add ...], and add
yourself and whoever else to these groups as appropriate.

Now set up the table group securities:
  rowprivate - Biosap_user - data_writer
  rowprivate - Biosap_admin - data_writer
  rowprivate - Biosap_readonly - data_writer
  project - Biosap_user - data_writer
  project - Biosap_admin - data_modifier
  Biosap_infrastructure - Biosap_admin - data_modifier
  Biosap_user - Biosap_user - data_writer
  Biosap_user - Biosap_admin - data_modifier



-------------------------------------------------------------------------------
7) Add some sample data

(logged in as your user account)

Add a Project as follows:

- Switch to the Biosap_user group by using the drop-down box at top
- Click on [Biosap Home]
- Under "Projects You Own", click [Add A New Project].  Required
  fields are in red.  If you don't have a budget number, enter NA.
- Fill in the appropriate information and [INSERT]


Add an Experiment as follows:

- Click on [Biosap Home]
- Click on the Project you jst created
- Click [Register another Experiment]
- Fill in the appropriate information and [INSERT]


Register a Biosequence Set as follows:

A biosequence_set is a set of proteins, genes, orfs, etc., sometimes called
a "sequence database". .

Click [Add Biosequence Set]
Fill in the appropriate information.  Make sure that the set_path points
to the location of the FASTA file.  Do not use the upload functionality.  
[INSERT] that record.


-------------------------------------------------------------------------------
8) Test the Protoemics command line functionality

cd $SBEAMS/lib/scripts/Biosap

./load_biosequence_set.pl --check

Now try loading a biosequence set:

./load_biosequence_set.pl --set_tag YeastORF

This should load the biosequence set called YeastORF.  Replace YeastORF with
the tag of your Biosequence Set as defined in step 7.

If this doesn't work.  Do not proceed, debug first.