spv.spectrum.function
Class Function

java.lang.Object
  java.util.Observable
      spv.spectrum.function.Function

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Observer, Constant

Direct Known Subclasses:

BroadBandFunction, NarrowBandFunction, SherpaFunction

public abstract class Function
extends java.util.Observable
implements Constant, java.util.Observer, java.io.Serializable, java.lang.Cloneable

One-dimensional analytic functions are handled by subclasses of this class.

A function stores internally a list of Parameter objects, and is capable of expressing itself given an array of independent variable values. It can also draw itself on screen (not a plot, just an interactive list of parameters) and generate a ID string that is unique for each object of the class.

A function has a read-only Units attribute, which expresses the physical units in which its dependent values are currently calculated. These units are dependent solely on the units attributes of its parameters. The default units are the standard units supplied by the Units class. Subclasses can override this default units selection.

A function can be "moved to" some specific locus in a WCS space. The exact meaning of that operation is left for subclasses to define. The moving includes a possible change in physical units for both independent and dependent variables.

A Function object listens to update notifications sent by its internal parameters and notifies its listeners in turn. Thus it is both an observer and an observable. This feature can be enabled/disabled at will.

Function instances support a "constrained" mode, in which the instance parameters are constrained to another instance's parameters.

Version:

1.0 - 22Jul99

Author:

Ivo Busko (Space Telescope Science Institute)

See Also:

Serialized Form

Field Summary

protected javax.swing.JPanel	botton_panel
(package private) static java.lang.String	CLASS_ATTRIBUTE
protected static int	COMPONENT
protected java.lang.String	description
private javax.swing.JDesktopPane	desktop
protected static int	EMPIRICAL
protected static java.text.NumberFormat	form1
protected MemoryJFrame	frame
static java.lang.String	FUNCTION_ATTRIBUTE
protected javax.swing.JPanel	gui
private static int	INVALID_SERIAL_NUMBER
protected java.lang.String	name
(package private) static java.lang.String	NAME_ATTRIBUTE
protected boolean	notify
(package private) static java.lang.String	PARAMETER_LIST_ATTRIBUTE
private Function	parent
private int	parent_serial_number
(package private) static java.lang.String	PARENT_SERIAL_NUMBER_ATTRIBUTE
protected KeyedVector	pars
protected static int	REDDENING
private Function	self
private int	serial_number
(package private) static java.lang.String	SERIAL_NUMBER_ATTRIBUTE
private javax.swing.JTextField	text
protected javax.swing.JPanel	top_panel
protected int	type
protected Units	units This may be overriden by subclasses if necessary.
protected java.lang.String	user_id
(package private) static java.lang.String	USERID_ATTRIBUTE

Fields inherited from interface spv.util.Constant

DATA_MARKER, DMAX, DMIN, IINDEF, IMAX, IMIN, MODEL_ID, NORMALIZED_ID, RESIDUALS_ID

Constructor Summary

Function()

Method Summary

