TRAM (Transcriptome Mapper) 1.3

TRAM generates and analyzes transcriptome maps. It is able to import and integrate any gene expression data source in tabulated text format and to map expression values to the relevant genomic region, providing statistical analysis of over- or under-expressed regions compared to the whole genome or to the relative chromosome.

Once decompressed, TRAM is ready to be used.
Macintosh: open the "TRAM" application ("TRAM" or "TRAM.app" file) contained in the "TRAM" folder.
Windows: open the "TRAM" application ("TRAM" Runtime file) contained in the "TRAM" folder.

The minimum software requirements are:
Mac OS X 10.6, OS X Lion 10.7, OS X Mountain Lion 10.8;
Windows XP Professional, Home Edition (Service Pack 3);
Windows Vista Ultimate, Business, Home Premium (Service Pack 2);
Windows 7 Ultimate, Professional, Home Premium;
Windows 8 Standard and Pro edition.

A connection to the Internet is required to display the software Guide and to download data for set up, but not to run the tool.

Please do not change the name of all files and folders of the TRAM software.

You may download multiple copies of TRAM and run them simultaneously, provided that each "TRAM" folder is located in a different directory.
Do not move the "TRAM" folder while the software is open.
Run the "TRAM" software from a local hard disk.
Do not run the software from a network drive.

If a TRAM analysis aborts unexpectedly, it is advisable to restart it in a fresh TRAM copy.

Simply use buttons to navigate in the different sections of the software. The "Back" button brings user to the last visited layout (and not to all previously visited layouts). The "Home" button brings user to the main software screen, from which any layout may be reached.

The TRAM file in the TRAM_HUMAN (or TRAM_MOUSE, TRAM_BRARE if available) species-specific versions is pre-loaded with the latest human (or mouse, or zebrafish, respectively) data for genes, chromosomes, UniGene cluster IDs and all related GenBank Accession Numbers, Expressed Sequence Tags (ESTs).
In addition, the gene identifiers for common commercially available array Platforms as deposited in Gene Expression Omnibus (GEO) are also available in these pre-setup versions (see section 2.2 for details). Please, if you use any other gene identifier type read the "Set up" chapter, section 2.2.

The number of the current National Center for Biotechnology Information (NCBI) Genome Build may be obtained from the site:
http://www.ncbi.nlm.nih.gov/mapview/
by clicking on the organism of interest.
The corresponding genome assembly version used by University of California, Santa Cruz (UCSC) Genome Browser to produce EST localization data may be chosen from the "assembly" menu in the "Table Browser" web page:
http://genome.ucsc.edu/cgi-bin/hgTables?

While TRAM_HUMAN.zip file contains a pre-setup version ready to analyze expression data from human organism, you may also download an empty TRAM template that may be prepared for the analysis of data from any organism.

Pre-setup versions may be directly used to import and analyze expression data without performing the "Set up" process. However, the user could need to perform the "Set up" section 2.2 to load additional Platform schemes if necessary to interpret the gene identifiers listed in his expression data file (see below).
The empty TRAM template must instead always be prepared by performing the "Set up" process from the beginning.

Download the "TRAM.zip" file from:
http://apollo11.isto.unibo.it/software/TRAM/
Following decompression of the "TRAM_1.3.zip" (or TRAM_1.3_Win.zip) file, open the "TRAM" file contained in the "TRAM" folder.

In the "Main" window click "Set Up", this will change to the "Set Up" layout which contains the first main choices.

Set up is composed of two main parts.
1) Organism-specific Genomic Data
Guided feeding of the software with data about chromosomes and genes of the genome of your interest.
2) Gene Identifiers conversion tables
Guided feeding of the software with conversion tables; this allows the conversion of each gene identifier used in the expression data file to the corresponding gene name.

At the end of Set Up, the user may proceed with expression data file import.

The software is optimized to parse "NCBI Gene" data to obtain the necessary localization information, due to both the short update period and the gene position accuracy of this database. You may use other sources of data, provided that they are in the format described below (column number and order, file name) to ensure a correct TRAM functioning.

TRAM cannot analyse non-chromosomal elements (such as plasmids), while it is able to map mitochondrial chromosome genes since version 1.2, although mitochondrial genes have not been considered in TRAM_HUMAN pre-loaded versions.

Note: the maximum number of chromosomes accepted by the software is 25 (including autosomal and sexual), only for the purpose of "horizontal" viewing, and unlimited for all other purposes.

When different types of deposited sequences (e.g., with NC_ reference or AC_  or NT_ code type) are available for the studied organism, NC_ (RefSeq) sequence should be chosen as default for each chromosome, AC_ sequence should be chosen, if available, in absence of an NC_ sequence and finally, NT_ sequence should be selected as a last choice.

The following instructions are also available as a guided procedure within the software in the "Set Up" area.
From the TRAM Home, click on the "Set Up" button - then on "Genomic" - then on "Chromosomes".

For example, you may obtain from "NCBI Genome" the data for each chromosome.
Click on the "Open "NCBI Genome" web site" button.

If you did not already set the "Organism" field into the "Setting Segment" or "Setting Cluster" window, the software will ask you for the searched "Organism", please insert the name only as Latin name (e.g. Human = Homo sapiens).

If appropriate, use complete species/strain name given in  square brackets by "Entrez Gene" online database (e.g., Saccharomyces cerevisiae S288c).

In the "NCBI Genome" organism-specific displayed page, locate the "Representative" genome information, then click on individual (RefSeq) chromosome entries at the bottom of the page.

Write the resulting data in a standard tabulated text file (.txt), separating each column by a "tab",
in this format [without Column Headers; use the "Name" reported in the Reference genome as the identifier for each chromosome]:

[Chromosome]   [Length]       [Organism]    [RefSeq/Genbank#]
1              248,956,422    Homo sapiens  NC_000001
2              242,193,529    Homo sapiens  NC_000002   
...

Move the obtained file, named genome.txt, into the "TRAM" folder.

Following chromosome data import it is useful to check the "Chromosome" Table (click on the "Chromosomes" link in TRAM page from which you have launched the import of chromosome data, or on the "Chr." button in the TRAM Home).
You may manually edit the chromosome records if necessary, using the "Record" Menu and typing into the appropriate fields.

Note: for organisms with only one chromosome (e.g., prokaryotes) insert manually the chromosome data, as follows:
from TRAM Home, click on the "Chr." button,
then on the appearing "Chromosome" layout
create a new record by selecting "New record" from the "Record" menu and insert these data manually in the corresponding field:

Chromosome
Chromosome (exactly this word: chromosome).
Length

1.2 Importing localization data for known genes        

a) Download the data for each gene from "NCBI Gene"
                                        
