Changes

From Genome Analysis Wiki
Jump to navigationJump to search
4,716 bytes added ,  15:54, 31 January 2017
Line 1: Line 1: −
[[Category:Software Libraries]]
   
[[Category:C++]]
 
[[Category:C++]]
 
[[Category:libStatGen]]
 
[[Category:libStatGen]]
Line 17: Line 16:  
***Pileup – structured access to data by individual reference position
 
***Pileup – structured access to data by individual reference position
   −
= Where to Find It =
+
Can be used to create your own C++ programs.
libStatGen can be found at: [https://github.com/statgen/libStatGen https://github.com/statgen/libStatGen]
+
 
 +
Currently the repository is recommended for Unix/Linux users with access to the GNU C++ compiler.
 +
 
 +
 
 +
= Copyrights =
 +
'''If you use this software, please e-mail me, Mary Kate Wing, at mktrost@umich.edu'''
 +
 
 +
Here are links to the copyrights for our code and some of the utilities it uses:
 +
*[https://github.com/statgen/libStatGen/blob/master/general/COPYING GNU GENERAL PUBLIC LICENSE] and [https://github.com/statgen/libStatGen/blob/master/general/LICENSE.txt Our Copyright Note]
 +
*[https://github.com/statgen/libStatGen/blob/master/general/LICENSE.twister Copyright for MERSENNE TWISTER (used in Random.cpp)]
 +
*[https://github.com/statgen/libStatGen/blob/master/samtools/COPYING Samtools Copyright (MIT License)]
 +
Copies of these can be found in our library under libStatGen/copyrights/.
 +
 
 +
= Join in libStatGen mailing list =
 +
 
 +
Please join in the [http://groups.google.com/group/libStatGen libStatGen Google Group] to ask / discuss / comment about this library.
 +
 
 +
 
 +
= Troubleshooting =
 +
If you are having trouble compiling any of the versions, check [[libStatGen Troubleshooting]] for help.  If that does not solve your problem, email me for support.
   −
You can both browse and download the library at that address.
     −
This is also a git repository.  You can create your own git clone from this location:
+
= Where to Find It =
git clone https://github.com/statgen/libStatGen.git
  −
or
  −
git clone git://github.com/statgen/libStatGen.git
     −
Either of these commands create a directory called <code>libStatGen</code> in the current directory.
+
{{ToolGitRepo|repoName=libStatGen|libStatGen=true|libBaseName=libStatGen}}
   −
If you decide to use git, but need a refresher, see [[How To Use Git]] or [https://statgen.sph.umich.edu/wiki/How_To_Use_Git Notes on how to use git] (if you have access)
+
== Releases ==
 +
Released Versions are documented at [[libStatGen Download]]
    
= What has changed =
 
= What has changed =
 
The <code>pipeline</code> and <code>statgen</code> repositories have been deprecated, so please update to our new framework.
 
The <code>pipeline</code> and <code>statgen</code> repositories have been deprecated, so please update to our new framework.
   −
libStatGen is the new git repository for our library code.   
+
<code>libStatGen</code> is the new git repository for our library code.   
    
There are now separate repositories for specific tools/groups of tools, allowing us to track everything separately so it is easier to follow changes that impact a specific tool or the library in general.
 
There are now separate repositories for specific tools/groups of tools, allowing us to track everything separately so it is easier to follow changes that impact a specific tool or the library in general.
Line 40: Line 55:     
= Library Documentation =
 
= Library Documentation =
Latest Doxygen documentation: <span style="color:#B22222">Coming Soon</span>
+
Latest Doxygen documentation:
 +
<!-- <a href="http://csg.sph.umich.edu//abecasis/GOLD/ -->
 +
<!-- [http://www.sph.umich.edu/csg/mktrost/doxygen/current/ Current Library Documentation in Doxygen] -->
 +
[http://csg.sph.umich.edu//mktrost/doxygen/current/ Current Library Documentation in Doxygen]
   −
Additional documentation: <span style="color:#B22222">Currently outdated, but updates will be coming soon</span>
+
Additional documentation:  
 
* [[libStatGen: general]] - General classes for file processing and performing common tasks (used by most other libraries).
 
* [[libStatGen: general]] - General classes for file processing and performing common tasks (used by most other libraries).
 
* [[libStatGen: BAM]] - Classes specific for reading/writing/analyzing SAM/BAM files.
 
* [[libStatGen: BAM]] - Classes specific for reading/writing/analyzing SAM/BAM files.
 
* [[libStatGen: GLF]] - Classes specific for reading/writing/analyzing GLF files.
 
* [[libStatGen: GLF]] - Classes specific for reading/writing/analyzing GLF files.
 
* [[libStatGen: FASTQ]] - Classes specific for reading/writing/analyzing FastQ files.
 
* [[libStatGen: FASTQ]] - Classes specific for reading/writing/analyzing FastQ files.
 +
* [[libStatGen: ASP]] - Classes specific for reading/writing/analyzing ASP files.
 +
* [[libStatGen: VCF]] - Classes specific for reading/writing/analyzing VCF files.
    
= Using the Library =
 
= Using the Library =
 +
== Dependencies ==
 +
* This software requires the following to be installed:
 +
** g++
 +
** development version of zlib (zlib1g-dev on ubuntu)
 +
* Compiles on Linux/Unix
 +
 
== Building the Library ==
 
== Building the Library ==
   Line 66: Line 92:  
</pre>
 
</pre>
   −
When you just type make, it will by default to make opt.
+
When you just type make, it will by default to make opt (optimized).
    
Make all indicates opt, debug, and profile.
 
Make all indicates opt, debug, and profile.
   −
opt creates libStatGen.a, debug creates libStatGen_debug.a, profile creates libStatGen_profile.a
+
opt creates <code>libStatGen.a</code>, debug creates <code>libStatGen_debug.a</code>, profile creates <code>libStatGen_profile.a</code>
   −
These libraries are created in the top level libStatGen directory and can then be linked to appropriately for optimized, debugging, or profiling builds.
+
These libraries are created in the top level libStatGen directory and can then be linked to appropriately for building tools as optimized, debugging, and/or profiling.
    
== Navigating the Library Subdirectories ==
 
== Navigating the Library Subdirectories ==
Line 96: Line 122:     
== Using the Library in Your Own Program ==
 
== Using the Library in Your Own Program ==
<span style="color:#B22222">Coming Soon</span>
     −
''' Below are the outdated instructions for <code>statgen</code>
+
=== Starting from a Sample Program (Recommended) ===
 +
[https://github.com/statgen/SampleProgram https://github.com/statgen/SampleProgram] is a simple program demonstrating how to write a tool that uses libStatGen and can be used as a starting point for your tool. 
 +
 
 +
SampleProgram has 4 subdirectories:
 +
* copyrights - contains the copyright information, add your own copyrights as necessary
 +
* obj - this directory is where the object files are placed when the code is compiled (with a subdirectory for debug and profile objects)
 +
* src - this is where your own program code goes
 +
* test - this is where your test code goes.  Test code can be setup to run with <code>make test</code> to ensure the program works properly.
 +
 
 +
'''Using SampleProgram as a starting point for your tool:'''
 +
# Copy SampleProgram into a directory with your program name (it is the starting point for your own program).
 +
# Update ChangeLog, .gitignore, and README.txt as appropriate.
 +
# Add any necessary copyrights to the copyrights directory.
 +
#* No changes to Makefile should be necessary.
 +
# Update Makefile.inc
 +
## Update the VERSION as necessary.
 +
## Replace all occurrences of <code>SAMPLE_PROGRAM</code> with an all caps name for your program.
 +
##*  You can then use the <code>LIB_PATH_<your program name></code> environment variable to specify an alternate path to libStatGen specific for your program.  In most cases you will not need to do this.
 +
#* No other updates to Makefile.inc should be necessary.
 +
# Add your program (cpp & h files) to the <code>src</code> directory.
 +
# Update src/Makefile
 +
## Set EXE to your program executable (replacing sampleProgram)
 +
## Set TOOLBASE, SRCONLY, and HDRONLY as appropriate for specifying your program file names.
 +
## Set any of the other optional settings as specified in the sample makefile.
 +
#* No other changes should be necessary to src/Makefile.
 +
# Add your tests to the <code>test</code> directory.
 +
# Update test/Makefile as appropriate for specifying how to compile/run your tests.
 +
 
 +
 
 +
After compiling a <code>bin</code> directory is created in the top level directory.  Your executable goes in there.  If you build for <code>debug</code> and/or <code>profile</code>, subdirectories for those are created under <code>bin/</code> and <code>obj</code>.
 +
 
 +
 
 +
=== Working from Scratch ===
 +
When compiling your code, be sure to include the library header files found in libStatgen/include/ and link in the appropriate library (opt: libStatGen.a, debug: libStatGen_debug.a, or profile: libStatGen_profile.a).
 +
 
   −
In the following instructions/comments:
+
=== Starting from a Sample Set of Tools ===
* replace STATGEN_DIR with the path to where the statgen directory is located (does not include statgen/).
+
[https://github.com/statgen/SampleTools https://github.com/statgen/SampleTools] is a repository containing multiple programs within one directory structure. It demonstrates how to have subdirectories for each tool using libStatGen and can be used as a starting point for your set of tools.
* replace MY_CODE_DIR with the path where you want your code located.
     −
To use the StatGen Library, first download and compile via [[StatGen Download | StatGen Download Instructions]] and [[StatGen Repository#Compile.2FBuild | StatGen Compile/Build Instructions]]
+
SampleTools has 3 subdirectories:
 +
* copyrights - contains the copyright information, add your own copyrights as necessary
 +
* SampleProgram1 - a dummy demo program to show the structure for having multiple programs
 +
* SampleProgram2 - a second dummy demo program to show the structure for having multiple programs
   −
This creates the library: STATGEN_DIR/statgen/lib/libStatGen.a, where STATGEN_DIR is the path to where you dec
+
SampleProgram1 & SampleProgram2 have 2 subdirectories:
 +
* src - this is where your own program code goes
 +
* test - this is where your test code goes.  Test code can be setup to run with <code>make test</code> to ensure the program works properly.
   −
== Creating programs using the Default Makefile ==
+
Upon compiling, an <code>obj</code> directory is created under <code>SampleProgram1</code> and <code>SampleProgram2</code> and a <code>bin</code> directory is created at the top level. If you build for <code>debug</code> and/or <code>profile</code>, subdirectories for those are created under <code>bin/</code> and <code>SampleProgram1(2)/obj</code>.
# Create a directory for your own code.
  −
#* <code>mkdir MY_CODE_DIR</code>
  −
# Move into your directory.
  −
#* <code>cd MY_CODE_DIR</code>
  −
# Copy the Makefile from the statgen directory.
  −
#* <code>cp STATGEN_DIR/statgen/src/Makefile.src Makefile
  −
#* You could instead link the Makefile, but then be careful not to modify it for your program because that may break any other programs that link to it (including those with the statgen repository).
  −
# Create <code>Makefile.tool</code>
  −
#* See [[Makefile.tool]] for what to put into Makefile.tool.
  −
# Compile your program
  −
#* For optimal performance (be sure you also compiled statgen for optimal performance):
  −
#** <code>make</code>
  −
#* For debug (be sure that you also compiled statgen for debug):
  −
#** <code>make OPTFLAG="-ggdb -O0"</code>
     −
NOTE: When you compile, all of your '.o' files will go in a directory called obj that will be created by the Makefile if it does not already exist.
     −
== Creating programs Without the Default Makefile ==
+
'''Using SampleTools as a starting point for your set of tools:'''
You can also use your own Makefile or method of building.
+
# Copy <code>SampleTools</code> into a directory with your toolset name (it is the starting point for your own set of tools).
 +
# Update <code>ChangeLog</code>, <code>.gitignore</code>, and <code>README.txt</code> as appropriate.
 +
# Add any necessary copyrights to the copyrights directory.
 +
# Rename the <code>SampleProgram1</code> and <code>SampleProgram2</code> directories
 +
# Create any additional directories as necessary.
 +
#* Recursively copy the structure/Makefiles from <code>SampleProgram1</code>.
 +
# Update <code>SUBDIRS</code> in <code>Makefile</code> as necessary.
 +
# Update <code>Makefile.inc</code>
 +
## Update the <code>VERSION</code> as necessary.
 +
## Replace all occurrences of <code>SAMPLE_PROGRAM</code> with an all caps name for your toolset.
 +
##*  You can then use the <code>LIB_PATH_<your toolset name></code> environment variable to specify an alternate path to libStatGen specific for your program.  In most cases you will not need to do this.
 +
#* No other updates to <code>Makefile.inc</code> should be necessary.
 +
# For each Program you want to add:
 +
## Move into the appropriate subdirectory.
 +
##* No change should be made to the program's <code>Makefile</code>
 +
## Add your program (cpp & h files) to the <code>src</code> subdirectory.
 +
## Update src/Makefile
 +
### Set EXE to your program executable (replacing sampleProgram)
 +
### Set TOOLBASE, SRCONLY, and HDRONLY as appropriate for specifying your program file names.
 +
### Set any of the other optional settings as specified in the sample makefile.
 +
##* No other changes should be necessary to src/Makefile.
 +
## Add your tests to the <code>test</code> directory.
 +
## Update test/Makefile as appropriate for specifying how to compile/run your tests.
   −
Just be sure to add -ISTAGEN_DIR/statgen/lib/include to your compile line to pull in the library header files.
     −
Add <code>STATGEN_DIR/stagen/lib/libStatGen.a STATGEN_DIR/statgen/lib/samtools/libbam.a -lm -lz -lssl</code> in that order to the end of your compile line to pull in the necessary libraries.
+
= How To Use the APIs =
 +
More coming soon, see: http://genome.sph.umich.edu/wiki/Sam_Library_Usage_Examples
   −
NOTE: These are all handled for you if you use Makefile.src from the statgen repository.
+
[[LibStatGen: ASP#API for Reading ASP Files| ASP APIs]]
   −
= Recently Added Capabilities =
+
[[LibStatGen: VCF#API for Reading VCF Files| VCF APIs]]
* [[SAM/BAM Convert Sequence|SAM/BAM support conversion between '=' and the base in a sequence]]
 
96

edits

Navigation menu