forester/java/src/org/forester/application/msa_compactor.java

   1 // $Id:
   2 // FORESTER -- software libraries and applications
   3 // for evolutionary biology research and applications.
   4 //
   5 // Copyright (C) 2014 Christian M. Zmasek
   6 // Copyright (C) 2014 Sanford-Burnham Medical Research Institute
   7 // All rights reserved
   8 //
   9 // This library is free software; you can redistribute it and/or
  10 // modify it under the terms of the GNU Lesser General Public
  11 // License as published by the Free Software Foundation; either
  12 // version 2.1 of the License, or (at your option) any later version.
  13 //
  14 // This library is distributed in the hope that it will be useful,
  15 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17 // Lesser General Public License for more details.
  18 //
  19 // You should have received a copy of the GNU Lesser General Public
  20 // License along with this library; if not, write to the Free Software
  21 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  22 //
  23 // WWW: https://sites.google.com/site/cmzmasek/home/software/forester
  24
  25 package org.forester.application;
  26
  27 import java.io.File;
  28 import java.io.FileInputStream;
  29 import java.io.IOException;
  30 import java.util.ArrayList;
  31 import java.util.List;
  32
  33 import org.forester.io.parsers.FastaParser;
  34 import org.forester.io.parsers.GeneralMsaParser;
  35 import org.forester.msa.DeleteableMsa;
  36 import org.forester.msa.Msa.MSA_FORMAT;
  37 import org.forester.msa.MsaInferrer;
  38 import org.forester.msa.MsaMethods;
  39 import org.forester.msa_compactor.Chart;
  40 import org.forester.msa_compactor.MsaCompactor;
  41 import org.forester.msa_compactor.MsaProperties;
  42 import org.forester.util.CommandLineArguments;
  43 import org.forester.util.DescriptiveStatistics;
  44 import org.forester.util.ForesterUtil;
  45
  46 public class msa_compactor {
  47
  48     final static private String HELP_OPTION_1                          = "help";
  49     final static private String HELP_OPTION_2                          = "h";
  50     final static private String REMOVE_WORST_OFFENDERS_OPTION          = "r";
  51     final static private String AV_GAPINESS_OPTION                     = "g";
  52     final static private String STEP_OPTION                            = "s";
  53     final static private String LENGTH_OPTION                          = "l";
  54     final static private String REALIGN_OPTION                         = "a";
  55     //
  56     final static private String STEP_FOR_DIAGNOSTICS_OPTION            = "sd";
  57     final static private String MIN_LENGTH_OPTION                      = "ml";
  58     final static private String GAP_RATIO_LENGTH_OPTION                = "gr";
  59     final static private String REPORT_ALN_MEAN_IDENTITY               = "q";
  60     final static private String OUTPUT_FORMAT_PHYLIP_OPTION            = "f";
  61     final static private String OUTPUT_REMOVED_SEQS_OPTION             = "ro";
  62     final static private String MAFFT_OPTIONS                          = "mo";
  63     //
  64     final static private String PATH_TO_MAFFT_OPTION                   = "mafft";
  65     final static private String DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION = "nn";
  66     final static private String PRG_NAME                               = "msa_compactor";
  67     final static private String PRG_DESC                               = "multiple sequence aligment compactor";
  68     final static private String PRG_VERSION                            = "0.02";
  69     final static private String PRG_DATE                               = "140316";
  70     final static private String E_MAIL                                 = "czmasek@sanfordburham.org";
  71     final static private String WWW                                    = "https://sites.google.com/site/cmzmasek/home/software/forester";
  72
  73     public static void main( final String args[] ) {
  74         try {
  75             final CommandLineArguments cla = new CommandLineArguments( args );
  76             if ( cla.isOptionSet( HELP_OPTION_1 ) || cla.isOptionSet( HELP_OPTION_2 )
  77                     || ( ( cla.getNumberOfNames() < 1 ) || ( cla.getNumberOfNames() > 2 ) ) ) {
  78                 printHelp();
  79                 System.exit( 0 );
  80             }
  81             final File in = cla.getFile( 0 );
  82             File out = null;
  83             if ( cla.getNumberOfNames() > 1 ) {
  84                 out = cla.getFile( 1 );
  85             }
  86             int worst_remove = -1;
  87             double av_gap = -1;
  88             int length = -1;
  89             int step = -1;
  90             boolean realign = false;
  91             boolean norm = true;
  92             String path_to_mafft = null;
  93             int step_for_diagnostics = -1;
  94             int min_length = -1;
  95             double gap_ratio = -1;
  96             boolean report_aln_mean_identity = false;
  97             MSA_FORMAT output_format = MSA_FORMAT.FASTA;
  98             File removed_seqs_out_base = null;
  99             String mafft_options = "--auto";
 100             final List<String> allowed_options = new ArrayList<String>();
 101             allowed_options.add( REMOVE_WORST_OFFENDERS_OPTION );
 102             allowed_options.add( AV_GAPINESS_OPTION );
 103             allowed_options.add( LENGTH_OPTION );
 104             allowed_options.add( REALIGN_OPTION );
 105             allowed_options.add( DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION );
 106             allowed_options.add( STEP_OPTION );
 107             allowed_options.add( PATH_TO_MAFFT_OPTION );
 108             allowed_options.add( STEP_FOR_DIAGNOSTICS_OPTION );
 109             allowed_options.add( MIN_LENGTH_OPTION );
 110             allowed_options.add( GAP_RATIO_LENGTH_OPTION );
 111             allowed_options.add( REPORT_ALN_MEAN_IDENTITY );
 112             allowed_options.add( OUTPUT_FORMAT_PHYLIP_OPTION );
 113             allowed_options.add( OUTPUT_REMOVED_SEQS_OPTION );
 114             allowed_options.add( MAFFT_OPTIONS );
 115             final String dissallowed_options = cla.validateAllowedOptionsAsString( allowed_options );
 116             if ( dissallowed_options.length() > 0 ) {
 117                 ForesterUtil.fatalError( PRG_NAME, "unknown option(s): " + dissallowed_options );
 118             }
 119             DeleteableMsa msa = null;
 120             final FileInputStream is = new FileInputStream( in );
 121             if ( FastaParser.isLikelyFasta( in ) ) {
 122                 msa = DeleteableMsa.createInstance( FastaParser.parseMsa( is ) );
 123             }
 124             else {
 125                 msa = DeleteableMsa.createInstance( GeneralMsaParser.parse( is ) );
 126             }
 127             final DescriptiveStatistics initial_msa_stats = MsaMethods.calculateEffectiveLengthStatistics( msa );
 128             System.out.println( initial_msa_stats.toString() );
 129             if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) ) {
 130                 worst_remove = cla.getOptionValueAsInt( REMOVE_WORST_OFFENDERS_OPTION );
 131                 if ( ( worst_remove < 1 ) || ( worst_remove >= msa.getNumberOfSequences() - 1 ) ) {
 132                     ForesterUtil.fatalError( PRG_NAME, "number of worst offender sequences to remove is out of range: "
 133                             + worst_remove );
 134                 }
 135             }
 136             if ( cla.isOptionSet( AV_GAPINESS_OPTION ) ) {
 137                 if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) ) {
 138                     printHelp();
 139                     System.exit( 0 );
 140                 }
 141                 av_gap = cla.getOptionValueAsDouble( AV_GAPINESS_OPTION );
 142                 if ( ( av_gap < 0 ) || ( av_gap >= 1 ) ) {
 143                     ForesterUtil.fatalError( PRG_NAME, "target gap-ratio is out of range: " + av_gap );
 144                 }
 145             }
 146             if ( cla.isOptionSet( LENGTH_OPTION ) ) {
 147                 if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) || cla.isOptionSet( AV_GAPINESS_OPTION ) ) {
 148                     printHelp();
 149                     System.exit( 0 );
 150                 }
 151                 length = cla.getOptionValueAsInt( LENGTH_OPTION );
 152                 if ( ( length < 2 ) || ( length >= msa.getLength() ) ) {
 153                     ForesterUtil.fatalError( PRG_NAME, "target length is out of range: " + length );
 154                 }
 155             }
 156             if ( cla.isOptionSet( STEP_OPTION ) ) {
 157                 step = cla.getOptionValueAsInt( STEP_OPTION );
 158                 if ( ( step < 1 )
 159                         || ( ( step > msa.getNumberOfSequences() ) || ( ( worst_remove > 0 ) && ( step > worst_remove ) ) ) ) {
 160                     ForesterUtil.fatalError( PRG_NAME, "value for step is out of range: " + step );
 161                 }
 162             }
 163             if ( cla.isOptionSet( REALIGN_OPTION ) ) {
 164                 realign = true;
 165             }
 166             if ( cla.isOptionSet( PATH_TO_MAFFT_OPTION ) ) {
 167                 if ( !realign ) {
 168                     ForesterUtil.fatalError( PRG_NAME, "no need to indicate path to MAFFT without realigning" );
 169                 }
 170                 path_to_mafft = cla.getOptionValueAsCleanString( PATH_TO_MAFFT_OPTION );
 171             }
 172             if ( cla.isOptionSet( DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION ) ) {
 173                 norm = false;
 174             }
 175             //
 176             if ( cla.isOptionSet( STEP_FOR_DIAGNOSTICS_OPTION ) ) {
 177                 step_for_diagnostics = cla.getOptionValueAsInt( STEP_FOR_DIAGNOSTICS_OPTION );
 178                 if ( ( step_for_diagnostics < 1 )
 179                         || ( ( step_for_diagnostics > msa.getNumberOfSequences() ) || ( ( worst_remove > 0 ) && ( step_for_diagnostics > worst_remove ) ) ) ) {
 180                     ForesterUtil.fatalError( PRG_NAME, "value for diagnostic step is out of range: "
 181                             + step_for_diagnostics );
 182                 }
 183             }
 184             if ( cla.isOptionSet( MIN_LENGTH_OPTION ) ) {
 185                 min_length = cla.getOptionValueAsInt( MIN_LENGTH_OPTION );
 186                 if ( ( min_length < 2 ) || ( min_length > initial_msa_stats.getMax() ) ) {
 187                     ForesterUtil.fatalError( PRG_NAME, "value for minimal sequence length is out of range: "
 188                             + min_length );
 189                 }
 190             }
 191             if ( cla.isOptionSet( MIN_LENGTH_OPTION ) ) {
 192                 gap_ratio = cla.getOptionValueAsDouble( GAP_RATIO_LENGTH_OPTION );
 193                 if ( ( gap_ratio < 0 ) || ( gap_ratio > 1 ) ) {
 194                     ForesterUtil.fatalError( PRG_NAME, "gap ratio is out of range: " + gap_ratio );
 195                 }
 196             }
 197             if ( cla.isOptionSet( REPORT_ALN_MEAN_IDENTITY ) ) {
 198                 report_aln_mean_identity = true;
 199             }
 200             if ( cla.isOptionSet( OUTPUT_FORMAT_PHYLIP_OPTION ) ) {
 201                 output_format = MSA_FORMAT.PHYLIP;
 202             }
 203             if ( cla.isOptionSet( OUTPUT_REMOVED_SEQS_OPTION ) ) {
 204                 final String s = cla.getOptionValueAsCleanString( OUTPUT_REMOVED_SEQS_OPTION );
 205                 removed_seqs_out_base = new File( s );
 206             }
 207             if ( realign ) {
 208                 if ( ForesterUtil.isEmpty( path_to_mafft ) ) {
 209                     path_to_mafft = MsaCompactor.guessPathToMafft();
 210                 }
 211                 checkPathToMafft( path_to_mafft );
 212                 if ( cla.isOptionSet( MAFFT_OPTIONS ) ) {
 213                     mafft_options = cla.getOptionValueAsCleanString( MAFFT_OPTIONS );
 214                     if ( ForesterUtil.isEmpty( mafft_options ) || ( mafft_options.length() < 3 ) ) {
 215                         ForesterUtil.fatalError( PRG_NAME, "gap ratio is out of range: " + gap_ratio );
 216                     }
 217                 }
 218             }
 219             ForesterUtil.printProgramInformation( PRG_NAME,
 220                                                   PRG_DESC,
 221                                                   PRG_VERSION,
 222                                                   PRG_DATE,
 223                                                   E_MAIL,
 224                                                   WWW,
 225                                                   ForesterUtil.getForesterLibraryInformation() );
 226             //
 227             System.out.println( "Input MSA                            : " + in );
 228             if ( out != null ) {
 229                 System.out.println( "Output                               : " + out );
 230             }
 231             else {
 232                 System.out.println( "Output                               : n/a" );
 233             }
 234             if ( removed_seqs_out_base != null ) {
 235                 System.out.println( "Write removed sequences to           : " + removed_seqs_out_base );
 236             }
 237             if ( worst_remove > 0 ) {
 238                 System.out.println( "Number of worst offenders to remove  : " + worst_remove );
 239             }
 240             else if ( av_gap > 0 ) {
 241                 System.out.println( "Target gap-ratio                     : " + av_gap );
 242             }
 243             else if ( length > 0 ) {
 244                 System.out.println( "Target MSA length                    : " + length );
 245             }
 246             else {
 247                 System.out.println( "Chart and diagnostics only           : true" );
 248             }
 249             if ( ( out != null ) || ( removed_seqs_out_base != null ) ) {
 250                 System.out.println( "Output format                        : "
 251                         + ( output_format == MSA_FORMAT.FASTA ? "fasta" : "phylip" ) );
 252             }
 253             System.out.println( "Step for output and re-aligning)     : " + ( step > 1 ? step : 1 ) );
 254             System.out.println( "Step for diagnostics reports         : "
 255                     + ( step_for_diagnostics > 1 ? step_for_diagnostics : 1 ) );
 256             System.out.println( "Report mean identity (\"MSA quality\") : " + report_aln_mean_identity );
 257             if ( !norm ) {
 258                 System.out.println( "Normalize                            : " + norm );
 259             }
 260             System.out.println( "Realign                              : " + realign );
 261             if ( realign ) {
 262                 System.out.println( "MAFFT options                        : " + mafft_options );
 263             }
 264             if ( min_length > -1 ) {
 265                 System.out.println( "Minimal effective sequence length    : " + min_length );
 266             }
 267             if ( gap_ratio > -1 ) {
 268                 System.out.println( "Maximum allowed gap ratio per column : " + gap_ratio );
 269             }
 270             System.out.println();
 271             //
 272             //
 273             if ( worst_remove > 0 ) {
 274                 final MsaCompactor mc = new MsaCompactor( msa );
 275                 mc.setRealign( realign );
 276                 if ( realign ) {
 277                     mc.setPathToMafft( path_to_mafft );
 278                 }
 279                 mc.setNorm( norm );
 280                 mc.setOutFileBase( out );
 281                 if ( step > 1 ) {
 282                     mc.setStep( step );
 283                 }
 284                 if ( step_for_diagnostics > 1 ) {
 285                     mc.setStepForDiagnostics( step_for_diagnostics );
 286                 }
 287                 mc.removeWorstOffenders( worst_remove );
 288             }
 289             else if ( av_gap > 0 ) {
 290                 final MsaCompactor mc = new MsaCompactor( msa );
 291                 mc.setRealign( realign );
 292                 if ( realign ) {
 293                     mc.setPathToMafft( path_to_mafft );
 294                 }
 295                 mc.setNorm( norm );
 296                 mc.setOutFileBase( out );
 297                 mc.setStep( step );
 298                 mc.removeViaGapAverage( av_gap, true );
 299             }
 300             else if ( length > 0 ) {
 301                 // TODO if < shortest seq -> error
 302                 final MsaCompactor mc = new MsaCompactor( msa );
 303                 mc.setRealign( realign );
 304                 if ( realign ) {
 305                     mc.setPathToMafft( path_to_mafft );
 306                 }
 307                 mc.setNorm( norm );
 308                 mc.setOutFileBase( out );
 309                 mc.setStep( step );
 310                 mc.removeViaLength( length, true );
 311             }
 312             else {
 313                 //MsaCompactor.chart( msa, step, realign, norm, path_to_mafft );
 314                 final int initial_number_of_seqs = msa.getNumberOfSequences();
 315                 final MsaCompactor mc = new MsaCompactor( msa );
 316                 mc.setRealign( realign );
 317                 if ( realign ) {
 318                     mc.setPathToMafft( path_to_mafft );
 319                 }
 320                 mc.setNorm( norm );
 321                 mc.setReportAlnMeanIdentity( report_aln_mean_identity );
 322                 mc.setOutFileBase( out );
 323                 if ( step > 1 ) {
 324                     mc.setStep( step );
 325                 }
 326                 if ( step_for_diagnostics > 1 ) {
 327                     mc.setStepForDiagnostics( step_for_diagnostics );
 328                 }
 329                 final List<MsaProperties> msa_props = mc.chart( step, realign, norm );
 330                 Chart.display( msa_props, initial_number_of_seqs );
 331             }
 332         }
 333         catch ( final IllegalArgumentException iae ) {
 334             iae.printStackTrace(); //TODO remove me
 335             ForesterUtil.fatalError( PRG_NAME, iae.getMessage() );
 336         }
 337         catch ( final IOException ioe ) {
 338             ioe.printStackTrace(); //TODO remove me
 339             ForesterUtil.fatalError( PRG_NAME, ioe.getMessage() );
 340         }
 341         catch ( final Exception e ) {
 342             ForesterUtil.unexpectedFatalError( PRG_NAME, e );
 343         }
 344     }
 345
 346     private static void checkPathToMafft( final String path_to_mafft ) {
 347         if ( !ForesterUtil.isEmpty( path_to_mafft ) && MsaInferrer.isInstalled( path_to_mafft ) ) {
 348             ForesterUtil.programMessage( PRG_NAME, "using MAFFT at \"" + path_to_mafft + "\"" );
 349         }
 350         else {
 351             if ( ForesterUtil.isEmpty( path_to_mafft ) ) {
 352                 ForesterUtil.fatalError( PRG_NAME, "no MAFFT executable found, use -\"" + PATH_TO_MAFFT_OPTION
 353                         + "=<path to MAFFT>\" option" );
 354             }
 355             else {
 356                 ForesterUtil.fatalError( PRG_NAME, "no MAFFT executable at \"" + path_to_mafft + "\"" );
 357             }
 358         }
 359     }
 360
 361     private static void printHelp() {
 362         ForesterUtil.printProgramInformation( PRG_NAME,
 363                                               PRG_DESC,
 364                                               PRG_VERSION,
 365                                               PRG_DATE,
 366                                               E_MAIL,
 367                                               WWW,
 368                                               ForesterUtil.getForesterLibraryInformation() );
 369         final String path_to_mafft = MsaCompactor.guessPathToMafft();
 370         String mafft_comment;
 371         if ( !ForesterUtil.isEmpty( path_to_mafft ) ) {
 372             mafft_comment = " (using " + path_to_mafft + ")";
 373         }
 374         else {
 375             mafft_comment = " (no path to MAFFT found, use -\"" + PATH_TO_MAFFT_OPTION + "=<path to MAFFT>\" option";
 376         }
 377         System.out.println( "Usage:" );
 378         System.out.println();
 379         System.out.println( PRG_NAME + " <options> <msa input file> <output file>" );
 380         System.out.println();
 381         System.out.println( " options: " );
 382         System.out.println();
 383         System.out.println( "   -" + REMOVE_WORST_OFFENDERS_OPTION
 384                 + "=<integer>   number of worst offender sequences to remove" );
 385         System.out.println( "   -" + LENGTH_OPTION + "=<integer>   target MSA length" );
 386         System.out.println( "   -" + AV_GAPINESS_OPTION + "=<decimal>   target gap-ratio (0.0-1.0)" );
 387         System.out.println( "   -" + STEP_OPTION + "=<integer>   step for output and re-aligning (default: 1)" );
 388         System.out.println( "   -" + REALIGN_OPTION + "             to realign using MAFFT" + mafft_comment );
 389         System.out.println( "   -" + MAFFT_OPTIONS + "=<string>   options for MAFFT (default: --auto)" );
 390         System.out.println( "   -" + STEP_FOR_DIAGNOSTICS_OPTION
 391                 + "=<integer>  step for diagnostics reports (default: 1)" );
 392         System.out.println( "   -" + MIN_LENGTH_OPTION
 393                 + "=<integer>  minimal effecive sequence length (for deleting of shorter sequences)" );
 394         System.out.println( "   -" + GAP_RATIO_LENGTH_OPTION
 395                 + "=<decimal>  maximal allowed gap ratio per column (for deleting of columms) (0.0-1.0)" );
 396         System.out.println( "   -" + REPORT_ALN_MEAN_IDENTITY
 397                 + "             to report mean identity diagnostic (not recommended for very large alignments)" );
 398         System.out.println( "   -" + OUTPUT_FORMAT_PHYLIP_OPTION
 399                 + "             to write output alignments in phylip format instead of fasta" );
 400         System.out.println( "   -" + OUTPUT_REMOVED_SEQS_OPTION + "=<file>     to output the removed sequences" );
 401         System.out.println();
 402         System.out.println();
 403         System.out.println();
 404     }
 405 }