Note: All previously imported data will be deleted.

Note: if the software asks you for the name of the "Organism", please insert this only as Latin name (e.g. Human = Homo sapiens).
If appropriate, use complete species/strain name given in  square brackets by "Entrez Gene" online database (e.g., Saccharomyces cerevisiae S288c).

Click on the "Open "NCBI Gene" web site" button.

The "Entrez Gene" web page will be opened showing all gene data needed for the specified organism.

In the "NCBI Gene" displayed page (in the web browser),
check that "Current" is selected as "Status" on the left column.

Save the resulting data as follows:
click on the "Send to" link on the right,
choose "File"
(and select "Tabular (text)" format, default order)
then click on the "Create file" button
(do not change the suggested file name).

Move the obtained "gene_result.txt" into the "TRAM" folder.

b) Import the file
Click on the "Import the "gene_result.txt" file" button
to automatically import and parse the downloaded gene data.

IMPORTANT - Do not import the same text file more than once into TRAM database; download or decompress the file again if you need to repeat the import twice.

Gene entries without genomic coordinates,
or with the word "Pseudogene" in the "Description" field (except when in the context "readthrough transcribed pseudogenes" or "gene/pseudogene") will be deleted.

At the end, data fields in the table for an RNA transcript will appear as follows:

[Chromosome]    [start site]    [end site]    [Gene symbol]
chr1            67,278,568      67,390,570    WDR78

1.3  Importing localization data for EST Clusters, if these data are available in "UCSC Genome Browser"

Note: this step is necessary if you wish to analyze the expression data not only for known genes but also for genes so far identified only as UniGene Cluster (cluster of ESTs, Expression Sequence Tags).
The genomic coordinates for UniGene Cluster are available for several organisms in the "UCSC Genome Browser" (University of California, Santa Cruz).

Assembly (build) version for the investigated genome in UCSC and NCBI must be the same, in order to use the same reference genome coordinates and successfully integrate localization data from known genes and from ESTs.

The number of the current NCBI Genome Build may be obtained from the site:
https://www.ncbi.nlm.nih.gov/genome/gdv/
by clicking on the organism of interest.
The corresponding genome assembly version used by UCSC Genome Browser to produce EST localization data may be chosen from the "assembly" menu in the "Table Browser" web page:
http://genome.ucsc.edu/cgi-bin/hgTables?

Note:
All previously imported EST Clusters data will be deleted.
Note:
this step must be performed after the previous "Set up Genes" process (section 1.2) and the UniGene identifiers conversion table import (section 2.1).

a) Download the EST localization data from UCSC "Genome Browser"


Click on the "Open Genome Browser site" button.

Then in the web browser page select:
clade:     your investigated clade (e.g., Mammal)
genome:    your investigated genome (e.g., Human)
group:     "mRNA and EST Tracks"
track:     "ESTs" (if available, otherwise current set up
                   is not possible)
table:     "all_est"
region:    "genome"

output format:         "selected fields from primary
                       and related tables"
output file:           EST.txt
file type returned:    gzip compressed

Click on the "get output" button and select the following fields in the appearing table:
qName
tName
tStart
tEnd

Click on the "get output" button at the bottom of the page.
Once the download of the file "EST.txt.gz" is complete, decompress it and put the resulting "EST.txt" file into the "TRAM" folder.

b) Import the file
Click on the "Import "EST.txt" file" button,
to automatically import and parse the obtained UniGene clusters location data file.

At the end, data fields in the table for an RNA transcript will appear as follows:


EST entries are parsed via their relationship with "UniGene_ID" table: ESTs belonging to UniGene Clusters are imported in the "EST_Clusters" table, where localization for each cluster is calculated between the minimum start coordinate and the maximum end coordinate available for each EST cluster.
To omit incongruent results, the parsing process will subsequently import in the "Genes" table only the unambiguously mapped UniGene clusters. To this aim, entries with a chromosome name not equal to one in the chromosome names in the "Chromosomes" table will not be considered, as well as those with ESTs mapping on very distant positions on the same chromosome. To this aim, we set a conservative limit to 250,000 bp in TRAM, considering that in Entrez Gene the set was of 28,355 human genes (the largest known genes), the mean size was 43,698 and the standard deviation 102,616, so this is equivalent to consider a size range within mean plus or minus 2 SD (approximately 95% of values in a Gaussian distribution). This correction effectively removes approximately 3,000 transcripts erroneously mapped to regions of several Mb or tens of Mb. The user retains the possibility to inspect the list of EST clusters with a genomic extension >250 kb that are present in a given chromosome segment, even if they are not considered in the creation of the transcriptome map. For this purpose, click "Go" under the title "Genes Table" in the "Map" result layouts, then click "EST Clusters - Go".

2 Importing gene identifiers conversion data tables
(Back to Index)

USE                                                                            
(Back to Index)

A protocol for the execution of meta-analysis by the TRAM software is available along with the TRAM 1.3 version ("TRAM_Meta_Analysis_Protocol_2017" file, located in the "TRAM Utilities" directory of the TRAM web site).

While TRAM_HUMAN.zip file contains a pre-setup version ready to analyze expression data from human organism, you may also download an empty TRAM template that may be prepared for the analysis of data from any organism.
 
Pre-setup versions may be directly used to import and analyze expression data without performing the "Set up" process. However, the user might need to perform the "Set up" section 2.3 to load additional Platform schemes if necessary to interpret the gene identifiers listed in his expression data file (see below).
Conversely, the empty TRAM template must always be prepared by performing the "Set up" process from the beginning (section 1).

Note - Data saving
TRAM, as any FileMaker-based database, automatically saves any changes, so you will not find any save options at the end of the import processes.
After the import processes, avoid any manual data change that may cause the loss of the original imported data.

Note - Advanced use
You may open the program files using your copy of FileMaker 12 or later, thus becoming fully able to make any modification to the software.
In this case, do not open the program using the "TRAM" file, but open, within FileMaker Pro, the file "TRAM.TMA" instead.
Following modifications, the correct functioning of the program requires its re-launch by "TRAM" runtime, due to data pathway structure stored in the "TRAM" Scripts.

