###############################################################################
# ABOUT
###############################################################################

This distribution contains all the code necessary to reproduce the
cutting scores in this manuscript:

    FragSeq: transcriptome-wide RNA structure probing using high-throughput
    sequencing.
    Jason G. Underwood, Andrew V. Uzilov, Sol Katzman, Courtney S. Onodera,
    Jacob E. Mainzer, David H. Mathews, Todd M. Lowe, Sofie R. Salama, David
    Haussler.
    Nature Methods [submitted 12 Aug 2010].

Future releases, patches, etc. of this code will be available here:

    http://users.soe.ucsc.edu/~auzilov/FragSeq/

The algorithm details are described in Supplementary Note 1 of the above paper,
and the design rationale in Supplementary Note 2.  Please read them before
trying to figure out how the code works.


###############################################################################
# SYSTEM REQUIREMENTS
###############################################################################

- Python 2.6.x or a more recent Python 2.x.x version.

- Lots of RAM (see "Known Bugs and Issues").

In theory, this code should be system-independent (however, see "Known Bugs
and Issues").  It was tested on CentOS (Linux) 5.5 and Mac OS X 10.6.4.


###############################################################################
# CONTACT INFO
###############################################################################

If you have questions, issues, bug reports, etc. regarding the code, please
contact:

    Andrew Uzilov
    auzilov@ucsc.edu


###############################################################################
# HOW TO REPRODUCE THE ANALYSIS IN THE PAPER
###############################################################################

First, download the mapped reads (.bed files) from either

    http://users.soe.ucsc.edu/~auzilov/FragSeq/

or from Gene Expression Omnibus (GEO)

    http://www.ncbi.nlm.nih.gov/geo/

They should be the same, but GEO is more likely to be persistent.  Use the GEO
accession number given in our paper.

You should obtain six BED-format files (2 cell types x 3 treatments), but only
the "nuclease" and "control" treatments are necessary.  The "PNK" treatment is
not used for computing cutting scores in the paper.

Make sure the following BED files are in this directory:

    bc02.bed
    bc05.bed
    bc07.bed
    bc08.bed

These are named after their barcode (bc) and the barcode info is listed in
Supplementary Table 1 in the paper.

Now, simply run the commands in "reproduceResults.bat".
On most shells (bash, zsh, tcsh, etc.) it is done like this:

    . reproduceResults.bat

That script will set up the necessary directories and run the FragSeq code
using the provided config files, which contain the algorithm settings we
used.  Also, read the script, which contains comments explaining what each
step does.  The config files contain detailed explanations of each setting.

The resulting data will be placed into the dirs:

    Output/undiff/
    Output/d5np/

which correspond to the two cell lines assayed.


###############################################################################
# ABOUT THE OUTPUT
###############################################################################

The files *.cutscores.ss.list contain the cutting scores.  Each line
corresponds to a site in the RNA, from 5' to 3'.  So the first line is the
native 5' end, and there are N+1 lines for a RNA with N bases.  "none"
denotes that either there were no more breaks in nuclease sample versus
control, or that the site was ignored (e.g. due to missing data or due to
being too close to native 5' or 3' end).

The files *.stats contain a lot of useful statistics about the RNA.  One
interesting statistic is the Multiple Mapping Index (MMI), which is a
summary of how uniquely mapped are the reads that were used to determine
cutting scores for a RNA.  A MMI of 1 means all reads were uniquely mapped.
Higher MMI means multiply mapped reads.  The MMI is the mean per-nuc
multiple mapping count of the reads; the multiple mapping count is taken
from the suffix of the reads in the input .bed files.

There are also wiggle files made and placed in the "Output/" dir, suitable
for upload to the UCSC Genome Browser.  There is a separate wiggle file for
each strand ("plus" vs "minus").  Wiggle files are made for raw counts of
ends ("rawends"), like in Fig. 2C in the paper, and cutting scores
("cutscores"), like in Fig. 2E in the paper.

Note that if you upload the wiggle files to the UCSC Genome Browser as custom
tracks, the values will be compressed, meaning the displayed values will be
off slightly from the values in the data.  To avoid this, convert the wiggle
data to bigWig format, making sure to use the "-unc" flag to "wigToBigWig" so
that compression is not done.  Complete instructions for converting wiggle
data to bigWig are here:

    http://genome.ucsc.edu/goldenPath/help/bigWig.html


###############################################################################
# USING THE CODE AND THE CONFIG FILES
###############################################################################

Run:

    python readsToStruct.py

to get a usage message.  Basically, you tell the program one or more config
files that specify how you actually want to run your analysis.  Multiple
config files are concatenated together, so you can "mix and match" several
modular pieces to try various ways of running the analysis.

The "%" symbol is a wildcard character that will be expanded to the name of
a RNA in the "rnas.bed" file.  So, if you see a "%" character, it means that
one file will be produced for EACH RNA in "rnas.bed" -- and the "%" will be
replaced with the name of that RNA.


###############################################################################
# KNOWN BUGS AND ISSUES
###############################################################################

These are all being fixed for the next release.

- The code uses **A LOT** of RAM (several gigabytes is normal for running
  just around 10 RNA sequences).

- There is not enough error-checking that config file parameters are sane.
  So, be careful with your config files.

- If you don't specify a "conf:outfile" in a config file, a Linux-specific
  hack kicks in.  This is the only non-portable part of the code.  The
  workaround is to always provide a "conf:outfile" setting.

- A lot of error messages are rather unforgiving and don't convey clearly
  what has gone wrong. 

- Some code comments aren't finished (denoted with "...").

- The output format is in wiggle format, not bigWig, which means custom
  tracks will be compressed on upload to the UCSC Genome Browser (see "About
  the Output" section).


###############################################################################
# CONVENTIONS IN CONFIG FILES AND CODE
###############################################################################

ss   = "nuclease" sample (as defined in the paper)
ssbg = "control" sample  (as defined in the paper)

"ss" doesn't mean it HAS to be a ssRNA-specific nuclease.  Any nuclease
will work just fine.  I just haven't renamed the variables to something
more generic yet.