void	addParameter(Parameter par) Adds a new parameter to the function, and sets the function as an Observer of the parameter.
protected void	addParameterGUI(int np) Add GUIs from each parameter.
abstract void	addRawValues(double[] xvar, double[] yvar) Expresses the function over an array of independent variable values, and applies the computed values to the supplied array of dependent variable values.
private void	applyParameterValues()
java.lang.Object	clone() Returns a clone copy of this object.
abstract void	coarseAdjust(java.awt.geom.Rectangle2D.Double wcs, XUnits xun, YUnits yun, double[] x, double[] y) Moves the function coordinates to within a WCS space.
void	constrainTo(Function parent) Constrain a function to another.
void	dispose() Disposes the GUI widget.
void	enableNotifications(boolean notify) Sets/resets the notification capability.
protected java.lang.String	getDescription() This method must be overriden by subclasses that want to provide a more verbose description to be used in places such as tool tips.
protected java.awt.Dimension	getFrameSize(int np) Gets the frame size.
abstract java.lang.String	getID() Gets the function ID.
static int	GetInvalidSerialNumber() Returns a constant that signals that a serial number is not valid.
java.lang.String	getName()
int	getNumberOfParameters() Gets the total number of parameters.
Parameter	getParameter(int i) Gets the i-th parameter.
Parameter	getParameter(java.lang.String id) Gets the parameter specified by the given ID.
Function	getParent() Returns the parent of this, when in constrained mode.
int	getParentSerialNumber() Gets the parent's serial number.
int	getSerialNumber() Gets the serial number.
int	getType() Gets the type of this function.
Units	getUnits() Gets the units.
abstract double	getValidRangeMaxLimit() Returns the maximum value of the range of values of the independent variable where the function is valid.
abstract double	getValidRangeMinLimit() Returns the minimum value of the range of values of the independent variable where the function is valid.
void	getWidget()
void	getWidget(javax.swing.JDesktopPane desktop) Gets a screen-representable form of the function.
abstract boolean	isEmission() Returns true if this is a emission component, false otherwise.
(package private) abstract boolean	isNarrow() Returns true if this is a narrow band component, false otherwise.
boolean	isShowing() Tells if the GUI is showing on screen.
void	print(java.io.PrintWriter pw) Write the contents of the function into a print stream.
private void	readText()
abstract void	recenter(double x) Recenters the function at the provided X coordinate.
protected void	refreshGUI() Replaces the GUI by a new one.
void	release() Releases (un-constrains) this function from its parent.
protected Parameter	removeParameter(int index) Removes the parameter pointed by the index, and breaks the Observer link.
void	replaceParameterValue(Parameter par, int i) Replaces the i-th parameter value.
void	resetObservables() This method reestablishes the observer-observable links that exist between the function and its parameters.
void	saveAsXML(org.w3c.dom.Document document, com.sun.xml.tree.ElementNode parent_node) Saves function as an XML element.
protected void	setChanged() This exists only to provide access from within an anonymous class, since setChanged is a protected method.
void	setDefaultMode() This method returns all parameters in the function to default mode.
(package private) void	setInternalLinks() This method is called when a function instance is being re-constructed from a database file.
void	setParametersFromList(java.util.ArrayList list) Sets all parameters for this function from a list.
void	setParentSerialNumber(int serial_number) Sets the parent's serial number.
void	setParentSerialNumber(java.lang.Integer serial_number) Sets the parent's serial number.
void	setSerialNumber(int serial_number) Sets the serial number.
void	setUserID(java.lang.String userID) sets the user ID string.
protected void	setValue(Parameter par, double value) This is a convenience method that sets a parameter value, even if the parameter is in fixed and/or constrained mode.
java.lang.String	toString() Builds a string representation.
void	update(java.util.Observable p, java.lang.Object a) In the default implementation provided by the superclass this method simply passes the notification to listeners.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FUNCTION_ATTRIBUTE

public static final java.lang.String FUNCTION_ATTRIBUTE

See Also:

Constant Field Values

SERIAL_NUMBER_ATTRIBUTE

static final java.lang.String SERIAL_NUMBER_ATTRIBUTE

See Also:

Constant Field Values

CLASS_ATTRIBUTE

static final java.lang.String CLASS_ATTRIBUTE

See Also:

Constant Field Values

NAME_ATTRIBUTE

static final java.lang.String NAME_ATTRIBUTE

See Also:

Constant Field Values

USERID_ATTRIBUTE

static final java.lang.String USERID_ATTRIBUTE

See Also:

Constant Field Values

PARENT_SERIAL_NUMBER_ATTRIBUTE

static final java.lang.String PARENT_SERIAL_NUMBER_ATTRIBUTE

See Also:

Constant Field Values

PARAMETER_LIST_ATTRIBUTE

static final java.lang.String PARAMETER_LIST_ATTRIBUTE

See Also:

Constant Field Values

COMPONENT

protected static final int COMPONENT

See Also:

Constant Field Values

REDDENING

protected static final int REDDENING

See Also:

Constant Field Values

EMPIRICAL

protected static final int EMPIRICAL

See Also:

Constant Field Values

INVALID_SERIAL_NUMBER

private static final int INVALID_SERIAL_NUMBER

See Also:

Constant Field Values

name

protected java.lang.String name

description

protected java.lang.String description

type

protected int type

user_id

protected java.lang.String user_id

pars

protected KeyedVector pars

notify

protected boolean notify

gui

protected javax.swing.JPanel gui

top_panel

protected javax.swing.JPanel top_panel

botton_panel

protected javax.swing.JPanel botton_panel

desktop

private javax.swing.JDesktopPane desktop

frame

protected MemoryJFrame frame

text

private javax.swing.JTextField text

serial_number

private int serial_number

parent_serial_number

private int parent_serial_number

parent

private Function parent

self

private Function self

form1

protected static final java.text.NumberFormat form1

units

protected Units units

This may be overriden by subclasses if necessary.

Constructor Detail

Function

public Function()

Method Detail

GetInvalidSerialNumber

public static int GetInvalidSerialNumber()

Returns a constant that signals that a serial number is not valid.

Returns:

constant hat signals that a serial number is not valid

toString

public java.lang.String toString()

Builds a string representation. This consists of the function name only.

Overrides:

toString in class java.lang.Object

Returns:

the string

getName

public java.lang.String getName()

getDescription

protected java.lang.String getDescription()

This method must be overriden by subclasses that want to provide a more verbose description to be used in places such as tool tips.

Returns:

a description string

getType

public int getType()

Gets the type of this function. It is used to tell apart "regular" spectral components from reddening laws and empirical, non-physical forms such as polynomials.

Returns:

the type

getNumberOfParameters

public int getNumberOfParameters()

Gets the total number of parameters.

Returns:

the number of parameters

getUnits

public Units getUnits()

Gets the units.

Returns:

the units

getParameter

public Parameter getParameter(int i)

Gets the i-th parameter.

Parameters:

i - the index

Returns:

the corresponding Parameter object, or null if the index is invalid.

getParameter

public Parameter getParameter(java.lang.String id)

Gets the parameter specified by the given ID. No method exists to return the list of parameter IDs in a Function object. The reason is that this method of parameter retrieval will be used, most likely, only by the parameter expression evaluator using user-typed parameter IDs. So the code will have no need to know parameter IDs.

Parameters:

id - the ID

Returns:

the corresponding Parameter object, or null if the ID is invalid.

getSerialNumber

public int getSerialNumber()

Gets the serial number.

Serial numbers are auxiliary quantities useful in the process of assembling a collection of functions. They are not used by the functions themselves.

Serial numbers are 1-indexed.

Returns:

the serial number

setSerialNumber

public void setSerialNumber(int serial_number)

Sets the serial number.

Parameters:

serial_number - the serial number

getParentSerialNumber

public int getParentSerialNumber()

Gets the parent's serial number.

Returns:

the parent's serial number

setParentSerialNumber

public void setParentSerialNumber(int serial_number)

Sets the parent's serial number.

Parameters:

serial_number - the parent's serial number

setParentSerialNumber

public void setParentSerialNumber(java.lang.Integer serial_number)

Sets the parent's serial number.

Parameters:

serial_number - the parent's serial number

setUserID

public void setUserID(java.lang.String userID)

sets the user ID string.

Parameters:

userID - the user ID string

enableNotifications

public void enableNotifications(boolean notify)

Sets/resets the notification capability.

Parameters:

notify - if true, listeners are notified

getWidget

public void getWidget(javax.swing.JDesktopPane desktop)

Gets a screen-representable form of the function. This method builds a default depiction; subclasses that need a custom depiction must override it. Two signatures are provided, so a desktop instance can be optionally provided.

getWidget

public void getWidget()

readText

private void readText()

applyParameterValues

private void applyParameterValues()

getFrameSize

protected java.awt.Dimension getFrameSize(int np)

Gets the frame size.

Parameters:

np - the number of parameters

Returns:

the frame size

addParameterGUI

protected void addParameterGUI(int np)

Add GUIs from each parameter.

Parameters:

np - the number of parameters

print

public void print(java.io.PrintWriter pw)

Write the contents of the function into a print stream.

Parameters:

pw - the stream to write to

saveAsXML

public void saveAsXML(org.w3c.dom.Document document,
                      com.sun.xml.tree.ElementNode parent_node)

Saves function as an XML element.

Parameters:

document - the document where to save the function

parent_node - the parent element where to save the function

refreshGUI

protected void refreshGUI()

Replaces the GUI by a new one.

dispose

public void dispose()

Disposes the GUI widget.

addParameter

public void addParameter(Parameter par)

Adds a new parameter to the function, and sets the function as an Observer of the parameter.

Parameters:

par - the parameter to add

removeParameter

protected Parameter removeParameter(int index)

Removes the parameter pointed by the index, and breaks the Observer link.

Parameters:

index - the index of the parameter to remove

Returns:

the removed parameter

setParametersFromList

public void setParametersFromList(java.util.ArrayList list)

Sets all parameters for this function from a list. This method should be used only on pristine Function instances.

Parameters:

list - the list with Parameter objects

replaceParameterValue

public void replaceParameterValue(Parameter par,
                                  int i)

Replaces the i-th parameter value.

Parameters:

par - the Parameter object with the new value

i - the index

setValue

protected void setValue(Parameter par,
                        double value)
                 throws OutOfRangeFunctionException

This is a convenience method that sets a parameter value, even if the parameter is in fixed and/or constrained mode. This method is used by subclasses from within the coarseAdjust method.

Parameters:

par - the parameter to be changed