To cancel a TRAM operation before it is completed (not recommended):
Press Command-period keys (Mac OS X) or Esc (Windows).

It is possible to compare two different biological conditions, importing one as the A sample (or samples pool), and the other as the B sample (or sample pools) to be compared to A.

Switching by TRAM database tables may be done by clicking on the relative buttons present in each layout.

A protocol for the execution of meta-analysis by the TRAM software is available along with the TRAM 1.3 version ("TRAM Meta-Analysis Protocol 2017" file).

Each series of data related to a "Sample" is defined as a "distinct biological sample", for example in the case of two channel experiment, a sample should be a single channel, each channel data being imported as a distinct data file.

Be sure that your system default format uses
"." (full stop mark)
as a decimal separator (English standard).
See below how to check and change the setting if necessary.

IMPORTANT. The expression data file must be a tabulated (tab-delimited) text file containing two columns separated by a TAB character (tabulator key, ASCII9).

First ("left") column: Gene probe identifier:
   Official Gene Symbols/"NCBI Gene" names (default);
   or, if set up the relative conversions:
   Custom identifiers, or
   Platform Identifiers or
   GenBank Accession Numbers.

Second column: numerical expression value.
Use "." as a decimal separator
(and do not use a thousand separator).
Be sure that your system default format uses
"." (full stop mark)
as a decimal separator (English standard).
If this is not the case, you must change the system setting.

Mac OS X: in "System Preferences" (from the "Apple" Menu),
click on "International", then on "Formats",
then choose as "Region" a country with the English standard format for numbers (full stop mark as a decimal separator).
System restart or user logout is not required to make the change effective.
Windows: in "Control Panel" (from the "Start" Menu),
click on "International options" then modify the format of numbers choosing a country with the English standard format for numbers (full stop mark as a decimal separator).
System restart or user logout is not required to make the change effective.

The expression value is usually the pre-processed intensity value, i.e. the value assigned to the spot as it has been processed by the software of the specific experimental platform used (for instance following background subtraction for a microarray spot).
Scientific notation is supported in the format, for example, 20E-2.
TRAM considers the expression values as linear data, and not logarithm-transformed data. If necessary, data should be retransformed before importing them in TRAM. TRAM can back-transform log-transformed values (in base 2, 10 or e) if user prepares data using "Help with data" utility (see below).
Ratio values (e.g., ratio between two microarray channels) are not admitted in TRAM.

GEO_GSM_Download is a tool useful to download automatically data matching a list of GEO samples (GSM) from the GEO database (Gene Expression Omnibus).
It is distributed along with TRAM in the directory "TRAM_Utilities" at:
http://apollo11.isto.unibo.it/software/TRAM/.
Requirements: any operating system (Linux, Mac OS X, Windows, ...) with Python 2 or Python 3 and IDLE.

When the pre-processed expression values are not available, the user may consider the background (BKD) median as the median of the pixel intensities in the area surrounding the spot, and the feature (spot) median as the median of the pixel intensities in the area inside the spot. The spot intensity may be then calculated by subtracting the background median value from the feature median value and used as the expression value for the corresponding gene. Clicking on the "Help with data" button in the TRAM "Home" window will allow the user to be interactively assisted in the preparation of text files of the required format, including calculation of the spot intensity by subtracting the background value from the spot value (see below for details).

Third column [optional]: Platform code (e.g., GPL96),
it is needed only in the first row.

IMPORTANT - To interpret the identifiers in your gene expression data file as ID for the relative Platform, you must previously have set up the corresponding Platform as explained in section 2.2 of this Guide. Some Platforms are pre-setup as described in the same section.

Example:

[Column Headers are not required]

[Probe ID] [Value]   [Platform]     
1007_s_at  6.38      GPL96  
1053_at    6.65
117_at     6.48
...        ...

Note: If the first expression value is not in the first row due to the presence of some header lines, please use the very first row anyway in your file to indicate the Platform code, making sure that you are writing it in the third column. If you have only one column in the first row, please press the tabulator key twice then write the Platform code.
Do not insert blank spaces or other characters at the end of the text in a column.

Management of absent/negative/zero values

Probes whose expression value is absent (i.e. empty, not available) will not be further considered by TRAM for the construction and analysis of the maps, assuming that an expression level has not been measured.

Sample expression values equal to or lower than "0" (≤0) will be thresholded to 95% of the minimum positive value present in that sample, in order to obtain meaningful numbers when dividing "Samples Pool A" values by "Sample Pool B" values.
Assuming that in these cases an expression level is too low to be detected under the used experimental conditions, this transformation still allows to obtain a ratio between values in the pool A and values in the pool B, which is useful to highlight differential gene expression.

Expression values assigned to unmapped genes (without known genome coordinates) will be normalized and it will be possible to browse through them in the "Values_A_B_All" layout, but they will not be used in the construction and analysis of the maps.

From the "Values_A_B" layout, the button "A/B (unmapped)" option brings to the layout "Values_A_B_All".

IMPORTANT - To interpret the identifiers in your gene expression data file as  ID for the relative Platform, you must have previously set up the corresponding Platform as explained in section 2.2 of this Guide. Some Platforms are pre-setup as described in the same section.

Clicking on the "Help with data" button in the TRAM "Home" window will allow the user to be interactively assisted in the preparation of text files of the required format. The user will be guided to import his data file and to select the two columns containing gene identifiers and expression values. A Platform code must be indicated if the gene/probe identifiers are not the standard gene symbols and they need to be converted into gene symbols using Platform data loaded in TRAM (see section 2.2).
Finally, the software asks the user to save the data, generating a text file suitable to be imported in TRAM. The user may choose the desired file name.
If the user plans to import expression data files using "Batch Import" mode of feeding the database, the text files must be saved with a name of the type A1.txt, A2.txt ... (in the TRAM folder "Batch_Import_A") or B1.txt, B2.txt ... (in the TRAM folder "Batch_Import_B").
Batch processing of a sample series: it is possible to prepare in batch mode a series of sample data files related to the same work, obtained with the same Platform and formatted in an identical way.
Put all the files to be processed in the "Series" folder located in the "TRAM" folder, naming them S1.txt, S2.txt and so on.
From the TRAM "Home", click on the "Help with data" button and then on the Data file batch processing button.
Locate the "ID" and "Value" columns when requested for the first sample.
Insert the name of the Platform when requested.
TRAM will then automatically process all the files located in the "Series" folder using the same criteria, generating a series of uniformly processed data files with names such as P1.txt, P2.txt and so on. These files may be transferred in the "Batch_Import_A" or "Batch_Import_B" folders to be automatically imported by TRAM using the "Batch mode" import buttons in the TRAM "Home", after renaming them with names such as A1.txt, A2.txt ... or B1.txt, B2.txt ..., respectively.

