001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2007, 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-2007, 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.3 2007/02/02 15:14:53 mungady Exp $
036     *
037     * Changes
038     * -------
039     * 10-Jul-2003 : Version 1 contributed by Barak Naveh (DG);
040     * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG);
041     *
042     */
043     
044    package org.jfree.data.xy;
045    
046    
047    /**
048     * Represents a dense normalized matrix M[i,j] where each Mij item of the
049     * matrix has a value (default is 0). When a matrix item is observed using
050     * <code>getItem</code> method, it is normalized, that is, divided by the
051     * total sum of all items. It can be also be scaled by setting a scale factor.
052     */
053    public class NormalizedMatrixSeries extends MatrixSeries {
054        
055        /** The default scale factor. */
056        public static final double DEFAULT_SCALE_FACTOR = 1.0;
057    
058        /**
059         * A factor that multiplies each item in this series when observed using 
060         * getItem method.
061         */
062        private double m_scaleFactor = DEFAULT_SCALE_FACTOR;
063    
064        /** The sum of all items in this matrix */
065        private double m_totalSum;
066    
067        /**
068         * Constructor for NormalizedMatrixSeries.
069         *
070         * @param name  the series name.
071         * @param rows  the number of rows.
072         * @param columns  the number of columns.
073         */
074        public NormalizedMatrixSeries(String name, int rows, int columns) {
075            super(name, rows, columns);
076    
077            /*
078             * we assum super is always initialized to all-zero matrix, so the
079             * total sum should be 0 upon initialization. However, we set it to
080             * Double.MIN_VALUE to get the same effect and yet avoid division by 0
081             * upon initialization.
082             */
083            this.m_totalSum = Double.MIN_VALUE;
084        }
085    
086        /**
087         * Returns an item.
088         * 
089         * @param itemIndex  the index.
090         * 
091         * @return The value.
092         * 
093         * @see org.jfree.data.xy.MatrixSeries#getItem(int)
094         */
095        public Number getItem(int itemIndex) {
096            int i = getItemRow(itemIndex);
097            int j = getItemColumn(itemIndex);
098    
099            double mij = get(i, j) * this.m_scaleFactor;
100            Number n = new Double(mij / this.m_totalSum);
101    
102            return n;
103        }
104    
105        /**
106         * Sets the factor that multiplies each item in this series when observed
107         * using getItem mehtod.
108         *
109         * @param factor new factor to set.
110         *
111         * @see #DEFAULT_SCALE_FACTOR
112         */
113        public void setScaleFactor(double factor) {
114            this.m_scaleFactor = factor;
115            // FIXME: this should generate a series change event
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    }