uk.ac.starlink.ttools.plottask

Class PlotStateFactory

java.lang.Object

uk.ac.starlink.ttools.plottask.PlotStateFactory

Direct Known Subclasses:

HistogramPlotStateFactory, Plot3DStateFactory

public class PlotStateFactory
extends Object

Obtains a PlotState and associated PlotData from the execution environment. It sets up and interrogates a lot of parameters which describe how the plot should be done, and organises this information into a single object, a PlotState. It is subclassed for different plot types.

Since:

22 Apr 2008

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUX_VARIABLE Symbolic suffix representing an auxiliary axis in per-aux parameter names.
static String	SUBSET_VARIABLE Symbolic suffix representing a subset in per-subset parameter names.
static String	TABLE_VARIABLE Symbolic suffix representing a table in per-table parameter names.

Constructor Summary

Constructors

Constructor and Description
PlotStateFactory(String[] dimNames, boolean useAux, boolean useLabel, int errNdim) Constructor.

Method Summary

Modifier and Type	Method and Description
Style	adjustFromData(Style style, int iset, DataBounds bounds) Updates a plotting style generated by this factory with information generated from a first pass through the data.
DataBounds	calculateBounds(PlotState state, TablePlot plot) Calculates data bounds for a given data set as appropriate for the given plot.
protected void	configureFromBounds(PlotState state, DataBounds bounds) Updates a plot state generated by this factory with information generated from a first pass through the data.
void	configureFromData(PlotState state, TablePlot plot) Performs additional plot state configuration which may require a pass through the data.
protected void	configurePlotState(PlotState state, Environment env) Configures a PlotState object by examining parameter values in a given execution environment.
protected TablePlotData	createPlotData(Environment env, String tLabel, StarTable table, String[] setExprs, String[] setNames, Style[] setStyles, String labelExpr, String[] coordExprs, String[] errExprs) Constructs a PlotData object.
protected PlotState	createPlotState() Creates a new unconfigured PlotState object suitable for configuration by this factory.
protected StyleFactory	createStyleFactory(String prefix) Constructs a style factory which can retrieve a plotting style suitable for use with this factory from the environment.
Parameter<?>[]	getParameters() Returns the parameters associated with this object.
PlotState	getPlotState(Environment env) Returns a configured PlotState obtained from parameter values specified by the given execution environment.
boolean	requiresAdjustFromData(Style style) Indicates whether a given style generated by this factory needs to be updated with information from a first pass through the data.
protected boolean	requiresConfigureFromBounds(PlotState state) Indicates whether it is necessary to calculate the DataBounds for a given PlotState before it is ready to be used.

Methods inherited from class java.lang.Object

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

Field Detail

TABLE_VARIABLE

public static final String TABLE_VARIABLE

Symbolic suffix representing a table in per-table parameter names.

See Also:

Constant Field Values

SUBSET_VARIABLE

public static final String SUBSET_VARIABLE

Symbolic suffix representing a subset in per-subset parameter names.

See Also:

Constant Field Values

AUX_VARIABLE

public static final String AUX_VARIABLE

Symbolic suffix representing an auxiliary axis in per-aux parameter names. Currently blank, as only one auxiliary axis is provided for.

See Also:

Constant Field Values

Constructor Detail

PlotStateFactory

public PlotStateFactory(String[] dimNames,
                        boolean useAux,
                        boolean useLabel,
                        int errNdim)

Constructor.

Parameters:

dimNames - names of main plot dimensions (typically "X", "Y", etc);

useAux - whether auxiliary axes are used

useLabel - whether point text labelling is used

errNdim - number of axes for which errors can be plotted

Method Detail

getParameters

public Parameter<?>[] getParameters()

Returns the parameters associated with this object. The returned list is intended for external use in documentation; the parameter objects returned may or may not be those used for obtaining values from a particular execution environment. For this reason they may have names which are symbolic, that is, represent possible parameter names. Since actual parameter names are dynamically determined from other parameter names, it is not possible to return an exhaustive list.

