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.math.RoundingMode;
  31 import java.text.DecimalFormat;
  32 import java.text.NumberFormat;
  33 import java.util.ArrayList;
  34 import java.util.List;
  35
  36 import org.forester.io.parsers.FastaParser;
  37 import org.forester.io.parsers.GeneralMsaParser;
  38 import org.forester.msa.DeleteableMsa;
  39 import org.forester.msa.Msa.MSA_FORMAT;
  40 import org.forester.msa.MsaInferrer;
  41 import org.forester.msa.MsaMethods;
  42 import org.forester.msa_compactor.Chart;
  43 import org.forester.msa_compactor.MsaCompactor;
  44 import org.forester.msa_compactor.MsaProperties;
  45 import org.forester.util.CommandLineArguments;
  46 import org.forester.util.DescriptiveStatistics;
  47 import org.forester.util.ForesterUtil;
  48
  49 public class msa_compactor {
  50
  51     final private static NumberFormat NF_1                                   = new DecimalFormat( "#.0" );
  52     static {
  53         NF_1.setRoundingMode( RoundingMode.HALF_UP );
  54     }
  55     final static private String       HELP_OPTION_1                          = "help";
  56     final static private String       HELP_OPTION_2                          = "h";
  57     final static private String       REMOVE_WORST_OFFENDERS_OPTION          = "r";
  58     final static private String       AV_GAPINESS_OPTION                     = "g";
  59     final static private String       STEP_OPTION                            = "s";
  60     final static private String       LENGTH_OPTION                          = "l";
  61     final static private String       REALIGN_OPTION                         = "a";
  62     //
  63     final static private String       STEP_FOR_DIAGNOSTICS_OPTION            = "sd";
  64     final static private String       MIN_LENGTH_OPTION                      = "ml";
  65     final static private String       GAP_RATIO_LENGTH_OPTION                = "gr";
  66     final static private String       REPORT_ALN_MEAN_IDENTITY               = "q";
  67     final static private String       OUTPUT_FORMAT_PHYLIP_OPTION            = "p";
  68     final static private String       OUTPUT_REMOVED_SEQS_OPTION             = "ro";
  69     final static private String       MAFFT_OPTIONS                          = "mo";
  70     //
  71     final static private String       PATH_TO_MAFFT_OPTION                   = "mafft";
  72     final static private String       DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION = "nn";
  73     final static private String       PRG_NAME                               = "msa_compactor";
  74     final static private String       PRG_DESC                               = "multiple sequence aligment compactor";
  75     final static private String       PRG_VERSION                            = "0.2";
  76     final static private String       PRG_DATE                               = "140428";
  77     final static private String       E_MAIL                                 = "czmasek@sanfordburham.org";
  78     final static private String       WWW                                    = "https://sites.google.com/site/cmzmasek/home/software/forester";
  79
  80     public static void main( final String args[] ) {
  81         try {
  82             final CommandLineArguments cla = new CommandLineArguments( args );
  83             if ( cla.isOptionSet( HELP_OPTION_1 ) || cla.isOptionSet( HELP_OPTION_2 )
  84                     || ( ( cla.getNumberOfNames() < 1 ) || ( cla.getNumberOfNames() > 2 ) ) ) {
  85                 printHelp();
  86                 System.exit( 0 );
  87             }
  88             final File in = cla.getFile( 0 );
  89             File out = null;
  90             if ( cla.getNumberOfNames() > 1 ) {
  91                 out = cla.getFile( 1 );
  92             }
  93             int worst_remove = -1;
  94             double av_gap = -1;
  95             int length = -1;
  96             int step = 1;
  97             boolean realign = false;
  98             boolean norm = true;
  99             String path_to_mafft = null;
 100             int step_for_diagnostics = 1;
 101             int min_length = -1;
 102             double gap_ratio = -1;
 103             boolean report_aln_mean_identity = false;
 104             MSA_FORMAT output_format = MSA_FORMAT.FASTA;
 105             File removed_seqs_out_base = null;
 106             String mafft_options = "--auto";
 107             final List<String> allowed_options = new ArrayList<String>();
 108             allowed_options.add( REMOVE_WORST_OFFENDERS_OPTION );
 109             allowed_options.add( AV_GAPINESS_OPTION );
 110             allowed_options.add( LENGTH_OPTION );
 111             allowed_options.add( REALIGN_OPTION );
 112             allowed_options.add( DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION );
 113             allowed_options.add( STEP_OPTION );
 114             allowed_options.add( PATH_TO_MAFFT_OPTION );
 115             allowed_options.add( STEP_FOR_DIAGNOSTICS_OPTION );
 116             allowed_options.add( MIN_LENGTH_OPTION );
 117             allowed_options.add( GAP_RATIO_LENGTH_OPTION );
 118             allowed_options.add( REPORT_ALN_MEAN_IDENTITY );
 119             allowed_options.add( OUTPUT_FORMAT_PHYLIP_OPTION );
 120             allowed_options.add( OUTPUT_REMOVED_SEQS_OPTION );
 121             allowed_options.add( MAFFT_OPTIONS );
 122             final String dissallowed_options = cla.validateAllowedOptionsAsString( allowed_options );
 123             if ( dissallowed_options.length() > 0 ) {
 124                 ForesterUtil.fatalError( PRG_NAME, "unknown option(s): " + dissallowed_options );
 125             }
 126             DeleteableMsa msa = null;
 127             final FileInputStream is = new FileInputStream( in );
 128             if ( FastaParser.isLikelyFasta( in ) ) {
 129                 msa = DeleteableMsa.createInstance( FastaParser.parseMsa( is ) );
 130             }
 131             else {
 132                 msa = DeleteableMsa.createInstance( GeneralMsaParser.parse( is ) );
 133             }
 134             final DescriptiveStatistics initial_msa_stats = MsaMethods.calculateEffectiveLengthStatistics( msa );
 135             //System.out.println( initial_msa_stats.toString() );
 136             if ( ( cla.isOptionSet( LENGTH_OPTION ) || cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) || cla
 137                     .isOptionSet( AV_GAPINESS_OPTION ) ) && ( out == null ) ) {
 138                 ForesterUtil.fatalError( PRG_NAME, "outfile file missing" );
 139             }
 140             if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) ) {
 141                 worst_remove = cla.getOptionValueAsInt( REMOVE_WORST_OFFENDERS_OPTION );
 142                 if ( ( worst_remove < 1 ) || ( worst_remove >= msa.getNumberOfSequences() - 1 ) ) {
 143                     ForesterUtil.fatalError( PRG_NAME, "number of worst offender sequences to remove is out of range: "
 144                             + worst_remove );
 145                 }
 146             }
 147             if ( cla.isOptionSet( AV_GAPINESS_OPTION ) ) {
 148                 if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) ) {
 149                     printHelp();
 150                     System.exit( 0 );
 151                 }
 152                 av_gap = cla.getOptionValueAsDouble( AV_GAPINESS_OPTION );
 153                 if ( ( av_gap < 0 ) || ( av_gap >= 1 ) ) {
 154                     ForesterUtil.fatalError( PRG_NAME, "target gap-ratio is out of range: " + av_gap );
 155                 }
 156             }
 157             if ( cla.isOptionSet( LENGTH_OPTION ) ) {
 158                 if ( cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) || cla.isOptionSet( AV_GAPINESS_OPTION ) ) {
 159                     printHelp();
 160                     System.exit( 0 );
 161                 }
 162                 length = cla.getOptionValueAsInt( LENGTH_OPTION );
 163                 if ( length >= msa.getLength() ) {
 164                     ForesterUtil.fatalError( PRG_NAME,
 165                                              "target length is out of range [longer than MSA (" + msa.getLength()
 166                                                      + ")]: " + length );
 167                 }
 168                 else if ( length < initial_msa_stats.getMin() ) {
 169                     ForesterUtil.fatalError( PRG_NAME,
 170                                              "target length is out of range [shorter than the shortest sequence ("
 171                                                      + initial_msa_stats.getMin() + ") ]: " + length );
 172                 }
 173             }
 174             if ( cla.isOptionSet( STEP_OPTION ) ) {
 175                 step = cla.getOptionValueAsInt( STEP_OPTION );
 176                 if ( ( step < 1 )
 177                         || ( ( step > msa.getNumberOfSequences() ) || ( ( worst_remove > 0 ) && ( step > worst_remove ) ) ) ) {
 178                     ForesterUtil.fatalError( PRG_NAME, "value for step is out of range: " + step );
 179                 }
 180             }
 181             if ( cla.isOptionSet( REALIGN_OPTION ) ) {
 182                 realign = true;
 183             }
 184             if ( cla.isOptionSet( PATH_TO_MAFFT_OPTION ) ) {
 185                 if ( !realign ) {
 186                     ForesterUtil.fatalError( PRG_NAME, "no need to indicate path to MAFFT without realigning" );
 187                 }
 188                 path_to_mafft = cla.getOptionValueAsCleanString( PATH_TO_MAFFT_OPTION );
 189             }
 190             if ( cla.isOptionSet( DO_NOT_NORMALIZE_FOR_EFF_LENGTH_OPTION ) ) {
 191                 norm = false;
 192             }
 193             if ( cla.isOptionSet( STEP_FOR_DIAGNOSTICS_OPTION ) ) {
 194                 step_for_diagnostics = cla.getOptionValueAsInt( STEP_FOR_DIAGNOSTICS_OPTION );
 195                 if ( ( step_for_diagnostics < 1 )
 196                         || ( ( step_for_diagnostics > msa.getNumberOfSequences() ) || ( ( worst_remove > 0 ) && ( step_for_diagnostics > worst_remove ) ) ) ) {
 197                     ForesterUtil.fatalError( PRG_NAME, "value for diagnostic step is out of range: "
 198                             + step_for_diagnostics );
 199                 }
 200             }
 201             if ( cla.isOptionSet( MIN_LENGTH_OPTION ) ) {
 202                 min_length = cla.getOptionValueAsInt( MIN_LENGTH_OPTION );
 203                 if ( ( min_length < 2 ) || ( min_length > initial_msa_stats.getMax() ) ) {
 204                     ForesterUtil.fatalError( PRG_NAME, "value for minimal sequence length is out of range: "
 205                             + min_length );
 206                 }
 207             }
 208             if ( cla.isOptionSet( GAP_RATIO_LENGTH_OPTION ) ) {
 209                 gap_ratio = cla.getOptionValueAsDouble( GAP_RATIO_LENGTH_OPTION );
 210                 if ( ( gap_ratio < 0 ) || ( gap_ratio > 1 ) ) {
 211                     ForesterUtil.fatalError( PRG_NAME, "gap ratio is out of range: " + gap_ratio );
 212                 }
 213             }
 214             if ( cla.isOptionSet( REPORT_ALN_MEAN_IDENTITY ) ) {
 215                 report_aln_mean_identity = true;
 216             }
 217             if ( cla.isOptionSet( OUTPUT_FORMAT_PHYLIP_OPTION ) ) {
 218                 output_format = MSA_FORMAT.PHYLIP;
 219             }
 220             if ( cla.isOptionSet( OUTPUT_REMOVED_SEQS_OPTION ) ) {
 221                 final String s = cla.getOptionValueAsCleanString( OUTPUT_REMOVED_SEQS_OPTION );
 222                 removed_seqs_out_base = new File( s );
 223             }
 224             if ( realign ) {
 225                 if ( ForesterUtil.isEmpty( path_to_mafft ) ) {
 226                     path_to_mafft = MsaCompactor.guessPathToMafft();
 227                 }
 228                 checkPathToMafft( path_to_mafft );
 229                 if ( cla.isOptionSet( MAFFT_OPTIONS ) ) {
 230                     mafft_options = cla.getOptionValueAsCleanString( MAFFT_OPTIONS );
 231                     if ( ForesterUtil.isEmpty( mafft_options ) || ( mafft_options.length() < 3 ) ) {
 232                         ForesterUtil.fatalError( PRG_NAME, "gap ratio is out of range: " + gap_ratio );
 233                     }
 234                 }
 235             }
 236             if ( ( !cla.isOptionSet( LENGTH_OPTION ) && !cla.isOptionSet( REMOVE_WORST_OFFENDERS_OPTION ) && !cla
 237                     .isOptionSet( AV_GAPINESS_OPTION ) ) && ( ( out != null ) || ( removed_seqs_out_base != null ) ) ) {
 238                 ForesterUtil.fatalError( PRG_NAME,
 239                                          "chart only, no outfile(s) produced (no need to indicate output file(s))" );
 240             }
 241             ForesterUtil.printProgramInformation( PRG_NAME,
 242                                                   PRG_DESC,
 243                                                   PRG_VERSION,
 244                                                   PRG_DATE,
 245                                                   E_MAIL,
 246                                                   WWW,
 247                                                   ForesterUtil.getForesterLibraryInformation() );
 248             System.out.println( "Input MSA                            : " + in );
 249             System.out.println( "  MSA length                         : " + msa.getLength() );
 250             System.out.println( "  Number of sequences                : " + msa.getNumberOfSequences() );
 251             System.out.println( "  Median sequence length             : " + NF_1.format( initial_msa_stats.median() ) );
 252             System.out.println( "  Mean sequence length               : "
 253                     + NF_1.format( initial_msa_stats.arithmeticMean() ) );
 254             System.out.println( "  Max sequence length                : " + ( ( int ) initial_msa_stats.getMax() ) );
 255             System.out.println( "  Min sequence length                : " + ( ( int ) initial_msa_stats.getMin() ) );
 256             if ( out != null ) {
 257                 System.out.println( "Output                               : " + out );
 258             }
 259             else {
 260                 System.out.println( "Output                               : n/a" );
 261             }
 262             if ( removed_seqs_out_base != null ) {
 263                 System.out.println( "Write removed sequences to           : " + removed_seqs_out_base );
 264             }
 265             if ( worst_remove > 0 ) {
 266                 System.out.println( "Number of worst offenders to remove  : " + worst_remove );
 267             }
 268             else if ( av_gap > 0 ) {
 269                 System.out.println( "Target gap-ratio                     : " + av_gap );
 270             }
 271             else if ( length > 0 ) {
 272                 System.out.println( "Target MSA length                    : " + length );
 273             }
 274             else {
 275                 System.out.println( "Chart and diagnostics only           : true" );
 276             }
 277             if ( ( out != null ) || ( removed_seqs_out_base != null ) ) {
 278                 System.out.println( "Output format                        : "
 279                         + ( output_format == MSA_FORMAT.FASTA ? "fasta" : "phylip" ) );
 280             }
 281             System.out.println( "Step for output and re-aligning      : " + step );
 282             System.out.println( "Step for diagnostics reports         : " + step_for_diagnostics );
 283             System.out.println( "Calculate mean identity              : " + report_aln_mean_identity );
 284             if ( !norm ) {
 285                 System.out.println( "Normalize                            : " + norm );
 286             }
 287             System.out.println( "Realign with MAFFT                   : " + realign );
 288             if ( realign ) {
 289                 System.out.println( "MAFFT options                        : " + mafft_options );
 290             }
 291             if ( min_length > -1 ) {
 292                 System.out.println( "Minimal effective sequence length    : " + min_length );
 293             }
 294             if ( gap_ratio > -1 ) {
 295                 System.out.println( "Maximum allowed gap ratio per column : " + gap_ratio );
 296             }
 297             System.out.println();
 298             //
 299             //
 300             final int initial_number_of_seqs = msa.getNumberOfSequences();
 301             List<MsaProperties> msa_props = null;
 302             if ( worst_remove > 0 ) {
 303                 final MsaCompactor mc = new MsaCompactor( msa );
 304                 mc.setRealign( realign );
 305                 mc.setOutputFormat( output_format );
 306                 if ( realign ) {
 307                     mc.setPathToMafft( path_to_mafft );
 308                     mc.setMafftOptions( mafft_options );
 309                 }
 310                 mc.setNorm( norm );
 311                 mc.setReportAlnMeanIdentity( report_aln_mean_identity );
 312                 mc.setOutFileBase( out );
 313                 if ( removed_seqs_out_base != null ) {
 314                     mc.setRemovedSeqsOutBase( removed_seqs_out_base );
 315                 }
 316                 mc.setStep( step );
 317                 mc.setStepForDiagnostics( step_for_diagnostics );
 318                 msa_props = mc.removeWorstOffenders( worst_remove );
 319             }
 320             else if ( av_gap > 0 ) {
 321                 final MsaCompactor mc = new MsaCompactor( msa );
 322                 mc.setRealign( realign );
 323                 mc.setOutputFormat( output_format );
 324                 if ( realign ) {
 325                     mc.setPathToMafft( path_to_mafft );
 326                     mc.setMafftOptions( mafft_options );
 327                 }
 328                 mc.setNorm( norm );
 329                 mc.setReportAlnMeanIdentity( report_aln_mean_identity );
 330                 mc.setOutFileBase( out );
 331                 if ( removed_seqs_out_base != null ) {
 332                     mc.setRemovedSeqsOutBase( removed_seqs_out_base );
 333                 }
 334                 mc.setStep( step );
 335                 mc.setStepForDiagnostics( step_for_diagnostics );
 336                 msa_props = mc.removeViaGapAverage( av_gap );
 337             }
 338             else if ( length > 0 ) {
 339                 final MsaCompactor mc = new MsaCompactor( msa );
 340                 mc.setRealign( realign );
 341                 mc.setOutputFormat( output_format );
 342                 if ( realign ) {
 343                     mc.setPathToMafft( path_to_mafft );
 344                     mc.setMafftOptions( mafft_options );
 345                 }
 346                 mc.setNorm( norm );
 347                 mc.setReportAlnMeanIdentity( report_aln_mean_identity );
 348                 mc.setOutFileBase( out );
 349                 if ( removed_seqs_out_base != null ) {
 350                     mc.setRemovedSeqsOutBase( removed_seqs_out_base );
 351                 }
 352                 mc.setStep( step );
 353                 mc.setStepForDiagnostics( step_for_diagnostics );
 354                 msa_props = mc.removeViaLength( length );
 355             }
 356             else {
 357                 //MsaCompactor.chart( msa, step, realign, norm, path_to_mafft );
 358                 final MsaCompactor mc = new MsaCompactor( msa );
 359                 mc.setRealign( realign );
 360                 if ( realign ) {
 361                     mc.setPathToMafft( path_to_mafft );
 362                     mc.setMafftOptions( mafft_options );
 363                 }
 364                 mc.setNorm( norm );
 365                 mc.setReportAlnMeanIdentity( report_aln_mean_identity );
 366                 mc.setOutFileBase( out );
 367                 mc.setStep( step );
 368                 mc.setStepForDiagnostics( step_for_diagnostics );
 369                 msa_props = mc.chart( step, realign, norm );
 370             }
 371             Chart.display( msa_props, initial_number_of_seqs, report_aln_mean_identity, in.toString() );
 372         }
 373         catch ( final IllegalArgumentException iae ) {
 374             //  iae.printStackTrace(); //TODO remove me
 375             ForesterUtil.fatalError( PRG_NAME, iae.getMessage() );
 376         }
 377         catch ( final IOException ioe ) {
 378             // ioe.printStackTrace(); //TODO remove me
 379             ForesterUtil.fatalError( PRG_NAME, ioe.getMessage() );
 380         }
 381         catch ( final Exception e ) {
 382             ForesterUtil.unexpectedFatalError( PRG_NAME, e );
 383         }
 384     }
 385
 386     private static void checkPathToMafft( final String path_to_mafft ) {
 387         if ( !ForesterUtil.isEmpty( path_to_mafft ) && MsaInferrer.isInstalled( path_to_mafft ) ) {
 388         }
 389         else {
 390             if ( ForesterUtil.isEmpty( path_to_mafft ) ) {
 391                 ForesterUtil.fatalError( PRG_NAME, "no MAFFT executable found, use -\"" + PATH_TO_MAFFT_OPTION
 392                         + "=<path to MAFFT>\" option" );
 393             }
 394             else {
 395                 ForesterUtil.fatalError( PRG_NAME, "no MAFFT executable at \"" + path_to_mafft + "\"" );
 396             }
 397         }
 398     }
 399
 400     private static void printHelp() {
 401         ForesterUtil.printProgramInformation( PRG_NAME,
 402                                               PRG_DESC,
 403                                               PRG_VERSION,
 404                                               PRG_DATE,
 405                                               E_MAIL,
 406                                               WWW,
 407                                               ForesterUtil.getForesterLibraryInformation() );
 408         final String path_to_mafft = MsaCompactor.guessPathToMafft();
 409         String mafft_comment;
 410         if ( !ForesterUtil.isEmpty( path_to_mafft ) ) {
 411             mafft_comment = " (using " + path_to_mafft + ")";
 412         }
 413         else {
 414             mafft_comment = " (no path to MAFFT found, use -\"" + PATH_TO_MAFFT_OPTION + "=<path to MAFFT>\" option";
 415         }
 416         System.out.println( "Usage:" );
 417         System.out.println();
 418         System.out.println( PRG_NAME + " <options> <msa input file> <output file base>" );
 419         System.out.println();
 420         System.out.println( " options: " );
 421         System.out.println();
 422         System.out.println( "   -" + REMOVE_WORST_OFFENDERS_OPTION
 423                 + "=<integer>   number of worst offender sequences to remove" );
 424         System.out.println( "   -" + LENGTH_OPTION + "=<integer>   target MSA length" );
 425         System.out.println( "   -" + AV_GAPINESS_OPTION + "=<decimal>   target gap-ratio (0.0-1.0)" );
 426         System.out.println( "   -" + REALIGN_OPTION + "             to realign using MAFFT" + mafft_comment );
 427         System.out.println( "   -" + MAFFT_OPTIONS + "=<string>   options for MAFFT (default: --auto)" );
 428         System.out.println( "   -" + STEP_OPTION + "=<integer>   step for output and re-aligning (default: 1)" );
 429         System.out.println( "   -" + STEP_FOR_DIAGNOSTICS_OPTION
 430                 + "=<integer>  step for diagnostics reports (default: 1)" );
 431         //   System.out.println( "   -" + MIN_LENGTH_OPTION
 432         //           + "=<integer>  minimal effecive sequence length (for deleting of shorter sequences)" );
 433         //   System.out.println( "   -" + GAP_RATIO_LENGTH_OPTION
 434         //           + "=<decimal>  maximal allowed gap ratio per column (for deleting of columms) (0.0-1.0)" );
 435         System.out
 436                 .println( "   -"
 437                         + REPORT_ALN_MEAN_IDENTITY
 438                         + "             to calculate mean MSA column identity (\"MSA quality\") (not recommended for very large alignments)" );
 439         System.out.println( "   -" + OUTPUT_FORMAT_PHYLIP_OPTION
 440                 + "             to write output alignments in phylip format instead of fasta" );
 441         System.out.println( "   -" + OUTPUT_REMOVED_SEQS_OPTION + "=<file>     to output the removed sequences" );
 442         System.out.println();
 443         System.out.println();
 444         System.out.println();
 445     }
 446 }