Clicking on the "Special" button in the TRAM "Home" window will allow the user to automatically perform batch data import of large pools of samples for both A and B Pools in succession, provided that the expression data files have been prepared in the required format (possibly using the "Help with data" utility) and have been saved in the TRAM folder "Batch_Import_A" (with names such as A1.txt, A2.txt ...) and in the TRAM folder "Batch_Import_B" (with names such as B1.txt, B2.txt).

Clicking on the "Export" button in the TRAM "Home" window will assist the user in the export of the (raw or normalized) imported data.

The following instructions are also available as a guided procedure within the software in the appropriate "Set Up" area ("Set up - Part 2 - Gene Identifiers conversion tables").

NOTE: TRAM will try to convert the Gene identifiers present in your expression data files to Gene Symbols/Gene names until a positive match is found, with the following priority order:

1) if you set up the "Custom" table as described in section 2.2 of the chapter "Set up", the "Custom" Table will be first searched to match Gene identifiers in your data to the corresponding Gene Symbols/Gene names, overriding all other conversions;

2) if no match has been found, then the "Genes" table (mandatorily setup as described in section 1.2 of the chapter "Set up") will be searched to directly interpret Gene identifiers in your data as Gene Symbols/Gene names;

3) if you write a Platform ID code (e.g., GPL... for a GEO Platform) in (at least) the first line of the third column of your data (formatted as described in the section 3 of this Guide), a corresponding list of gene Identifiers (often a series of progressive numbers) is expected in your data  and each will be converted in the corresponding Gene Symbol/Gene name, if you previously set up the table for the relative platform as described in section 2.3 of the chapter "Set up";
for example:

1007_s_at  6.38      GPL96  
1053_at    6.65
117_at     6.48
...        ...

[Note - If the first expression value is not in the first row due to the presence of some header lines, please use the very first row anyway in your file to indicate the Platform code, making sure that you are writing it in the third column. If you have only one column in the first row, please press the tabulator key twice then write the Platform code.
Do not insert blank spaces or other characters at the end of the text in a column].

4) if you write the word GeneID in the first line of the third column of your data (formatted as described in the section 3 of this Guide), an "Entrez Gene" Identifier (a progressive number) is expected in your data and it will be converted in the corresponding Gene Symbol/Gene name searching in the "Genes" Table (this has been mandatorily setup as described in section 1.2 of the chapter "Set up");

for example:

780        6.38      GeneID 
5982       6.65
3310       6.48
...        ...

[Note - If the first expression value is not in the first row due to the presence of some header lines, please use the very first row anyway in your file to indicate the "GeneID" option, making sure that you are writing it in the third column. If you have only one column in the first row, please press the tabulator key twice then write the "GeneID" word.
Do not insert blank spaces or other characters at the end of the text in a column].

5) if no match has still been found, the "Unigene" Table will be searched to directly interpret Gene identifiers in your data as GenBank Accession Numbers (if you set up this table as described in section 2.1 of the chapter "Set up");

6) if no match has still been found, the "Unigene" Table will then be searched to directly interpret Gene identifiers in your data as UniGene Cluster identifiers (if you set up this table as described in section 2.1 of the chapter "Set up").

When a match is found, this will prevent the software from searching for a symbol in the next tables.
We suggest to use recently released data for each table to be imported in the TRAM software.

If you have a list of Gene Symbols as probe identifiers, with the corresponding expression values, you can directly go to "Home" and start to Import expression data, otherwise go to the "Set Up" chapter, Part 2.

In the "Main" ("Home") window there are two button series designed for rapidly begin the import processes.

Don't worry if the progress bars seem to advance too slow; this sometimes doesn't reflect the actual progress of the task.

The first import button series ("Import A" and "Import B") imports one expression data file into "Values_A" table or "Values_B" TRAM database table, respectively.

At the start of the import process, the user must choose whether to retain or delete all previously imported data. Clicking on "No" in the first dialog box will let the user add to the previously imported data one or more other datasets. The user may subsequently select any sample subset which must be subjected to analysis.

The second dialog box asks for the selection of the file containing the data table.

All data imported from a file will be labeled by the software with a progressive order number (Sample_ID) to easily track (or delete from the analyzed set by the "Remove Sample" function) all data belonging to a specific set.
In addition, "Samples_A" and "Samples_B" tables allow the visualization and annotation of the list of imported samples and to visualize summary data for each sample.
The "Go" buttons open a window in your default browser displaying the entry for Platform,  Series,  Sample, Dataset and PubMed record if you annotated (at any time) the corresponding fields with codes for GPL, GSE, GSM, GDS and PMID, respectively.
At the start of an analysis, the user can also select which samples are to be excluded or included (default) from the current analysis, without removing them from the TRAM database; alternatively the user may even remove any samples from the database.
Please note that changing the set of samples to be analyzed causes restarting of normalization (see below), which may take several minutes or hours, depending on the number of loaded samples.

The software will ask for the import of another set at the end of the process.

As final step, the user can check the results of the import process.

When requested by the software, click on the blue "Continue" button at the top and on the right of the program window, to ensure a correct functioning of the software.

The second import button series ("Batch mode" buttons) works in the same way but it is optimized to perform a batch, non user-supervised import.
By clicking on "Batch mode" (A or B) all files (formatted as just described for the manual import) contained in the
"Batch Import_A" folder or in the
"Batch_Import_B" folder, respectively, will be imported.
In these folders the file must be named as
A1.txt, A2.txt, ... and
B1.txt, B2.txt, ..., respectively (without interruption in the series of progressive numbers).

In the case that you would like to perform a batch import maintaining the previously imported dataset, the first file name should be numbered as the first not used Sample_ID number (e.g. if the last imported set has Sample_ID = 5, the first file must be A6) and that number will correspond to the Sample_ID of that dataset. The software will alert you about this. You may check for the currently used Sample_TRAM_IDs by clicking on the "Samples A" and "Samples B" buttons, respectively, in the TRAM Home.