Returns:

array of parameters to be used for documentation

getPlotState

public PlotState getPlotState(Environment env)
                       throws TaskException

Returns a configured PlotState obtained from parameter values specified by the given execution environment.

Parameters:

env - execution environment

Throws:

TaskException

createPlotState

protected PlotState createPlotState()

Creates a new unconfigured PlotState object suitable for configuration by this factory.

Returns:

plot state

configurePlotState

protected void configurePlotState(PlotState state,
                                  Environment env)
                           throws TaskException

Configures a PlotState object by examining parameter values in a given execution environment. Such an object was presumably previously created by a call to createPlotState().

Parameters:

state - plot state to configure

env - execution environment

Throws:

TaskException

createPlotData

protected TablePlotData createPlotData(Environment env,
                                       String tLabel,
                                       StarTable table,
                                       String[] setExprs,
                                       String[] setNames,
                                       Style[] setStyles,
                                       String labelExpr,
                                       String[] coordExprs,
                                       String[] errExprs)
                                throws TaskException,
                                       gnu.jel.CompilationException

Constructs a PlotData object. Called by configurePlotState(uk.ac.starlink.ttools.plot.PlotState, uk.ac.starlink.task.Environment); may be overridden by subclasses.

Parameters:

env - execution environment

tLabel - table identifier suffix

table - input table

setExprs - nset-element JEL boolean-valued expression array for set inclusion

setNames - nset-element set name array

setStyles - nset-elemnt set style array

labelExpr - JEL expression for text label

coordExprs - ndim-element JEL double-valued expression array for coordinate values

errExprs - nerr-element expression(s) array for error values

Returns:

new PlotData object based on parameters

Throws:

TaskException

gnu.jel.CompilationException

configureFromData

public void configureFromData(PlotState state,
                              TablePlot plot)
                       throws TaskException,
                              IOException

Performs additional plot state configuration which may require a pass through the data. This may do zero or more of the following:

1. Configure the range attributes of the given state, ensuring that they have non-NaN values.

Parameters:

state - plot state whose ranges will to be configured

plot - table plot for which configuration is to be done

Throws:

TaskException

IOException

calculateBounds

public DataBounds calculateBounds(PlotState state,
                                  TablePlot plot)

Calculates data bounds for a given data set as appropriate for the given plot.

Parameters:

state - plot state

plot - plot object

requiresConfigureFromBounds

protected boolean requiresConfigureFromBounds(PlotState state)

Indicates whether it is necessary to calculate the DataBounds for a given PlotState before it is ready to be used. Iff true is returned, then configureFromBounds(uk.ac.starlink.ttools.plot.PlotState, uk.ac.starlink.ttools.plot.DataBounds) will be called later.

Parameters:

state - plot state

Returns:

whether configureFromBounds should be called

configureFromBounds

protected void configureFromBounds(PlotState state,
                                   DataBounds bounds)
                            throws TaskException

Updates a plot state generated by this factory with information generated from a first pass through the data.

Parameters:

state - plot state to update

bounds - data bounds calculated by a pass through the data

Throws:

TaskException

requiresAdjustFromData

public boolean requiresAdjustFromData(Style style)

Indicates whether a given style generated by this factory needs to be updated with information from a first pass through the data. Iff true is returned, then adjustFromData(uk.ac.starlink.ttools.plot.Style, int, uk.ac.starlink.ttools.plot.DataBounds) will be called later.

Parameters:

style - plot style to consider

Returns:

true iff adjustFromData should be called on style

adjustFromData

public Style adjustFromData(Style style,
                            int iset,
                            DataBounds bounds)

Updates a plotting style generated by this factory with information generated from a first pass through the data.

Parameters:

style - plot style to update

iset - set index for which style is used

bounds - data bounds calculated by a pass through the data

createStyleFactory

protected StyleFactory createStyleFactory(String prefix)

Constructs a style factory which can retrieve a plotting style suitable for use with this factory from the environment.

Parameters:

prefix - prefix to use for all style-type variables