value - the new value

Throws:

OutOfRangeFunctionException

setDefaultMode

public void setDefaultMode()

This method returns all parameters in the function to default mode. All parameters are set to variable mode; constrained parameters are set to fixed.

Subclasses override this method in case custom behavior is required.

constrainTo

public void constrainTo(Function parent)
                 throws FunctionException

Constrain a function to another.

Parameters of this are constrained on an individual basis against matching parameters of the parent component. The matching criterion is the parameter name.

Constrained parameters are set to fixed mode.

Parameters:

parent - the parent instance to constrain to

Throws:

FunctionException

release

public void release()

Releases (un-constrains) this function from its parent.

getParent

public Function getParent()

Returns the parent of this, when in constrained mode.

Returns:

the parent of this, or null if not constrained.

resetObservables

public void resetObservables()

This method reestablishes the observer-observable links that exist between the function and its parameters. When a function is serialized and later deserialized, the links are broken since Observable does not implement Serializable. Thus this method must be called for every function that gets deserialized.

isShowing

public boolean isShowing()

Tells if the GUI is showing on screen.

Returns:

true if the GUI is showing

setInternalLinks

void setInternalLinks()

This method is called when a function instance is being re-constructed from a database file. Some function types may have parameters that carry links to other parameters in the same function, and those links may not be preserved in the database file (e.g. in XML file).

The superclass provides a default implementation (do nothing). Subclasses must override this as required.

addRawValues

public abstract void addRawValues(double[] xvar,
                                  double[] yvar)

Expresses the function over an array of independent variable values, and applies the computed values to the supplied array of dependent variable values. Sequential application of this method over a range of Function subtypes enables the building of multi-component models with both emission (additive) and absorption (multiplicative transparency) components. It is up to each subclass to decide how exactly it should act on the dependent variable array.

No checking for Constant.INDEF input values is performed.

Parameters:

xvar - array with the independent variable values

yvar - on input: array with the dependent variable values. on output: array with the updated dependent variable values

getID

public abstract java.lang.String getID()

Gets the function ID. This method should generate a string that uniquely identifies the object. An example could be the function name followed by the value of a important parameter value, such as "GAUSSIAN center=1.234"

Returns:

the ID

coarseAdjust

public abstract void coarseAdjust(java.awt.geom.Rectangle2D.Double wcs,
                                  XUnits xun,
                                  YUnits yun,
                                  double[] x,
                                  double[] y)

Moves the function coordinates to within a WCS space. Alternatively, attempts a coarse fit to a set of x, y values. The exact meaning and behavior are set by the subclass, and either the rectangle or the data arrays (but not both) can be null.

Parameters:

wcs - a rectangle that defines the WCS

xun - units of independent variable

yun - units of dependent variable

x - array with independent variable values

y - array with dependent variable values

recenter

public abstract void recenter(double x)

Recenters the function at the provided X coordinate. The meaning of the operation is defined by each subclass.

Parameters:

x - the new center

getValidRangeMinLimit

public abstract double getValidRangeMinLimit()

Returns the minimum value of the range of values of the independent variable where the function is valid. If the function is a broad-band type, this concept does not apply and this method should always return INDEF.

Returns:

the minimum value of the range of values of the independent variable where the function is valid

getValidRangeMaxLimit

public abstract double getValidRangeMaxLimit()

Returns the maximum value of the range of values of the independent variable where the function is valid. If the function is a broad-band type, this concept does not apply and this method should always return INDEF.

Returns:

the maximum value of the range of values of the independent variable where the function is valid

isEmission

public abstract boolean isEmission()

Returns true if this is a emission component, false otherwise.

Returns:

true if this is a emission component, false otherwise

isNarrow

abstract boolean isNarrow()

Returns true if this is a narrow band component, false otherwise.

Returns:

true if this is a barrow band component, false otherwise

update

public void update(java.util.Observable p,
                   java.lang.Object a)

In the default implementation provided by the superclass this method simply passes the notification to listeners. Subclasses that need to perform internal activities when notified by a Parameter object must override this method to perform the required acivities and them end the method with a call to the superclass:

super.update (p, a);

Specified by:

update in interface java.util.Observer

Parameters:

p - the object that sent the notification

a - the object sent as a notification message

setChanged

protected void setChanged()

This exists only to provide access from within an anonymous class, since setChanged is a protected method.

Overrides:

setChanged in class java.util.Observable

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Returns a clone copy of this object.

Overrides:

clone in class java.lang.Object

Returns:

the clone

Throws:

java.lang.CloneNotSupportedException