Clicking on the "Special" button in the TRAM "Home" window will allow the user to automatically perform batch expression data import of large pools of samples in succession for both A and B Pools. Batch import may be followed automatically by data analysis using the "Batch Import + Analysis" button in the "Special" section.

After the import process, expression data are visualized in the "Values_A" and "Values_B" tables, that you be displayed by clicking on the buttons A and B, respectively, from TRAM "Home" (opening window).
These are the data fields for the "Values" tables:

Identifier      (the original probe identifier in your data)
Intensity value (the original numerical expression value)
Sample_ID       (A1, A2... or B1, B2...).
Platform        (filled if you indicated a Platform code "GPL..."
                   in your expression data file.
Exclude         (state of inclusion/exclusion of the data for the analysis)
Gene_name       (Gene Symbol/Gene name following conversion of Identifiers)
Chr             (chromosome name)
txStart         (start position of the gene transcript on the chromosome)
txEnd           (start position of the gene transcript on the chromosome)

IMPORTANT - The conversion of gene or probe identifiers to Gene Symbols/Gene names is performed during expression data import. To keep the database indexed and fast, variations of set up of the software are not dynamically reflected in variations of gene assignment to the probe identifiers. Therefore, changing of any table related to the "Set Up" chapter ("Chromosomes", "Genes", "EST_Clusters" and "UniGene_ID", " Platforms ID", "Custom ID") should be followed by reimport and reanalysis of the expression data to make the changes effective. An exception to this rule is the set up of new Platforms or new Custom ID sets that have to be applied only to new, subsequently loaded samples and not to previously imported samples. In this case reimport of all samples is not needed.
Clicking on the "Special" button in the TRAM "Home" window will allow the user to automatically perform batch data import of large pools of samples.

Interpretation and Normalization of the imported data

The user provides TRAM with an "Intensity value" for each spot, which is intended to be the pre-processed intensity value, i.e. the numerical value assigned to the spot as it has been processed by the software of the specific experimental platform used (e.g. following background subtraction for a microarray spot).
To allow comparison of gene expression data obtained by different biological samples and/or by different experimental platform, TRAM is able to perform some useful data normalization methods.

The normalization type may be changed by a pop-up Menu from the "Values" or "Samples" data tables.

Intra-sample (intra-array) normalization works within each distinct sample, while inter-sample (inter-array) normalization is simultaneously applied to the desired sample sets.
You may select different combinations between these types of normalization.

Please note that the normalization process may require several hours for databases in which tens of arrays were imported.
Clicking on the "Special" button in the TRAM "Home" window will allow the user to automatically  perform normalization changes of large pools of samples.

The normalization may also be set starting an analysis, so that normalization and analysis will be performed in chain without the user's intervention.

Intra-sample normalization

These methods rescale values within each data set using a standard internal reference for each sample.

None
No Intra-sample normalization is performed.

Mean [DEFAULT AFTER INSTALLATION]
Each value is expressed as the percentage of the corresponding sample mean value. This is equivalent to the classic "global normalization" in the microarray data analysis.

Median
Each value is expressed as the percentage of the corresponding sample median value. This is equivalent to the classic "global normalization" in the microarray data analysis.

Max
Each value is expressed as the percentage of the corresponding sample maximum value. This is equivalent to the classic "scale normalization" in the microarray data analysis.

Inter-sample normalization

These methods rescale values within each sample set.

None
No Inter-sample normalization is performed.

Quantile
For the implementation in the database structure at the core of TRAM, each intra-sample normalized value is given a rank following sample data sorting in ascending order, then the mean value for all the values with the same rank across all samples is calculated. This mean value is assigned as the expression value to each gene with the same rank in each sample. An original variant of this method implemented in TRAM is described below. (Bolstad et al., 2003).

Scaled_Q (Scaled Quantile) [DEFAULT AFTER INSTALLATION]
Derived from Quantile method, except that the rank for each array is rescaled according to the array with the maximum number of probes. This original method allows to compensate when comparing array with highly different number of probes because in this way the highest values for arrays with low number of probes are given ranks comparable to those assigned to arrays with high number of probes (see the article).

DATA SUMMARY - Values_A_B Layout

The summary of gene expression values, under the current mode of normalization, may be viewed in the "Values_A_B" layout.
This is an indexed database table summarizing all data points available in the sample pool for each gene.
Along with the Mean value and the Standard Deviation (SD) value, the SD value is also shown as a percentage of the expression value.
The "Mean" value of the data points available for each locus is considered the expression value for the respective gene and it is used in the subsequent analysis.
The number of "Data Points" from which the summary data are obtained is also displayed.

The yellow button "A/B (unmapped)" brings to the layout "Values_A_B_All", which includes also unmapped loci that are not listed in the "Values_A_B" table used for the creation and analysis of the transcriptome maps.

Clicking on the "Export" button the data for the genes listed in "Values_A_B" table may be exported as a tabulated text file.
The file contains by default the following columns, from left to right:
01) Gene_name
02) Chromosome name
03) Chromosome Identifier (progressive number)
04) Gene mean expression value for pool A samples.
05) Gene mean expression value for pool B samples.
06) Ratio between gene mean expression value from pool A
    samples and from pool B samples (A/B ratio).


4 Analyzing data                                  (Back to Index)

Click on the "Chromosomal Segments" button in the TRAM "Home" (TRAM main window).

The software will generate a graphical map of the transcriptome showing a vertical line representing each chromosome. An expression value is associated to each segment of the line, whose size is determined by a window (in bp) set by the user. This value is the mean for all available expression data related to the genes included in each segment.

Information about "Location" is derived from "NCBI Gene" imported data and in the "Map" mode is obtained for the first gene listed in each chromosomal segment.

In the "Map" mode, results are always generated calculating both types of analysis (the one based on all genes in the genome and the one based on the genes located in the same chromosome the segment belongs to). You are required to select one type of analysis ("genome" or "chromosome") in order to be directed, at the end of process, to the results layout you selected, but the results for the other layout are also available.
This is because TRAM spends much of the time during "Map" analysis in creating chromosomal segments, so it is convenient to calculate both statistics when segments are created.

SETTINGS

The available settings for this analysis are:

Window: defines the length for a segment.
If the coordinates of a gene span the window boundaries, the gene is included in each window in which a part of it lies.
Each segment on the map shows only those genes having an available expression value in the corresponding sample or pool of samples.

Sliding window shift: defines the overlapping region between a segment and the next one.
A shift equal to zero results into non overlapped segments.
For example, if the window is 1.000.000 bp and the shift equals 200.000 bp, the successive segments will be created with coordinates:
      1 - 1.000.000 bp
200.000 - 1.200.000 bp
400.000 - 1.400.000 bp, and so on.

This function could be useful to increase the sensitivity of the search for over/under-expressed segments.

Percent (segment): defines the threshold required to consider a segment as "Over- (or Under-) expressed" (i.e. to be marked in red or blue in the expression bar).

The segment which shows mean expression value (calculated as the mean of all known genes included in it) within the highest (n) percent of Values or within the lowest (n) percent of Values, where n=Factor (segment), will be highlighted (in red or blue colour, respectively), thus displaying genomic regions globally over- or under-expressed, respectively, with respect to the desired threshold.

Percent (gene): defines the threshold expression value to consider a gene as "Over- (or Under-) expressed" (i.e. to be marked in red or blue in the segment gene list).

The gene which shows mean expression value within the highest (n) percent of Values or within the lowest (n) percent of Values, where n=Percent (gene), will be highlighted, being listed in red (over-expressed) or blue (under-expressed) colour font, respectively.

The number of over/under-expressed genes in the segment is calculated with respect to the Percent (gene).
Using two different parameters for segment and genes allows the user to perform a more refined analysis.

Number of genes in the window: defines the minimum number of over/under-expressed genes required to mark the segment with the tag "Over" (or "Under").

The Over-Expressed segment listing a number of Over-Expressed genes equal to or greater than the "Number of genes in the window" will be marked as "Over" in the "Map" layouts.

The Under-Expressed segment listing a number of Under-Expressed genes equal to or greater than the "Number of genes in window" will be marked as "Under" in the "Map" layouts.


RESULTS

The results of the analysis are displayed within 30-90 minutes, depending on the number of arrays analyzed. Changing the data normalization type during the analysis requires additional time for the task to be completed.

The results of the analysis are displayed in the "Chromosomal Segments" layouts (i.e., "Map" layouts).
Each chromosomal segment is actually a record of the database. You can find and sort segments using desired criteria.

The "P" field displays the p-value resulting from the hypergeometric distribution calculation for the "Over/Under"-expressed segments. This is the statistical significance, i.e. the probability that the result (presence of n over/under-expressed genes within the same segment) could have been obtained by chance.
Due to the high number of segments in a genome, the "P" value needs to be corrected to avoid False Discovery Rate (FDR). The "Q" field displays the p-value corrected for FDR.
"P" and "Q" values are displayed only for the segments fulfilling criteria to be tagged as over/under-expressed. If Q≤0.05, the over/under-expression is considered to be statistically significant.
For details and references about the statistical analysis, see the article describing "TRAM".

The user may also produce a graphical output showing the series of chromosome transcriptome maps aligned horizontally and may choose to select representation of specific chromosomes or set of chromosomes.
In addition, specific buttons help retrieve online database entries for the desired genes.

In the "Map" layouts based on all gene values, segments that result to be significantly over/under-expressed only in this type of analysis, but not in the corresponding one based on pertinent chromosome values, will be marked by a "G" and the intensity bar will be highlighted in yellow. The button "Show only"->"Genome Specific" will retrieve only these "G" segments.
In the "Map" layouts based on chromosome-specific values, segments that result to be significantly over/under-expressed only in this type of analysis, but not in the corresponding one based on all gene values, will be marked by a "C" and the intensity bar will be highlighted in yellow. The button "Show only"->"Chromos. Specific" will retrieve only these "C" segments.

Clicking on the "Export Results Data" button allows the export of the results as a tabulated text file that will be saved in the "Results" folder present in the main "TRAM" directory.
The file contains the following columns, from left to right:
01) Chromosome name
02) Chromosomal location
03) Segment Start genomic position
04) Segment End genomic position
05) Segment expression value
06) Label of segment Over/Under-expression ("Over", "Under")
07) P value
08) Q value
09) List of genes (symbols) included in the segment
10) Number of Over-expressed genes in the segment
11) Number of Under-expressed genes in the segment
12) Total number of genes in the segment

A second file with the label "Set" in the file name is generated, containing the summary of the analysis settings, which are also displayed at the top in all TRAM results layout.

The user can also export result data in different formats (e.g., Excel) using the "Export Records..." command from the "File" Menu.

4.2 Searching for clusters of neighbouring over/under-expressed genes
(Back to Index)

In the "Cluster" mode, the software will search for sets of contiguous/neighbouring genes all expressed beyond a defined "n" threshold, i.e. with expression values higher than the (100 - "n") percentile or lower than the "n" percentile.

In this mode, results are centered on individual differentially expressed loci and they are complementary and more sensitive compared to the "Map" mode of analysis, which requires the definition of an arbitrary window length within which genes must be comprised.

SETTINGS

Click on the "Gene Clusters" button in the TRAM "Home" (TRAM main window).

The available settings for this analysis are:

Percent (gene):  defines the thresholds required to consider a gene as "Over- (or Under-) expressed" (i.e. to be marked in red or blue in the expression bar).

The genes showing mean expression value within the highest (n) percent of Values or within the lowest (n) percent of Values, where n=Percent (gene), will be highlighted, being listed in red (over-expressed) or blue (under-expressed) colour font, respectively,

Over-Expressed gene
(marked as "CLUST-O" in the results layout)

Under-Expressed gene
(marked as "CLUST-U" in the results layout)

Gap: defines the maximum number of non "Over" or "Under"-expressed genes allowed to be localized between two "Over" or "Under"-expressed genes in a cluster.
Setting a gap equal to 1 means that two over- (under-) expressed genes will be included in the "Cluster" even when they are separated along the chromosome by a gene not fulfilling the conditions to be considered over/under-expressed. For example, a cluster composed by the over-expressed genes A, B, and C, could contain no more than 2 non-over-expressed genes: one between genes A and B and the other between genes B and C.
Genes with this feature will be marked as "GAP" in the results layouts.
If Gap=0, only contiguous genes will be considered to be in cluster.
Genes with no expression data in the analyzed sample set will not be considered as "GAP" and will instead be marked "EMPTY" in the results layouts. They are visualized, but they are ignored by the searching for cluster process.

