/**
* Returns a parameter giving expressions for the error values associated with a given coordinate
* axis, indexed by a table-identifying label. The value taken by this parameter is a string which
* is either a single (symmetric) numeric error expression or two comma-separated error
* expressions.
*
* @param axName axis label
* @param tlabel table identifier
* @return error pair parameter
*/
private Parameter createErrorParameter(String axName, String tlabel) {
Parameter param = new Parameter(axName.toLowerCase() + "error" + tlabel);
param.setUsage("<expr>|[<lo-expr>],[<hi-expr>]");
param.setPrompt("Error bound(s) in " + axName + " for table " + tlabel);
param.setNullPermitted(true);
param.setDescription(
new String[] {
"<p>Gives expressions for the errors on " + axName,
"coordinates for table " + tlabel + ".",
"The following forms are permitted:",
"<ul>",
"<li><code><expr></code>: symmetric error value</li>",
"<li><code><lo-expr>,<hi-expr></code>:"
+ "distinct lower and upper error values</li>",
"<li><code><lo-expr>,</code>: lower error value only</li>",
"<li><code>,<hi-expr></code>: upper error value only</li>",
"<li><code>null</code>: no errors</li>",
"</ul>",
"The expression in each case is a numeric algebraic expression",
"based on column names",
"as described in <ref id='jel'/>.",
"</p>",
});
return param;
}
/**
* Constructor.
*
* @param axName axis name
*/
public AxisParameterSet(String axName) {
axName_ = axName.toLowerCase();
loParam_ = new DoubleParameter(axName_ + "lo");
loParam_.setPrompt("Lower bound for " + axName_ + " axis");
loParam_.setDescription(
new String[] {
"<p>The lower limit for the plotted " + axName_ + " axis.",
"If not set, a value will be chosen which is low enough",
"to accommodate all the data.",
"</p>",
});
loParam_.setNullPermitted(true);
hiParam_ = new DoubleParameter(axName_ + "hi");
hiParam_.setPrompt("Upper bound for " + axName_ + " axis");
hiParam_.setDescription(
new String[] {
"<p>The upper limit for the plotted " + axName_ + " axis.",
"If not set, a value will be chosen which is high enough",
"to accommodate all the data.",
"</p>",
});
hiParam_.setNullPermitted(true);
logParam_ = new BooleanParameter(axName_ + "log");
logParam_.setPrompt("Logarithmic scale on " + axName_ + " axis?");
logParam_.setDescription(
new String[] {
"<p>If false (the default), the scale on the " + axName_,
"axis is linear; if true it is logarithmic.",
"</p>",
});
logParam_.setDefault("false");
flipParam_ = new BooleanParameter(axName_ + "flip");
flipParam_.setPrompt("Reversed direction on " + axName_ + "axis?");
flipParam_.setDescription(
new String[] {
"<p>If set true, the scale on the " + axName_ + " axis",
"will increase in the opposite sense from usual",
"(e.g. right to left rather than left to right).",
"</p>",
});
flipParam_.setDefault("false");
labelParam_ = new Parameter(axName_ + "label");
labelParam_.setPrompt("Label for axis " + axName_);
labelParam_.setDescription(
new String[] {
"<p>Specifies a label to be used for annotating axis " + axName_ + ".",
"A default values based on the plotted data will be used",
"if no value is supplied for this parameter.",
"</p>",
});
labelParam_.setNullPermitted(true);
}
/**
* Constructs a new subset name parameter.
*
* @param stlabel table/subset parameter label
* @return new subset name parameter
*/
private Parameter createSubsetNameParameter(String stlabel) {
Parameter nameParam = new Parameter(STYLE_PREFIX + "name" + stlabel);
nameParam.setNullPermitted(true);
nameParam.setPrompt("Label for subset " + stlabel);
nameParam.setDescription(
new String[] {
"<p>Provides a name to use for a subset with the symbolic label",
stlabel + ".",
"This name will be used for display in the legend,",
"if one is displayed.",
"</p>",
});
return nameParam;
}
/**
* Constructs a new text label expression parameter.
*
* @param tlabel table parameter label
* @return new text label expression parameter
*/
private Parameter createLabelParameter(String tlabel) {
Parameter labelParam = new Parameter("txtlabel" + tlabel);
labelParam.setPrompt("Label annotating each plotted point");
labelParam.setDescription(
new String[] {
"<p>Gives an expression which will label each plotted point.",
"If given, the text (or number) resulting from evaluating",
"the expression will be written near each point which is",
"plotted.",
"</p>",
});
labelParam.setNullPermitted(true);
return labelParam;
}
/**
* Returns a parameter giving an expression for the coordinate values used by this axis. It is
* indexed by a table-identifying label.
*
* @param tlabel table identifier
* @return parameter giving JEL expression for coordinate data
*/
public Parameter createCoordParameter(String tlabel) {
Parameter param = new Parameter(axName_ + "data" + tlabel);
param.setUsage("<expr>");
param.setPrompt("Value to plot on " + axName_ + " axis" + " for table " + tlabel);
param.setDescription(
new String[] {
"<p>Gives a column name or expression for the " + axName_,
"axis data for table " + tlabel + ".",
"The expression is a numeric algebraic expression",
"based on column names",
"as described in <ref id=\"jel\"/>",
"</p>",
});
return param;
}
/**
* Constructs a new subset inclusion expression parameter.
*
* @param stlabel table/subset parameter label
* @return new subset expression parameter
*/
private Parameter createSubsetExpressionParameter(String stlabel) {
Parameter param = new Parameter(SUBSET_PREFIX + stlabel);
param.setPrompt("Selection criterion for subset " + stlabel);
param.setDescription(
new String[] {
"<p>Gives the selection criterion for the subset labelled",
"\"<code>" + stlabel + "</code>\".",
"This is a boolean expression which may be the name of",
"a boolean-valued column or any other boolean-valued expression.",
"Rows for which the expression evaluates true will be included",
"in the subset, and those for which it evaluates false will not.",
"</p>",
});
param.setUsage("<expr>");
return param;
}
/**
* Obtains the subset definition object from the environment for a given table.
*
* @param env execution environment
* @param tlabel table parameter label
* @param styleFactory factory which can examine the environment for plotting style information
*/
private SubsetDef[] getSubsetDefinitions(
Environment env, String tlabel, StyleFactory styleFactory) throws TaskException {
/* Work out which parameter suffixes are being used to identify
* different subsets for the table with parameter suffix tlabel.
* This is done by finding all the parameters which start
* "subset"+tlabel and pulling off their suffixes. These suffixes
* are then applied to other parameter stems for obtaining other
* per-subset parameter values. */
String[] paramNames = env.getNames();
String stPrefix = SUBSET_PREFIX + tlabel;
String[] subLabels = getSuffixes(paramNames, stPrefix);
Arrays.sort(subLabels);
int nset = subLabels.length;
/* If there are no subsets for this table, consider it the same as
* a single subset with inclusion of all points. */
if (nset == 0) {
Parameter nameParam = createSubsetNameParameter(tlabel);
nameParam.setDefault(tlabel);
String name = nameParam.stringValue(env);
return new SubsetDef[] {
new SubsetDef(tlabel, "true", name, styleFactory.getStyle(env, tlabel)),
};
}
/* If there is at least one subset, gather the information required
* to construct a SubsetDef object describing its characteristics. */
else {
SubsetDef[] sdefs = new SubsetDef[nset];
for (int is = 0; is < nset; is++) {
String stLabel = tlabel + subLabels[is];
String expr = createSubsetExpressionParameter(stLabel).stringValue(env);
Parameter nameParam = createSubsetNameParameter(stLabel);
nameParam.setDefault(expr);
String name = nameParam.stringValue(env);
sdefs[is] = new SubsetDef(stLabel, expr, name, styleFactory.getStyle(env, stLabel));
}
return sdefs;
}
}
/**
* Configures a PlotState object by examining parameter values in a given execution environment.
* Such an object was presumably previously created by a call to {@link #createPlotState}.
*
* @param state plot state to configure
* @param env execution environment
*/
protected void configurePlotState(PlotState state, Environment env) throws TaskException {
int mainNdim = mainDimNames_.length;
state.setMainNdim(mainNdim);
String[] paramNames = env.getNames();
/* Work out which parameter suffixes are being used to identify
* different tables. This is done by finding all the parameters
* which start "table" and pulling off their suffixes.
* These suffixes are then applied to other parameter stems
* for obtaining other per-table parameter values. */
String tPrefix = TABLE_PREFIX;
String[] tableLabels = getSuffixes(paramNames, tPrefix);
if (tableLabels.length == 0) {
tableLabels = new String[] {""};
}
Arrays.sort(tableLabels);
int nTable = tableLabels.length;
/* Get a list of all the axis names being used. This includes the
* main axes and any auxiliary ones. */
List axNameList = new ArrayList();
axNameList.addAll(Arrays.asList(mainDimNames_));
String[] auxLabels;
if (useAux_) {
auxLabels = AxisParameterSet.getAuxAxisNames(paramNames);
Arrays.sort(auxLabels);
for (int ia = 0; ia < auxLabels.length; ia++) {
axNameList.add("aux" + auxLabels[ia]);
}
} else {
auxLabels = new String[0];
}
String[] allAxNames = (String[]) axNameList.toArray(new String[0]);
int allNdim = allAxNames.length;
/* Assemble parameter groups corresponding to each axis. */
AxisParameterSet[] axParamSets = new AxisParameterSet[allNdim];
for (int idim = 0; idim < allNdim; idim++) {
axParamSets[idim] = new AxisParameterSet(allAxNames[idim]);
}
/* Construct a PlotData object for the data obtained from each table. */
PlotData[] datas = new PlotData[nTable];
String[] coordExprs0 = null;
StyleFactory styleFactory = createStyleFactory(STYLE_PREFIX);
List setLabelList = new ArrayList();
for (int itab = 0; itab < nTable; itab++) {
String tlabel = tableLabels[itab];
StarTable table = getInputTable(env, tlabel);
String[] coordExprs = new String[allNdim];
for (int idim = 0; idim < allNdim; idim++) {
Parameter coordParam = axParamSets[idim].createCoordParameter(tlabel);
if (idim >= mainNdim) {
coordParam.setNullPermitted(true);
}
coordExprs[idim] = coordParam.stringValue(env);
}
String[] errExprs = new String[errNdim_];
for (int idim = 0; idim < errNdim_; idim++) {
errExprs[idim] = createErrorParameter(mainDimNames_[idim], tlabel).stringValue(env);
}
String labelExpr = useLabel_ ? createLabelParameter(tlabel).stringValue(env) : null;
SubsetDef[] subsetDefs = getSubsetDefinitions(env, tlabel, styleFactory);
int nset = subsetDefs.length;
String[] setExprs = new String[nset];
String[] setNames = new String[nset];
Style[] setStyles = new Style[nset];
for (int is = 0; is < nset; is++) {
SubsetDef sdef = subsetDefs[is];
setLabelList.add(sdef.label_);
setExprs[is] = sdef.expression_;
setNames[is] = sdef.name_;
setStyles[is] = sdef.style_;
}
try {
TablePlotData plotData =
createPlotData(
env, tlabel, table, setExprs, setNames, setStyles, labelExpr, coordExprs, errExprs);
plotData.checkExpressions();
datas[itab] = plotData;
} catch (CompilationException e) {
throw new TaskException(e.getMessage(), e);
}
if (itab == 0) {
coordExprs0 = coordExprs;
}
}
/* Set up a plot data object which is an aggregation of the data
* objects from all the input tables. */
PlotData plotData = new MultiPlotData(datas);
/* Rearrange the set plot order if required. */
StringBuffer seqbuf = new StringBuffer();
for (Iterator it = setLabelList.iterator(); it.hasNext(); ) {
seqbuf.append(it.next());
if (it.hasNext()) {
seqbuf.append(seqParam_.getValueSeparator());
}
}
String seqDefault = seqbuf.toString();
seqParam_.setDefault(seqDefault);
String seqString = seqParam_.stringValue(env);
if (seqString != null && !seqString.equals(seqDefault)) {
String[] setLabels =
seqParam_.stringValue(env).split("\\Q" + seqParam_.getValueSeparator() + "\\E");
int nset = setLabels.length;
for (int is = 0; is < nset; is++) {
setLabels[is] = setLabels[is].trim();
}
int[] isets = new int[nset];
for (int is = 0; is < nset; is++) {
String label = setLabels[is];
isets[is] = setLabelList.indexOf(label);
if (isets[is] < 0) {
String msg =
"Unknown set identifier \"" + label + "\"; " + "known labels are " + setLabelList;
throw new ParameterValueException(seqParam_, msg);
}
}
plotData = new SubsetSelectionPlotData(plotData, isets);
}
/* Store the calculated plot data object in the plot state. */
state.setPlotData(plotData);
/* Configure other per-axis properties. */
boolean[] logFlags = new boolean[allNdim];
boolean[] flipFlags = new boolean[allNdim];
double[][] ranges = new double[allNdim][];
String[] labels = new String[allNdim];
for (int idim = 0; idim < allNdim; idim++) {
AxisParameterSet axParamSet = axParamSets[idim];
logFlags[idim] = axParamSet.logParam_.booleanValue(env);
flipFlags[idim] = axParamSet.flipParam_.booleanValue(env);
ranges[idim] =
new double[] {
axParamSet.loParam_.doubleValue(env), axParamSet.hiParam_.doubleValue(env),
};
String labelDefault = coordExprs0[idim];
if (labelDefault == null || labelDefault.trim().length() == 0) {
labelDefault = idim < mainNdim ? mainDimNames_[idim] : "Aux " + (idim - mainNdim + 1);
}
axParamSet.labelParam_.setDefault(labelDefault);
labels[idim] = axParamSet.labelParam_.stringValue(env);
}
state.setLogFlags(logFlags);
state.setFlipFlags(flipFlags);
state.setRanges(ranges);
state.setAxisLabels(labels);
/* Configure per-auxiliary axis properties. */
Shader[] shaders = new Shader[auxLabels.length];
ShaderParameter[] shaderParams = createShaderParameters(auxLabels);
for (int ia = 0; ia < auxLabels.length; ia++) {
shaders[ia] = shaderParams[ia].shaderValue(env);
}
state.setShaders(shaders);
/* Configure other properties. */
state.setGrid(gridParam_.booleanValue(env));
state.setAntialias(aaParam_.booleanValue(env));
}
/**
* 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.
*
* @return array of parameters to be used for documentation
*/
public Parameter[] getParameters() {
/* Create and return a list of parameters some of which have
* "example" suffixes. In some cases the parameters which
* supply actual values to this factory are constructed as
* required elsewhere in this class. */
String tSuffix = TABLE_VARIABLE;
String stSuffix = TABLE_VARIABLE + SUBSET_VARIABLE;
String auxAxName = AUX_PREFIX + AUX_VARIABLE;
/* Per-table input parameters. */
InputTableParameter inParam = createTableParameter(tSuffix);
FilterParameter filterParam = createFilterParameter(tSuffix);
List paramList = new ArrayList();
paramList.add(inParam);
paramList.add(inParam.getFormatParameter());
paramList.add(inParam.getStreamParameter());
paramList.add(filterParam);
/* Per-axis parameters. */
List axParamSetList = new ArrayList();
for (int idim = 0; idim < mainDimNames_.length; idim++) {
axParamSetList.add(new AxisParameterSet(mainDimNames_[idim]));
}
if (useAux_) {
axParamSetList.add(new AxisParameterSet(auxAxName));
}
AxisParameterSet[] axParamSets =
(AxisParameterSet[]) axParamSetList.toArray(new AxisParameterSet[0]);
int allNdim = axParamSets.length;
Parameter[][] axScalarParams = new Parameter[allNdim][];
for (int idim = 0; idim < allNdim; idim++) {
AxisParameterSet axParamSet = axParamSets[idim];
paramList.add(axParamSet.createCoordParameter(tSuffix));
axScalarParams[idim] = axParamSet.getScalarParameters();
}
int nScalarParam = axScalarParams[0].length; // same for all elements
for (int ip = 0; ip < nScalarParam; ip++) {
for (int idim = 0; idim < allNdim; idim++) {
paramList.add(axScalarParams[idim][ip]);
}
}
for (int idim = 0; idim < errNdim_; idim++) {
paramList.add(createErrorParameter(mainDimNames_[idim], tSuffix));
}
if (useAux_) {
Parameter shaderParam = createShaderParameters(new String[] {AUX_VARIABLE})[0];
assert shaderParam.getDefault() != null;
paramList.add(shaderParam);
}
/* Other parameters. */
if (useLabel_) {
paramList.add(createLabelParameter(tSuffix));
}
paramList.add(createSubsetExpressionParameter(stSuffix));
paramList.add(createSubsetNameParameter(stSuffix));
paramList.addAll(Arrays.asList(createStyleFactory(STYLE_PREFIX).getParameters(stSuffix)));
paramList.add(gridParam_);
paramList.add(aaParam_);
paramList.add(seqParam_);
return (Parameter[]) paramList.toArray(new Parameter[0]);
}