001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
006     *
007     * Project Info:  http://www.jfree.org/jfreechart/index.html
008     *
009     * This library is free software; you can redistribute it and/or modify it 
010     * under the terms of the GNU Lesser General Public License as published by 
011     * the Free Software Foundation; either version 2.1 of the License, or 
012     * (at your option) any later version.
013     *
014     * This library is distributed in the hope that it will be useful, but 
015     * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
016     * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
017     * License for more details.
018     *
019     * You should have received a copy of the GNU Lesser General Public
020     * License along with this library; if not, write to the Free Software
021     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
022     * USA.  
023     *
024     * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
025     * in the United States and other countries.]
026     *
027     * ---------------------------
028     * NormalizedMatrixSeries.java
029     * ---------------------------
030     * (C) Copyright 2003-2005, by Barak Naveh and Contributors.
031     *
032     * Original Author:  Barak Naveh;;
033     * Contributor(s):   David Gilbert (for Object Refinery Limited);
034     *
035     * $Id: NormalizedMatrixSeries.java,v 1.3.2.1 2005/10/25 21:36:51 mungady Exp $
036     *
037     * Changes
038     * -------
039     * 10-Jul-2003 : Version 1 contributed by Barak Naveh (DG);
040     *
041     */
042     
043    package org.jfree.data.xy;
044    
045    
046    /**
047     * Represents a dense normalized matrix M[i,j] where each Mij item of the
048     * matrix has a value (default is 0). When a matrix item is observed using
049     * <code>getItem</code> method, it is normalized, that is, divided by the
050     * total sum of all items. It can be also be scaled by setting a scale factor.
051     *
052     * @author Barak Naveh
053     */
054    public class NormalizedMatrixSeries extends MatrixSeries {
055        
056        /** The default scale factor. */
057        public static final double DEFAULT_SCALE_FACTOR = 1.0;
058    
059        /**
060         * A factor that multiplies each item in this series when observed using 
061         * getItem method.
062         */
063        private double m_scaleFactor = DEFAULT_SCALE_FACTOR;
064    
065        /** The sum of all items in this matrix */
066        private double m_totalSum;
067    
068        /**
069         * Constructor for NormalizedMatrixSeries.
070         *
071         * @param name  the series name.
072         * @param rows  the number of rows.
073         * @param columns  the number of columns.
074         */
075        public NormalizedMatrixSeries(String name, int rows, int columns) {
076            super(name, rows, columns);
077    
078            /*
079             * we assum super is always initialized to all-zero matrix, so the
080             * total sum should be 0 upon initialization. However, we set it to
081             * Double.MIN_VALUE to get the same effect and yet avoid division by 0
082             * upon initialization.
083             */
084            this.m_totalSum = Double.MIN_VALUE;
085        }
086    
087        /**
088         * Returns an item.
089         * 
090         * @param itemIndex  the index.
091         * 
092         * @return The value.
093         * 
094         * @see org.jfree.data.xy.MatrixSeries#getItem(int)
095         */
096        public Number getItem(int itemIndex) {
097            int i = getItemRow(itemIndex);
098            int j = getItemColumn(itemIndex);
099    
100            double mij = get(i, j) * this.m_scaleFactor;
101            Number n = new Double(mij / this.m_totalSum);
102    
103            return n;
104        }
105    
106        /**
107         * Sets the factor that multiplies each item in this series when observed
108         * using getItem mehtod.
109         *
110         * @param factor new factor to set.
111         *
112         * @see #DEFAULT_SCALE_FACTOR
113         */
114        public void setScaleFactor(double factor) {
115            this.m_scaleFactor = factor;
116        }
117    
118    
119        /**
120         * Returns the factor that multiplies each item in this series when
121         * observed using getItem mehtod.
122         *
123         * @return The factor
124         */
125        public double getScaleFactor() {
126            return this.m_scaleFactor;
127        }
128    
129    
130        /**
131         * @see org.jfree.data.xy.MatrixSeries#update(int, int, double)
132         */
133        public void update(int i, int j, double mij) {
134            this.m_totalSum -= get(i, j);
135            this.m_totalSum += mij;
136    
137            super.update(i, j, mij);
138        }
139    
140        /**
141         * @see org.jfree.data.xy.MatrixSeries#zeroAll()
142         */
143        public void zeroAll() {
144            this.m_totalSum = 0;
145            super.zeroAll();
146        }
147    }