Gene Type: the software will construct a scheme of the linear succession of genes present in the table "Genes", filled during the set up process.
The user can set TRAM to use any of the following, while constructing the linear map of genes:

SAMPLE NUMBER: defines the minimum number of Samples for which an expression value must be available for a gene in order to include that gene in the analysis.

The Results of the "Cluster" analysis are typically displayed within a few minutes.

Changing the data normalization type during the analysis takes additional time for the task to be completed.

Clicking on the "Export Results Data" button will export the results as a tabulated text file that will be saved in the "Results" folder present in the main "TRAM" directory.
The file contains the following columns, from left to right:
01) Cluster ID (a unique number used as cluster identifier)
02) Type of Cluster
    (CLUST-O: over-, CLUST-U: under-expressed)
03) Count of over/under-expressed genes in the Cluster
04) Length (bp) of the region covered by the cluster
05) Chromosome name
06) Chromosomal location
07) Gene symbol/name
08) Gene Start genomic position
09) Gene End genomic position
10) Gene expression value (mean among all pool samples)
11) Sample Count (number of Samples with an Expression value
    for that Gene)
    (two values in the A/B analysis, for A and B, respectively)
13) Label of gene Over/Under-expression ("Over", "Under")
14) Number of individual Data Points processed for each gene
15) P value
16) Q value
17) Gene description

A second file with the label "Set" in the file name is generated containing the summary of the analysis settings, which are also displayed at the top in all TRAM results layout.

The user can also export result data in different formats (e.g., Excel) using the "Export Records..." command from the "File" Menu.

(Back to Index)

Since 1.2 version, a copy of TRAM itself (empty) may be used as a "TRAM Results Viewer" (TRV) in order to regenerate a grahical view of the results obtained by a copy of TRAM filled with species-specific data Tables and with Results generated by the analysis allowed by TRAM.
1. Choose "! Export Main Tables" from the "Script" Menu of the copy of TRAM where the analyses were executed. This will export all main Tables (all fields) from TRAM in .fmp12 format into the "Results" folder of TRAM
("Settings", "Chromosomes", "Genes", "Samples", "Values_A_B", "Map" and "Cluster" Results Tables).
Platforms, UniGene/ESTs and sample "Values" Tables data will not be exported.
2. Copy the resulting 16 Tables in the "Results" folder of a distinct, empty copy of TRAM 1.2 itself (TRV).
3. Choose "! Import Main Tables" from the "Script" Menu of TRV.
This will import the Tables in TRV. The source "Table" files can then be deleted from the TRV "Results" folder.
TRV is intended to allow the distribution of a set of data and results from a particular TRAM analysis without distributing the original whole file (which can be of the size of ~25 Gb when approximately 700 samples are analyzed).
Due to the lack of Platform data, as well as of individual sample "Values" data, in TRAM used as a TRV some types of analysis cannot be run (adding / deleting / including / excluding Samples) and some functions and buttons cannot work (inspecting individual sample Values, inspecting Platform / UniGene / ESTs tables).

A set of records referring to the same subject type (e.g., the "Genes" table).

One set of fields which represent one entry (i.e. containing all requested data for a subject, e.g. a gene probe).
The record browser is a small book icon at the top left of the window. You may also browse the records faster using the cursor at the right of the small book icon.

A particular graphical organization of the field of a table.
A table can be visualized in more than one layout.
A layout may display fields from a table or its related fields from other tables.
A file may show data within different layouts.
Visualization of a field is independent from the storage of the contained data.

Browsing among the layouts can be made by clicking on the "Layout:" pop-up Menu at the upper left corner.

You may browse the database by clicking on the small book pages at the top left of the window, or
using the cursor at the right of the small book icon or by
entering a record number and clicking on the "Return" key.
The following information is constantly displayed in the top bar of the  window (if not, select "Status Toolbar" from the "View" Menu):
Records: total number of Records in the table.
Found: total number of the subset of Records currently selected. Clicking on the green circular button will retrieve the complementary subset of currently omitted records.
Sorted: sorting status of the Records (Sorted/Unsorted).

The FileMaker Pro-based database may be used basically in these "modes":
"Browse", "Find", and "Preview".
Switching among different modes can be done from the "View" Menu or from the pop-up Menu bar at the bottom left of the window.

It allows entry, view, browse, sort, and manipulation of data.
It may be selected from:
the "View" menu or
the mode pop-up Menu bar at the bottom left of the window.

In the "Browse" mode, the record sets can be browsed by clicking on the small book icon (with the arrows to move "back" and "forward") in the upper left corner.

Browsing among the tables can be done by clicking on the "Layout" pop-up Menu at the upper left corner.

(Back to Index)
An alternative mode to use the database.
It allows searching for specific content in the database fields, using any different combination of criteria
(see the "Search mode" section below for more details).
It may be selected from:
the "View" menu or
the mode pop-up Menu bar at the bottom left of the window.

The user can fill in a blank form allowing to search in specific fields.

In the "Find" mode, the small book icon in the upper left corner represents different "requests" that are made for searching the database.

In FileMaker Pro "Find" mode, the "AND" - "OR" - "NOT" operators may be implemented in this way:

"AND" by filling criteria in different fields
      located in the same "Request",

"OR"  by generating additional requests
      (from "Requests" Menu) in the same query,

"NOT" by generating additional requests
      (from "Requests" Menu) and clicking on the "Omit"
      button (located in the window top bar).

The "Operators" pop-up Menu appears by clicking on a field while pressing the "ctrl" key, allowing query of:
exact matches, duplicate values, ranges, wild cards and more.

Click on the "Perform Find" button at the top of the window to start the query.

The result of the search is the subset of the entries matching the set search criteria.

(Back to Index)
An alternative way to use the database.
It visualizes a print preview of the found records.
It may be selected from:
the "View" menu
or the pop-up Menu bar at the bottom left of the window.

In the "Preview" mode, the user can obtain a print preview of the data in the current table.
Browsing among the tables can be done by clicking on the "Layout:" pop-up Menu at the upper left corner.

About FileMaker Pro Runtime...
Information about FileMaker Pro Runtime at the core of the software.

Preferences...
Standard preferences panel; cache memory size can be set up to 256 Mb.

