forester/java/src/org/forester/surfacing/DomainLengths.java

   1 // $Id:
   2 //
   3 // FORESTER -- software libraries and applications
   4 // for evolutionary biology research and applications.
   5 //
   6 // Copyright (C) 2008-2010 Christian M. Zmasek
   7 // Copyright (C) 2008-2010 Burnham Institute for Medical Research
   8 // All rights reserved
   9 //
  10 // This library is free software; you can redistribute it and/or
  11 // modify it under the terms of the GNU Lesser General Public
  12 // License as published by the Free Software Foundation; either
  13 // version 2.1 of the License, or (at your option) any later version.
  14 //
  15 // This library is distributed in the hope that it will be useful,
  16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 // Lesser General Public License for more details.
  19 //
  20 // You should have received a copy of the GNU Lesser General Public
  21 // License along with this library; if not, write to the Free Software
  22 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  23 //
  24 // Contact: phylosoft @ gmail . com
  25 // WWW: https://sites.google.com/site/cmzmasek/home/software/forester
  26
  27 package org.forester.surfacing;
  28
  29 import java.util.ArrayList;
  30 import java.util.List;
  31 import java.util.SortedMap;
  32 import java.util.TreeMap;
  33
  34 import org.forester.protein.DomainId;
  35 import org.forester.species.Species;
  36 import org.forester.util.BasicDescriptiveStatistics;
  37 import org.forester.util.DescriptiveStatistics;
  38
  39 public class DomainLengths {
  40
  41     final DomainId                                  _domain_id;
  42     final SortedMap<Species, DescriptiveStatistics> _length_statistics;
  43
  44     public DomainLengths( final DomainId domain_id ) {
  45         _domain_id = domain_id;
  46         _length_statistics = new TreeMap<Species, DescriptiveStatistics>();
  47     }
  48
  49     public void addLength( final Species species, final int domain_length ) {
  50         if ( !getLengthStatistics().containsKey( species ) ) {
  51             addLengthStatistics( species, new BasicDescriptiveStatistics() );
  52         }
  53         getLengthStatistic( species ).addValue( domain_length );
  54     }
  55
  56     private void addLengthStatistics( final Species species, final DescriptiveStatistics length_statistic ) {
  57         if ( getLengthStatistics().containsKey( species ) ) {
  58             throw new IllegalArgumentException( "length statistics for [" + species.getSpeciesId() + "] already added" );
  59         }
  60         getLengthStatistics().put( species, length_statistic );
  61     }
  62
  63     /**
  64      * Returns descriptive statistics based on the arithmetic means
  65      * for each species.
  66      *
  67      *
  68      * @return
  69      */
  70     public DescriptiveStatistics calculateMeanBasedStatistics() {
  71         final DescriptiveStatistics stats = new BasicDescriptiveStatistics();
  72         for( final DescriptiveStatistics s : getLengthStatisticsList() ) {
  73             stats.addValue( s.arithmeticMean() );
  74         }
  75         return stats;
  76     }
  77
  78     /**
  79      *
  80      * Note. This is not technically a Z-score since the distribution
  81      * of means is unknown (and not normal).
  82      *
  83      * @param species
  84      * @return
  85      */
  86     public double calculateZScoreForSpecies( final Species species ) {
  87         final double species_mean = getLengthStatistic( species ).arithmeticMean();
  88         final DescriptiveStatistics domain_stats = calculateMeanBasedStatistics();
  89         final double population_sd = domain_stats.sampleStandardDeviation();
  90         final double population_mean = domain_stats.arithmeticMean();
  91         return ( species_mean - population_mean ) / population_sd;
  92     }
  93
  94     public DomainId getDomainId() {
  95         return _domain_id;
  96     }
  97
  98     public DescriptiveStatistics getLengthStatistic( final Species species ) {
  99         return getLengthStatistics().get( species );
 100     }
 101
 102     private SortedMap<Species, DescriptiveStatistics> getLengthStatistics() {
 103         return _length_statistics;
 104     }
 105
 106     public List<DescriptiveStatistics> getLengthStatisticsList() {
 107         final List<DescriptiveStatistics> list = new ArrayList<DescriptiveStatistics>();
 108         for( final DescriptiveStatistics stats : _length_statistics.values() ) {
 109             list.add( stats );
 110         }
 111         return list;
 112     }
 113
 114     public List<Species> getMeanBasedOutlierSpecies( final double z_score_limit ) {
 115         final List<Species> species = new ArrayList<Species>();
 116         if ( getSpeciesList().size() > 1 ) {
 117             for( final Species s : getSpeciesList() ) {
 118                 final double z = calculateZScoreForSpecies( s );
 119                 if ( z_score_limit < 0 ) {
 120                     if ( z <= z_score_limit ) {
 121                         species.add( s );
 122                     }
 123                 }
 124                 else if ( z_score_limit > 0 ) {
 125                     if ( z >= z_score_limit ) {
 126                         species.add( s );
 127                     }
 128                 }
 129             }
 130         }
 131         return species;
 132     }
 133
 134     public List<Species> getSpeciesList() {
 135         final List<Species> list = new ArrayList<Species>();
 136         for( final Species s : _length_statistics.keySet() ) {
 137             list.add( s );
 138         }
 139         return list;
 140     }
 141
 142     public boolean isHasLengthStatistic( final Species species ) {
 143         return getLengthStatistics().containsKey( species );
 144     }
 145 }