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.species.Species;
  35 import org.forester.util.BasicDescriptiveStatistics;
  36 import org.forester.util.DescriptiveStatistics;
  37
  38 public class DomainLengths {
  39
  40     final String                                    _domain_id;
  41     final SortedMap<Species, DescriptiveStatistics> _length_statistics;
  42
  43     public DomainLengths( final String domain_id ) {
  44         _domain_id = domain_id;
  45         _length_statistics = new TreeMap<Species, DescriptiveStatistics>();
  46     }
  47
  48     public void addLength( final Species species, final int domain_length ) {
  49         if ( !getLengthStatistics().containsKey( species ) ) {
  50             addLengthStatistics( species, new BasicDescriptiveStatistics() );
  51         }
  52         getLengthStatistic( species ).addValue( domain_length );
  53     }
  54
  55     private void addLengthStatistics( final Species species, final DescriptiveStatistics length_statistic ) {
  56         if ( getLengthStatistics().containsKey( species ) ) {
  57             throw new IllegalArgumentException( "length statistics for [" + species.getSpeciesId() + "] already added" );
  58         }
  59         getLengthStatistics().put( species, length_statistic );
  60     }
  61
  62     /**
  63      * Returns descriptive statistics based on the arithmetic means
  64      * for each species.
  65      *
  66      *
  67      * @return
  68      */
  69     public DescriptiveStatistics calculateMeanBasedStatistics() {
  70         final DescriptiveStatistics stats = new BasicDescriptiveStatistics();
  71         for( final DescriptiveStatistics s : getLengthStatisticsList() ) {
  72             stats.addValue( s.arithmeticMean() );
  73         }
  74         return stats;
  75     }
  76
  77     /**
  78      *
  79      * Note. This is not technically a Z-score since the distribution
  80      * of means is unknown (and not normal).
  81      *
  82      * @param species
  83      * @return
  84      */
  85     public double calculateZScoreForSpecies( final Species species ) {
  86         final double species_mean = getLengthStatistic( species ).arithmeticMean();
  87         final DescriptiveStatistics domain_stats = calculateMeanBasedStatistics();
  88         final double population_sd = domain_stats.sampleStandardDeviation();
  89         final double population_mean = domain_stats.arithmeticMean();
  90         return ( species_mean - population_mean ) / population_sd;
  91     }
  92
  93     public String getDomainId() {
  94         return _domain_id;
  95     }
  96
  97     public DescriptiveStatistics getLengthStatistic( final Species species ) {
  98         return getLengthStatistics().get( species );
  99     }
 100
 101     private SortedMap<Species, DescriptiveStatistics> getLengthStatistics() {
 102         return _length_statistics;
 103     }
 104
 105     public List<DescriptiveStatistics> getLengthStatisticsList() {
 106         final List<DescriptiveStatistics> list = new ArrayList<DescriptiveStatistics>();
 107         for( final DescriptiveStatistics stats : _length_statistics.values() ) {
 108             list.add( stats );
 109         }
 110         return list;
 111     }
 112
 113     public List<Species> getMeanBasedOutlierSpecies( final double z_score_limit ) {
 114         final List<Species> species = new ArrayList<Species>();
 115         if ( getSpeciesList().size() > 1 ) {
 116             for( final Species s : getSpeciesList() ) {
 117                 final double z = calculateZScoreForSpecies( s );
 118                 if ( z_score_limit < 0 ) {
 119                     if ( z <= z_score_limit ) {
 120                         species.add( s );
 121                     }
 122                 }
 123                 else if ( z_score_limit > 0 ) {
 124                     if ( z >= z_score_limit ) {
 125                         species.add( s );
 126                     }
 127                 }
 128             }
 129         }
 130         return species;
 131     }
 132
 133     public List<Species> getSpeciesList() {
 134         final List<Species> list = new ArrayList<Species>();
 135         for( final Species s : _length_statistics.keySet() ) {
 136             list.add( s );
 137         }
 138         return list;
 139     }
 140
 141     public boolean isHasLengthStatistic( final Species species ) {
 142         return getLengthStatistics().containsKey( species );
 143     }
 144 }