Hide TRAM
Hiding all TRAM windows.

Quit TRAM
Closing the program.

File Options...
It is possible to set only the "Spelling" options.

Change Password...
There is no default password set.

Page setup...
Standard page set up command.

Print...
Standard print command.
The appearance will match the layout currently displayed on the screen.

Import Records
This is the general "Import" function of FileMaker Pro.

Export Records...

Save a Copy as...

6.5 "Records" Menu                                 
(Back to Index)

New Record
Create a new empty record in the database.
The new Record will be the latest of the current record set.

Duplicate Record
Duplicate the current record in the database.
The new Record will be the latest of the current record set.

Delete Record...
Delete the current record in the database.

Delete Found Records...
Delete all currently found records in the database.

Go to Record
Move to the selected record by number, previous or next.

Show All Records
Show all the records in the database.

Show Omitted Only
Show all the records in the database not included in the current "found" set.

Omit Record
Remove the selected record out of the current found set, without deleting it.

Omit Multiple...
Remove more than a record, selected by numbers, out of the current found set, without deleting them.

Modify Last Find
Return to the last performed search in order to edit it.

Saved Finds
Save a set of search criteria.

Sort Records...
Sort the current record set according to desired criteria.

Unsort
Display the current record set according to the order of creation of each record.

Replace Field Contents
Replace the value of a field in all Found Records with the value specified in the current record, or by calculation.

Relookup Field Contents...
This command executes a relook up of the value of a field by reading the matched value in a related table (the relationship has been established during database development using a "key" field).

Revert Record...
Restore the value of a field, discarding any change, before clicking out of that field.

6.6 "Scripts" Menu                                  
(Back to Index) This opens the "About" window containing information about the TRAM software.

Guide
The page with the user Guide of the TRAM software (this Guide).

6.7 "Help" Menu                                    
(Back to Index)

Search
Search a "Help" system for the general commands.


TROUBLESHOOTING                                                         (Back to Index)

Sometimes, power failure, hardware problems, or other factors can damage a FileMaker Pro database file.
When the runtime application discovers a damaged file, a dialog box appears, prompting the user to contact the creator.
Even if the dialog box does not appear, files can exhibit erratic behaviour.
If you have FileMaker Pro or FileMaker Pro Advanced installed you can recover it using the "Recover" command.
Otherwise, to recover a damaged file:
- On Mac OS X machines, press Command + Option (cmd-alt) while double-clicking the runtime application icon. Hold the keys down until you see the "Open Damaged File" dialog box.
- On Windows machines, press Ctrl+Shift while double-clicking the runtime application icon. Hold the keys down until you see the Open Damaged File dialog box.
During the recovery process, the runtime application:
1. Creates a new file;
3. Gives the repaired file the original name.


TECHNICAL NOTES                                                
(Back to Index)

The minimum software requirements are:
Mac OS X 10.6, OS X Lion 10.7, OS X Mountain Lion 10.8;
Windows XP Professional, Home Edition (Service Pack 3);
Windows Vista Ultimate, Business, Home Premium (Service Pack 2);
Windows 7 Ultimate, Professional, Home Premium;
Windows 8 Standard and Pro edition.

Other specifications may be found here.

A connection to the Internet is required to display the software Guide and to download data for set up, but not to run the tool.

Please do not change the name of all files and folders of the TRAM software.

You may download multiple copies of TRAM and run them simultaneously, provided that each "TRAM" folder is located in a different directory.
Do not move the "TRAM" folder while the software is open.
Run the "TRAM" software from a local hard disk.
Do not run the software from a network drive.

If a TRAM analysis aborts unexpectedly, it is advisable to restart it in a fresh TRAM copy.

The scripts at the core of TRAM software are "FileMaker Pro" scripts.

TRAM 1.3 is composed of a 228 MB database engine ("TRAM.app") and a template ("TRAM.TMA") with 43 data tables, 134 relationships among them and 489 script definitions.
Following set up including NCBI UniGene and UCSC EST localization data, the size becomes about 5 GB  for human "TRAM.TMA" file.

Time required to import and process a typical microarray data file is about 10 minutes.
Typical execution time is 1-2 hours for a "Map" analysis and  5-10 minutes for a "Cluster" analysis, depending on the number of analyzed samples, which also heavily affects the time required to refresh data when the type of data normalization is changed.

Large file size and relative slowness of data processing are mainly due to systematic indexing of all data contained in TRAM, with the advantage of very fast data browsing, navigation and search at the end of data import and processing, which may be run in batch mode.


7.1 Known software limits
(Back to Index)

Due to FileMaker Pro limits:
maximum TRAM file size is 8 terabytes (1024 gigabytes);
text field can contain up to 1 billion characters;
numbers field can contains values from 10^-400 up to 10^400.

At present, TRAM requires an unambiguous mapping. Genes common to X and Y chromosomes (e.g., CSF2RA) are now mapped, but only on chromosome X. The double X-Y location remains indicated in the "Location" field of the "Genes" Table.

The limit of 25 chromosomes for a genome is declared only for the possibility to display synthetic maps with all chromosomes shown horizontally aligned; however, it does not apply to the data import, standard visualization mode and all data analysis.

7.2 Bug reports
(Back to Index)
Please report any suggestions, bugs or problems to:
Pierluigi Strippoli
pierluigi.strippoli@unibo.it


ACKNOWLEDGEMENTS                                        
(Back to Index)

Thanks to NCBI for the "Entrez" databases and to UCSC Genome Bioinformatics for the "UCSC Genome Browser".
Thanks to FMPexperts List and FMForum for suggestion and tips about FileMaker Pro.

The following 34 Platforms (commercially available) that have been used for the analysis of at least 2,000 GEO samples are already loaded as default in the pre set-up versions for human, 2017 (the number of sample available for each Platform has been updated up to November 08, 2017):

              Affymetrix Human Genome U133A Array

The following further 27 Platforms (Total=61) are also already loaded as default in the pre set-up versions for human, 2017 (the number of samples available for each Platform has been updated up to November 08, 2017). They have been used in any of the TRAM analyses published to date (May 2018) and they are listed below in numerical/alphabetical order:

              In situ oligonucleotide - non-commercial

              (Platform in atypical format, only Gene Symbols  
              present in "NCBI Gene" have been left in the
              TRAM "Platform" Table).