From autoplot.org

Purpose: We need a document describing commands available when scripting. This will cover commands available when no imports are used.

Audience: Scientists and software people wanting to use Autoplot for scripting.

Note: Some of the non-technical aspects of this page are being migrated to scripting.

See also scripting, http://autoplot.org/data/jyds, and http://autoplot.org/data/tools/.

More scripts in the SVN repository: [1] (All scripts before and including areaSelect.py have been verified to work with current DOM).

1. Introduction to Scripting

Autoplot uses the popular language Python to provide scripting for various applications. For example, a script can load the data from two data sources and combine them to make a new dataset. Scripts can also be used to run Autoplot automatically, for example, to create a series of images to we call a pngwalk. Autoplot creates the scripting environment where the user's commands are executed, and adds useful commands to the environment. Also, Autoplot's data model, or data representation, is adapted so that arithmetic operators can be used directly on the data as if they were number arrays in IDL or Matlab. (But unlike IDL and Matlab, they carry with them descriptive metadata and physical units.)

For example, consider this script:

ds1= getDataSet( 'http://autoplot.org/data/image/Capture_00158.jpg?channel=greyscale' )
ds2= getDataSet( 'http://autoplot.org/data/image/Capture_00159.jpg?channel=greyscale' )
result= abs( ds2- ds1 )

It should be fairly clear what the script does: load in two grayscale views of images, and then assign the absolute difference to the variable result. This variable could then be plotted, for example, or we might look for the greatest difference.

Scripting is used in three contexts: the Data Source Context, the Application Context, and the third is a scripting context using the --script at the launch command. In the "Data Source" context, the output of the script is expected to be named result or data, and this script variable is plotted in the canvas tab. In the "Application" context, Jython commands may be used to manipulate the content of the canvas. The third context can essentially be used to create new custom applications, and it is not discussed any further here.

1.1. Script Editor

Autoplot provides a editor GUI for working with scripts. Selecting Options->Enable Feature->Script Panel will reveal a tab named "script" where scripts may be entered and executed. The editor provides simple completions for this environment. To see completions, enter TAB or ctrl-space. (Note TAB can use reset to the TAB character whitespace with a preference.)

1.2. Data Source Context

Here scripts can load in data and return a new dataset (or datasets). This is the "data source context" and these are files that can be used as if they were datasets. If the above script were saved in the file "http://www.autoplot.org/data/imageDiff.jyds," then http://www.autoplot.org/data/imageDiff.jyds?result would refer to this dataset. This allows scientists to publish operations done to data as well as data itself. Note these scripts are unaware of the Autoplot application, they can load and operate on data, but they cannot plot it. Commands available in this context are described below under the section "Ops"

Script examples: [2] and cookbook#Scripting.

1.3. Application Context

These scripts access the application itself. Take for example the following application:

trs= generateTimeRanges( '%Y-%m-%d', '2010-January' )
for tr in trs:
   dom.timeRange= DatumRangeUtil.parseTimeRange(tr)
   writeToPng( '/tmp/%s.png' % tr )

This script would run the application through each day of the month January 2010, making images of each day. All commands are available in this context.

Examples are available at [3] and cookbook#Scripting. This javadoc describes the commands available in this Jython Application Context.

1.4. Building Scripts

1.4.1. Use of Progress Monitor

All scripts have a progress monitor that can be used to provide feedback to users. This is the variable 'monitor' and is used like so:

monitor.setTaskSize(200)                     # the number of steps (arbitary units)
monitor.started()                            # the task is started.  

for i in xrange(200):
   if ( monitor.isCancelled() ): break       # if not called, the cancel button will be insensitive
   monitor.setProgressMessage('at %d' % i)   # this describes actions done to perform the task.  
   monitor.setTaskProgress(i)
   java.lang.Thread.sleep(100);

monitor.finished()     # indicate the task is complete

1.4.2. Getting Input

s= getParam( 's', 'deflt', 'label to describe' )   # gets a string parameter, with default value "deflt"
f= getParam( 'f', 2.34, 'label to describe' )      # gets a float parameter, with default value 2.34

Autoplot will look for this in scripts and automatically add to GUI. The type is determined by the default value.

This is mostly used for .jyds scripts that create new datasets, but all script types can use this command. The jyds plugin creates a GUI by looking for these calls. Note the GUI is created by parsing but not executing the Jython code, so do not put variables and expressions in the getParam call. For example: Autoplot will fail to make a GUI from this:

max= getParam( 'max', 10, 'the maximum value' )
i= getParam( 'i', max, 'the value' ) 

Enumerations are supported as well, where a list of possible values is enumerated. For example:

sensor= getParam( 'sensor', 'left', 'sensor antenna', ['left','right'] )

will get the parameter sensor, which can be either left or right (with left as the default). When a GUI is created, a droplist of possible values is used instead of a text entry field.

TODO: Application-context scripts can use get param as well. Right now the default value is always used, but soon a gui will be created before running the script.

1.4.3. Handling Exceptions

Often a process will typically execute, but we know exceptional cases may occur and we want to invoke special code to handle them. For example, I may open a sequence of files, and if one is misformatted, I want to log it to a file and carry on with processing other files.

In Python we use try/exception blocks, something like:

try: 
  plot( uri )
  writeToPng( '/tmp/pngs/%s.png' % uri )
except Exception, ex:
  ERROR.write( '# unable to plot ' + uri + ' because of ' + str(ex) )

Note most of the functions called are actually Java procedures and throw Java exceptions. Unfortunately, the Python catch doesn't catch Java exceptions, and a second except block is needed:

try: 
  plot( uri )
  writeToPng( '/tmp/pngs/%s.png' % uri )
except Exception, ex:
  ERROR.write( '# unable to plot ' + uri + ' because of ' + str(ex) )
except java.lang.Exception, ex:
  ERROR.write( '# unable to plot ' + uri + ' because of ' + str(ex) )

1.4.3.1. Throwing (or Raising) Exceptions

Sometimes we want our process to stop and let the user know that something went wrong, so we throw an exception. This is done like so:

if ( ds.length()==0 ):
  raise Exception("Dataset is empty")

1.4.4. Adding to the Tools menu

Application-context scripts can be added to the Autoplot GUI by putting them in the HOME/autoplot_data/tools/ folder. http://autoplot.org/data/tools/ shows some example scripts.

2. Commands

These are commands that are available to scripts in Autoplot. Autoplot's scripting environment is Jython (Python in Java) with a set of codes that are automatically imported to keep scripts simple.

The Java types that each command takes are indicated, because it's easier to produce this document and if these commands are used in Java instead if Jython, the types must be followed. Jython is able to make some conversions to correctly combine data.

3. ScriptContext Commands

These are extra commands that are added when running in the script context, such as writeToPng. These commands are not available in JythonDataSources, which load data to make a new data set.

3.1. getViewWindow

public static java.awt.Window getViewWindow()

return the Window for the application, to be used for dialogs. See createGui(), which creates the view.

3.2. setCanvasSize

public static void setCanvasSize(int width,
                                int height)

set the size of the canvas. This is only used when the GUI is not used, and in headless mode, otherwise the GUI controls the size of the canvas.

Parameters:

• width - the width of the canvas
• height - the height of the canvas

3.3. plot

A number of plot commands are available.

3.3.1. plot the URI

public static void plot(java.lang.String surl)

bring up the autoplot with the specified URL.

Parameters:

• surl - a URI or vap file

3.3.2. plot one URI against another

public static void plot(java.lang.String surl1,
                       java.lang.String surl2)

plot one URI against another. No synchronization is done, so beware. Introduced for testing non-time axis TSBs.

Parameters:

• surl1 - the independent variable dataset (generally used for X)
• surl2 - the dependent variable dataset (generally used for Y, but can be rank 2).

3.3.3. plot the URI at position

public static void plot(int chNum,
                       java.lang.String surl)

bring up the autoplot with the specified URL. This may be a little confusing, because it replaces the datasource with the given number, which would typically correspond to the position on the page.

Parameters:

• chNum - the data source number to reset the URI.
• surl - a URI to use

3.3.4. plot the URI at position with this label

public static void plot(int chNum,
                       java.lang.String label,
                       java.lang.String surl)

bring up the autoplot with the specified URL.

Parameters:

• chNum - the data source number to reset the URI.
• label - for the plot.
• surl - a URI to use

3.3.5. plot this dataset

public static void plot(org.virbo.dataset.QDataSet ds)

plot the dataset in the first dataSource node.

Parameters:

• ds - QDataSet to plot

3.3.6. plot one dataset against another

public static void plot(org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y)

plot the dataset in the first dataSource node.

Parameters:

• x - QDataSet for the independent parameter
• y - QDataSet for the dependent parameter

3.3.7. plot one dataset Z against X and Y

public static void plot(org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y,
                       org.virbo.dataset.QDataSet z)

plot the dataset in the first dataSource node.

Parameters:

• x - QDataSet for the independent parameter for the X values
• y - QDataSet for the independent parameter for the Y values
• z - Rank 1 or Rank 2 QDataSet for the dependent parameter

3.3.8. plot one dataset in this position

public static void plot(int chNum,
                       org.virbo.dataset.QDataSet ds)

plot the dataset in the specified dataSource node.

Parameters:

• ds - dataset to plot.

3.3.9. plot one dataset against another in this position

public static void plot(int chNum,
                       org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y)

plot the dataset in the specified dataSource node.

Parameters:

• x - QDataSet for the independent parameter for the X values
• y - QDataSet for the independent parameter for the Y values

3.3.10. plot one dataset Z against X and Y in this position

public static void plot(int chNum,

                       org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y,
                       org.virbo.dataset.QDataSet z)

plot the dataset in the specified dataSource node.

Parameters:

• x - QDataSet for the independent parameter for the X values
• y - QDataSet for the independent parameter for the Y values
• z - Rank 1 or Rank 2 QDataSet for the dependent parameter

3.3.11. plot this URI at this position

public static void plot(int chNum,
                       java.lang.String label,
                       org.virbo.dataset.QDataSet ds)

bring up the autoplot with the dataset

Parameters:

• chNum - the data source number to reset the URI.
• label - for the plot.
• ds - the dataset to use.

3.3.12. plot X vs Y with this label at this position

public static void plot(int chNum,
                       java.lang.String label,
                       org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y)

plot the dataset in the specified dataSource node.

Parameters:

• x - QDataSet for the independent parameter for the X values
• y - QDataSet for the independent parameter for the Y values

3.3.13. plot one dataset Z against X and Y in this position with this label

public static void plot(int chNum,
                       java.lang.String label,
                       org.virbo.dataset.QDataSet x,
                       org.virbo.dataset.QDataSet y,
                       org.virbo.dataset.QDataSet z)

plot the dataset in the specified dataSource node.

Parameters:

• label - the label for the dependent parameter
• x - QDataSet for the independent parameter for the X values
• y - QDataSet for the independent parameter for the Y values
• z - Rank 1 or Rank 2 QDataSet for the dependent parameter

3.4. setStatus

public static void setStatus(java.lang.String message)

set the autoplot status bar string. Use the prefixes "busy:", "warning:" and "error:" to set icons.

Parameters:

• message - message to display, possibly with "busy:" "warning:" or "error:" prefix.

3.5. addTab

public static void addTab(java.lang.String label,
                         javax.swing.JComponent c)

add a tab to the running application. A new tab will be added with the label.

Parameters:

• label - the label for the component.
• c - the component to add.

3.6. setRenderStyle

public static void setRenderStyle(java.lang.String name)

• Set the style used to render the data using a string identifier: spectrogram, series, scatter, histogram, fill_to_zero, digital

Parameters:

• name - string name of the plot style.

3.7. peekAt

public static void peekAt(java.lang.Object o)
                  throws java.io.IOException

This is intended to be used with a debugger. The developer should put a breakpoint at the out.write statement, and then call peekAt from the script.

Parameters:

• o - any object we want to look at.

3.8. writeToPng

public static void writeToPng(java.lang.String filename)

write out the current canvas to a png file. TODO: bug 3113441: this has issues with the size. It's coded to get the size from the DOM, but if it is fitted and has a container it must get size from the container. Use writeToPng( filename, width, height ) instead for now. See writeToPdf(String filename), which appears to have a fix for this that would affect how this is resolved.

Parameters:

• filename - The name of a local file

3.9. writeToPng

public static void writeToPng(java.lang.String filename,
                             int width,
                             int height)

write out the current canvas to a png file. TODO: bug 3113441: this has issues with the size. It's coded to get the size from the DOM, but if it is fitted and has a container it must get size from the container. Use writeToPng( filename, width, height ) instead for now. See writeToPdf(String filename), which appears to have a fix for this that would affect how this is resolved.

Parameters:

• filename - The name of a local file
• width - the width in pixels of the png
• height - the height in pixels of the png

3.10. writeToPng

public static void writeToPng(java.io.OutputStream out)

write out the current canvas to stdout. This is introduced to support servers. TODO: this has issues with the size. See writeToPng(filename).

Parameters:

• OutputStream - out

3.11. writeToPdf

public static void writeToPdf(java.lang.String filename)

write out the current canvas to a pdf file. TODO: this has issues with the size. See writeToPng(filename). It looks like this might be handled here

Parameters:

• filename - the local file to write the file.

3.12. writeToPdf

public static void writeToPdf(java.io.OutputStream out)

write out the current canvas to a pdf to the output stream. This is to support servers. TODO: this has issues with the size. See writeToPng(filename). It looks like this might be handled here

Parameters:

• out - the OutputStream

3.13. writeToBufferedImage

public static java.awt.image.BufferedImage writeToBufferedImage(Application applicationIn)

creates a BufferedImage from the provided DOM. This blocks until the image is ready. TODO: this has issues with the size. See writeToPng(filename). It looks like this might be handled here

Parameters:

• applicationIn -

3.14. getTimeRangesFor

public static java.lang.String[] getTimeRangesFor(java.lang.String surl,
                                                 java.lang.String timeRange,
                                                 java.lang.String format)

return an array of URLs that match the spec for the time range provided. For example,

uri= 'http://cdaweb.gsfc.nasa.gov/istp_public/data/polar/hyd_h0/$Y/po_h0_hyd_$Y$m$d_v01.cdf?ELECTRON_DIFFERENTIAL_ENERGY_FLUX'
xx= getTimeRangesFor( uri, '2000-jan', '$Y-$d-$m' )
for x in xx:
   print x
        

Parameters:

• surl - an Autoplot uri with an aggregation specifier.
• timeRange - a string that is parsed to a time range, such as "2001"
• format - format for the result, such as "%Y-%m-%d"

Returns:

• a list of URLs without the aggregation specifier.

3.15. generateTimeRanges

public static java.lang.String[] generateTimeRanges(java.lang.String spec,
                                                   java.lang.String srange)
                                            throws java.text.ParseException

Given a spec to format timeranges and a range to contain each timerange, produce a list of all timeranges covering the range formatted with the spec. For example, generateTimeRanges( "%Y-%m-%d", "Jun 2009" ) would result in 2009-06-01, 2009-06-02, ..., 2009-06-30.

Parameters:

• spec - such as "%Y-%m". Note specs like "%Y%m" will not be parsable.
• srange - range limiting the list, such as "2009"

Returns:

• a string array of formatted time ranges, such as [ "2009-01", "2009-02", ..., "2009-12" ]

3.16. setTitle

public static void setTitle(java.lang.String title)

set the title of the focus plot.

Parameters:

• title -

3.17. createGui

public static void createGui()

create a model with a GUI presentation layer. If the GUI is already created, then this does nothing.

3.18. getApplicationModel

public static ApplicationModel getApplicationModel()

returns the internal application model (the object that does all the business). This provides access to the internal model for power users. Note the applicationModel provides limited access, and the DOM now provides full access to the application.

Returns:

• ApplicationModel object

3.19. isModelInitialized

public static boolean isModelInitialized()

provide way to see if the model is already initialized (e.g. for clone application)

Returns:

• true is the model is already initialized.

3.20. bind

public static void bind(java.lang.Object src,
                       java.lang.String srcProp,
                       java.lang.Object dst,
                       java.lang.String dstProp)

binds two bean properties together. Bindings are bidirectional, but the initial copy is from src to dst. In MVC terms, src should be the model and dst should be a view. The properties must fire property change events for the binding mechanism to work. Example:

bind( dom.plots[0], "title", dom.plots[0].getYaxis(), "label" )
dom.plots[0].title= 'My Data'

Parameters:

• src - java bean such as model.getPlotDefaults()
• srcProp - a property name such as "title"
• dst - java bean such as model.getPlotDefaults().getXAxis()
• dstProp - a property name such as "label"

3.21. dumpToQStream

public static void dumpToQStream(org.virbo.dataset.QDataSet ds,
                                java.io.OutputStream out,
                                boolean ascii)

serializes the dataset to a QStream, a self-documenting, streaming format useful for moving datasets.

ds= getDataSet('http://autoplot.org/data/somedata.cdf?BGSEc')
from java.lang import System
dumpToQStream( ds, System.out, True )
        

Parameters:

• ds - The dataset to stream. Note all schemes should be streamable, but some bugs exist that may prevent this.
• output - stream, such as "System.out"
• ascii - use ascii transfer types, otherwise binary are used.

3.22. dumpToDas2Stream

public static void dumpToDas2Stream(org.virbo.dataset.QDataSet ds,
                                   boolean ascii)

serializes the dataset to a das2stream, a well-documented, open, streaming data format. (that's a joke.) Das2Streams are the legacy stream format used by the Plasma Wave Groups's server, and can serialize a limited set of QDataSets. QStreams were introduced to allow streaming of any QDataSet, see dumpToQStream. Currently, to keep the channel open, the stream is created in a buffer and then the buffer is sent. TODO: write a stream-producing code that doesn't close the output stream. (TODO: does it still do this?)

Parameters:

• ds - QDataSet
• ascii - use ascii transfer types, otherwise binary are used.

3.23. dumpToDas2Stream

public static void dumpToDas2Stream(org.virbo.dataset.QDataSet ds,
                                   java.lang.String file,
                                   boolean ascii)

serializes the dataset to a das2stream, a well-documented, open, streaming data format. (that's a joke.) Currently, to keep the channel open, the stream is created in a buffer and then the buffer is sent. TODO: write a stream-producing code that doesn't close the output stream.

Parameters:

• ds -
• file - the file target for the stream.
• ascii - use ascii transfer types.

3.24. formatDataSet

public static void formatDataSet(org.virbo.dataset.QDataSet ds,
                                java.lang.String file)
                         throws java.lang.Exception

Export the data into a format implied by the filename extension. See the export data dialog for additional parameters available for formatting. For example:

ds= getDataSet('http://autoplot.org/data/somedata.cdf?BGSEc')
formatDataSet( ds, 'vap+dat:file:/home/jbf/temp/foo.dat?tformat=minutes&format=6.2f')
        

Parameters:

• ds - QDataSet
• file - local file name that is the target

3.25. getDocumentModel

public static Application getDocumentModel()

get the document model (DOM). This may initialize the model, in which case defaults like the cache directory are set.

3.26. save

public static void save(java.lang.String filename)

save the current state as a .vap file

Parameters:

• filename - local file where the vap should be saved.

3.27. getCompletions

public static java.lang.String[] getCompletions(java.lang.String file)

return a list of completions. I was talking to Tom N. who was looking for this to get a list of CDF variables, and realized this would be useful in the IDL context as well as python scripts. This will perform the completion for where the carot is at the end of the string.

Parameters:

• file, - for example "http://autoplot.org/data/somedata.cdf?"

Returns:

• list of completions, containing the entire URI.

3.28. load

public static void load(java.lang.String filename)

load the .vap file. This is implemented by calling plot on the URI.

Parameters:

• filename - the vap file to load

3.29. reset

public static void reset()

reset the application to its initial state.

3.30. close

protected static void close()

called when the application closes so if we reopen it will be in a good state.

4. Ops

These are QDataSet operators imported from org.virbo.dsops.Ops. Parenthesis enclosing an operator indicate the operator is overloaded to this function, so for example a.add(b) is usually replaced with a+b.

Note that there's a bit of "coersion" supported to make two dataset arguments have the same geometry. For example, you can add two 10-element rank 1 datasets, but you can also add a 10-element rank 1 dataset to a rank 0 dataset. In other words, [1,2,3,4]+[1,1,1,1] is equivalent to [1,2,3,4] + 1 because the 1 is coerced to [1,1,1,1]. Also Python arrays and numbers are automatically converted to QDataSets. Note a dataset must sometimes be explicitly made, and to force python to coerce to it, use the dataset() prefix:

print [1,2,3,4]
print dataset([1,2,3,4])  
print total(dataset([1,2,3,4]))
print total(2 + dataset([1,2,3,4]) )
#(This is in the autoplot2011 version only.)

4.1. Constants

PI = 3.141592653589793

E = 2.718281828459045

4.2. add (+)

public static QDataSet add(QDataSet ds1,
                          QDataSet ds2)

add the two datasets have the same geometry.

Parameters:

• ds1 -
• ds2 -

Returns:

4.3. subtract (-)

public static QDataSet subtract(QDataSet ds1,
                               QDataSet ds2)

subtract one dataset from another.

Parameters:

• ds1 -
• ds2 -

Returns:

4.4. negate (-)

public static QDataSet negate(QDataSet ds1)

return a dataset with each element negated.

Parameters:

• ds1 -

Returns:

4.5. magnitude

public static QDataSet magnitude(QDataSet ds)

return the magnitudes of vectors in a rank 2 or greater dataset. The last index must be a cartesian dimension, so it must have a depend dataset either named "cartesian" or having the property CARTESIAN_FRAME. TODO: check this in the 2011 branch, I think it's removed.

Parameters:

• ds - of Rank N.

Returns:

• ds of Rank N-1.

4.6. total

public static double total(QDataSet ds)

return the total of all the elements in the dataset, returning a rank 0 dataset. If there are invalid measurements, then fill is returned. Does not support BINS or BUNDLE dimensions.

Parameters:

• ds -

Returns:

• the unweighted total of the dataset, or -1e31 if fill was encountered.

4.7. total

public static QDataSet total(QDataSet ds,
                            int dim)

reduce the dataset's rank by totalling all the elements along a dimension. Only QUBEs are supported presently.

Parameters:

• ds - rank N qube dataset. N=1,2,3,4
• dim - zero-based index number.

Returns:

4.8. reduceMax

public static QDataSet reduceMax(QDataSet ds,
                                int dim)

reduce the dataset's rank by reporting the max of all the elements along a dimension. Only QUBEs are supported presently.

Parameters:

• ds - rank N qube dataset.
• dim - zero-based index number.

Returns:

4.9. reduceMin

public static QDataSet reduceMin(QDataSet ds,
                                int dim)

reduce the dataset's rank by reporting the min of all the elements along a dimension. Only QUBEs are supported presently.

Parameters:

• ds - rank N qube dataset.
• dim - zero-based index number.

Returns:

4.10. reduceMean

public static QDataSet reduceMean(QDataSet ds,
                                 int dim)

reduce the dataset's rank by reporting the mean of all the elements along a dimension. Only QUBEs are supported presently.

Parameters:

• ds - rank N qube dataset.
• dim - zero-based index number.

Returns:

4.11. sqrt

public static QDataSet sqrt(QDataSet ds)

element-wise sqrt.

Parameters:

• ds -

Returns:

4.12. abs

public static QDataSet abs(QDataSet ds1)

element-wise abs. For vectors, this returns the length of each element. Note jython conflict needs to be resolved.

Parameters:

• ds1 -

Returns:

4.13. pow (**)

public static QDataSet pow(QDataSet ds1,
                          QDataSet pow)

element-wise pow (** in FORTRAN, ^ in IDL) of two datasets with the same geometry.

Parameters:

• ds1 -
• pow - dataset or scalar

Returns:

4.14. exp

public static QDataSet exp(QDataSet ds)

element-wise exponentiate e**x.

Parameters:

• ds -

Returns:

4.15. exp10

public static QDataSet exp10(QDataSet ds)

element-wise exponentiate 10**x.

Parameters:

• ds -

Returns:

4.16. log

public static QDataSet log(QDataSet ds)

element-wise natural logarithm.

Parameters:

• ds -

Returns:

4.17. log10

public static QDataSet log10(QDataSet ds)

element-wise base 10 logarithm.

Parameters:

• ds -

Returns:

4.18. multiply (*)

public static QDataSet multiply(QDataSet ds1,
                               QDataSet ds2)

element-wise multiply of two datasets with compatible geometry.

Parameters:

• ds -

Returns:

4.19. divide (/)

public static QDataSet divide(QDataSet ds1,
                             QDataSet ds2)

element-wise divide of two datasets with compatible geometry.

Parameters:

• ds -

Returns:

4.20. mod

public static QDataSet mod(QDataSet ds1,
                          QDataSet ds2)

element-wise mod of two datasets with compatible geometry.

Parameters:

• ds -

Returns:

4.21. div

public static QDataSet div(QDataSet ds1,
                          QDataSet ds2)

element-wise div of two datasets with compatible geometry.

Parameters:

• ds -

Returns:

4.22. eq

public static QDataSet eq(QDataSet ds1,
                         QDataSet ds2)

element-wise equality test. 1.0 is returned where the two datasets are equal. Fill is returned where either measurement is invalid.

Parameters:

• ds -

Returns:

4.23. ne

public static QDataSet ne(QDataSet ds1,
                         QDataSet ds2)

element-wise not equal test. 1.0 is returned where elements are not equal. Fill is returned where either measurement is invalid.

Parameters:

• ds1 -
• ds2 -

Returns:

4.24. gt

public static QDataSet gt(QDataSet ds1,
                         QDataSet ds2)

element-wise function returns 1 where ds1>ds2.

Parameters:

• ds1 -
• ds2 -

Returns:

4.25. ge

public static QDataSet ge(QDataSet ds1,
                         QDataSet ds2)

element-wise function returns 1 where ds1>=ds2.

Parameters:

• ds1 -
• ds2 -

Returns:

4.26. lt

public static QDataSet lt(QDataSet ds1,
                         QDataSet ds2)

element-wise function returns 1 where ds1<ds2.

Parameters:

• ds1 -
• ds2 -

Returns:

4.27. le

public static QDataSet le(QDataSet ds1,
                         QDataSet ds2)

element-wise function returns 1 where ds1<=ds2.

Parameters:

• ds1 -
• ds2 -

Returns:

4.28. or

public static QDataSet or(QDataSet ds1,
                         QDataSet ds2)

element-wise logical or function. returns 1 where ds1 is non-zero or ds2 is non-zero.

Parameters:

• ds1 -
• ds2 -

Returns:

4.29. and

public static QDataSet and(QDataSet ds1,
                          QDataSet ds2)

element-wise logical and function. non-zero is true, zero is false.

Parameters:

• ds1 -
• ds2 -

Returns:

4.30. not

public static QDataSet not(QDataSet ds1)

element-wise logical not function. non-zero is true, zero is false.

TODO: This isn't working, use ( ds1.eq(1) ) instead.

Parameters:

• ds1 -
• ds2 -

Returns:

4.31. dindgen

public static QDataSet dindgen(int len0)

returns rank 1 dataset with values [0,1,2,...,len0-1]

Parameters:

• size - the number of elements

Returns:

• rank 1 dataset with values [0,1,2,...,len0-1]

4.32. dindgen

public static QDataSet dindgen(int len0,
                              int len1)

returns rank 2 dataset with values increasing [ [0,1,2], [ 3,4,5] ]

Parameters:

• len0 -
• len1 -

Returns:

4.33. dindgen

public static QDataSet dindgen(int len0,
                              int len1,
                              int len2)

returns rank 3 dataset with values increasing ( [ [ [0,1,2], [ 3,4,5] ], [ [6,7,8] ], ...] )

Parameters:

• len0 -
• len1 -
• len2 -

Returns:

• Rank 3 dataset with elements increasing.

4.34. findgen

public static QDataSet findgen(int len0)

returns rank 1 dataset with values [0,1,2,...]

Parameters:

• size -

Returns:

4.35. findgen

public static QDataSet findgen(int len0,
                              int len1)

returns rank 2 dataset with values increasing [ [0,1,2], [ 3,4,5] ]

Parameters:

• len0 -
• len1 -

Returns:

4.36. findgen

public static QDataSet findgen(int len0,
                              int len1,
                              int len2)

returns rank 3 dataset with values increasing

Returns:

4.37. fltarr

public static QDataSet fltarr(int len0)

create a dataset filled with zeros.

Parameters:

• len0 -

Returns:

4.38. fltarr

public static QDataSet fltarr(int len0,
                             int len1)

4.39. fltarr

public static QDataSet fltarr(int len0,
                             int len1,
                             int len2)

4.40. dblarr

public static QDataSet dblarr(int len0)

create a dataset filled with zeros.

Parameters:

• len0 -

Returns:

4.41. dblarr

public static QDataSet dblarr(int len0,
                             int len1)

4.42. dblarr

public static QDataSet dblarr(int len0,
                             int len1,
                             int len2)

4.43. timegen

public static QDataSet timegen(java.lang.String baseTime,
                              java.lang.String cadence,
                              int len0)

returns rank 1 dataset with values [0,1,2,...]

Parameters:

• baseTime - e.g. "2003-02-04T00:00"
• cadence - e.g. "4.3 sec" "1 day"
• len0 - the number of elements.

Returns:

• rank 1 dataset

4.44. toTimeDataSet

public static QDataSet toTimeDataSet( QDataSet years, QDataSet mons, QDataSet days, QDataSet hour, QDataSet minute, QDataSet second, QDataSet nano )

returns a rank 1 dataset of timetags, by adding the components. Any of the components can be null, except for years and days.

Parameters:

• years - the years. (2010) Less than 100 is interpreted as 19xx.
• mons - the months (1..12), or null. If null, then days are day of year
• days - the day of month (1..28) or day of year.
• hour - null or the hours of the day.
• minute - null or the minutes of the day
• second - null or the seconds of the day
• nano - null or the nanoseconds (1e-9) of the day

Returns:

• a rank 1 dataset with Units.us2000 (non-leap microseconds since 2000-01-01T00:00). Be sure to check the units as a future version may change.

4.45. taggen

public static MutablePropertyDataSet taggen(double base,
                                           double dcadence,
                                           int len0,
                                           org.das2.datum.Units units)

creates tags. First tag will be start and they will increase by cadence. Units specifies the units of each tag.

Parameters:

• start -
• cadence -
• len0 -
• units -

Returns:

4.46. linspace

public static QDataSet linspace(double min,
                               double max,
                               int len0)

return a rank 1 dataset with len0 linearly-spaced values, the first is min and the last is max.

Parameters:

• min - the first value of the series
• max - the last value of the series.
• len0 - the number of values

Returns:

4.47. replicate

public static WritableDataSet replicate(double val,
                                       int len0)

returns rank 1 dataset with value

Parameters:

• val - fill the dataset with this value.
• len0 -

Returns:

4.48. replicate

public static WritableDataSet replicate(double val,
                                       int len0,
                                       int len1)

returns rank 2 dataset filled with value

Parameters:

• val - fill the dataset with this value.
• len0 -
• len1 -

Returns:

4.49. replicate

public static WritableDataSet replicate(double val,
                                       int len0,
                                       int len1,
                                       int len2)

returns rank 3 dataset with filled with value.

Parameters:

• val - fill the dataset with this value.
• len0 -
• len1 -
• len2 -

Returns:

4.50. replicate

public static WritableDataSet replicate(float val,
                                       int len0)

returns rank 1 dataset with value

Parameters:

• val - fill the dataset with this value.
• len0 -

Returns:

4.51. replicate

public static WritableDataSet replicate(float val,
                                       int len0,
                                       int len1)

returns rank 2 dataset filled with value

Parameters:

• val - fill the dataset with this value.
• len0 -
• len1 -

Returns:

4.52. replicate

public static WritableDataSet replicate(float val,
                                       int len0,
                                       int len1,
                                       int len2)

returns rank 3 dataset with filled with value.

Parameters:

• val - fill the dataset with this value.
• len0 -
• len1 -
• len2 -

Returns:

4.53. zeros

public static WritableDataSet zeros(int len0)

return new dataset filled with zeros.

Parameters:

• len0 -

Returns:

4.54. zeros

public static WritableDataSet zeros(int len0,
                                   int len1)

return new dataset filled with zeros.

Parameters:

• len0 -

Returns:

4.55. zeros

public static WritableDataSet zeros(int len0,
                                   int len1,
                                   int len2)

return new dataset filled with zeros.

Parameters:

• len0 -

Returns:

4.56. zeros

public static WritableDataSet zeros(QDataSet ds)

return a new dataset filled with zeroes that has the same geometry as the given dataset. Only supports QUBE datasets.

Parameters:

• ds -

Returns:

• a new dataset with filled with zeroes with the same geometry.

4.57. ones

public static QDataSet ones(int len0)

return new dataset filled with ones.

Parameters:

• len0 -

Returns:

4.58. ones

public static QDataSet ones(int len0,
                           int len1)

return new dataset filled with ones.

Parameters:

• len0 -

Returns:

4.59. ones

public static QDataSet ones(int len0,
                           int len1,
                           int len2)

return new dataset filled with ones.

Parameters:

• len0 -

Returns:

4.60. concatenate

public static QDataSet concatenate(QDataSet ds1,
                                  QDataSet ds2)

concatenates the two datasets together, appending the datasets on the zeroth dimension. The two datasets must be QUBES have similar geometry on the higher dimensions. If one of the datasets is rank 0 and the geometry of the other is rank 1, then the lower rank dataset is promoted before appending. If the first dataset is null and the second is non-null, then return the second dataset. This was briefly known as "join."

Parameters:

• ds1 - null, or a rank n dataset with dimensions any1,a1,a2,...
• ds2 - A rank n dataset with dimensions any2,a1,a2,...

Returns:

• a rank n dataset with dimensions any1+any2,a1,a2, or just ds2 when ds1 is null.

See also: join

4.61. rand

public static QDataSet rand(int len0)

return returns a rank 1 dataset of random uniform numbers from [0,1].

4.62. randn

public static QDataSet randn(int len0)

return returns a rank 1 dataset of random numbers of a guassian (normal) distribution.

4.63. randomn

public static QDataSet randomn(long seed,
                              int len0)

returns a rank 1 dataset of random numbers of a guassian (normal) distribution. System.currentTimeMillis() may be used for the seed.

Parameters:

• seed -
• len0 -

Returns:

4.64. randomu

public static QDataSet randomu(long seed,
                              int len0)

returns a rank 1 dataset of random numbers of a uniform distribution. System.currentTimeMillis() may be used for the seed.

Parameters:

• seed -
• len0 -

Returns:

4.65. ripples

public static QDataSet ripples( int len0 )

rank 1 dataset for demos.

Parameters:

• len0 -

Returns:

public static QDataSet ripples( int len0, int len1 )

rank 2 dataset for demos.

Parameters:

• len0 -
• len0 -

Returns:

public static QDataSet ripples( int len0, int len1, int len2 )

rank 3 dataset for demos.

Parameters:

• len0 -

Returns:

public static QDataSet ripples( int len0, int len1, int len2, int len3 )

rank 4 dataset for demos.

Parameters:

• len0 -

Returns:

4.66. circle

public static QDataSet circle(double radius)
public static QDataSet circle(String radius)
public static QDataSet circle(QDataSet radius)

return a dataset with X and Y forming a circle, introduced as a convenient way to indicate planet location.

Parameters:

• radius the radius, a rank 0 dataset, maybe with units, or a string parsed into a rank 0 dataset.

Returns:

• QDataSet that when plotted is a circle.

4.67. sin

public static QDataSet sin(QDataSet ds)

element-wise sin.

Parameters:

• ds -

Returns:

4.68. asin

public static QDataSet asin(QDataSet ds)

element-wise arcsin.

Parameters:

• ds -

Returns:

4.69. cos

public static QDataSet cos(QDataSet ds)

element-wise cos.

Parameters:

• ds -

Returns:

4.70. acos

public static QDataSet acos(QDataSet ds)

element-wise arccos.

Parameters:

• ds -

Returns:

4.71. tan

public static QDataSet tan(QDataSet ds)

element-wise tan.

Parameters:

• ds -

Returns:

4.72. atan

public static QDataSet atan(QDataSet ds)

element-wise atan.

Parameters:

• ds -

Returns:

4.73. atan2

public static QDataSet atan2(QDataSet dsy,
                            QDataSet dsx)

element-wise atan2, 4-quadrant atan.

Parameters:

• dsy -
• dsx -

Returns:

4.74. cosh

public static QDataSet cosh(QDataSet ds)

element-wise cosh.

Parameters:

• ds -

Returns:

4.75. sinh

public static QDataSet sinh(QDataSet ds)

element-wise sinh.

Parameters:

• ds -

Returns:

4.76. tanh

public static QDataSet tanh(QDataSet ds)

element-wise tanh.

Parameters:

• ds -

Returns:

4.77. expm1

public static QDataSet expm1(QDataSet ds)

returns ex -1. Note that for values of x near 0, the exact sum of expm1(x) + 1 is much closer to the true result of ex than exp(x). (TODO lost info in wiki)

Parameters:

• ds -

Returns:

4.78. toRadians

public static QDataSet toRadians(QDataSet ds)

4.79. toDegrees

public static QDataSet toDegrees(QDataSet ds)

4.80. where

public static QDataSet where(QDataSet ds)

returns a dataset containing the indeces of where the dataset is non-zero. For a rank 1 dataset, returns a rank 1 dataset with indeces for the values. For a higher rank dataset, returns a rank 2 qube dataset with ds.rank() elements in the first dimension. Note when the dataset is all zeros (false), the result is a zero-length array, as opposed to IDL which would return a -1 scalar.

Parameters:

• ds - of any rank M

Returns:

• a rank 1 or rank 2 dataset with N by M elements, where N is the number of non-zero elements found.

4.81. sort

public static QDataSet sort(QDataSet ds)

returns a rank 1 dataset of indeces that sort the rank 1 dataset ds. This is not the dataset sorted. For example:

ds= randn(2000)
s= sort( ds )
dsSorted= ds[s]
    

Parameters:

• ds - rank 1 dataset

Returns:

• rank 1 dataset of indeces that sort the input dataset.

4.82. uniqValues

public static QDataSet uniqValues(QDataSet ds,
                                 QDataSet sort)

return the unique elements from the dataset. If sort is null (jython None), then the dataset is assumed to be monotonic, and only repeating values are coalesced. If sort is non-null, then it is the result of the function "sort" and should be a rank 1 list of indeces that sort the data. renamed uniqValues from uniq to avoid confusion with the IDL command.

Parameters:

• ds -
• sort -

Returns:

4.83. reverse

public static QDataSet reverse(QDataSet ds)

returns the reverse of the rank 1 dataset.

Parameters:

• ds -

Returns:

4.84. shuffle

public static QDataSet shuffle(QDataSet ds)

returns a rank 1 dataset of indeces that shuffle the rank 1 dataset ds

s= shuffle( ds )
dsShuffled= ds[s]
    

Parameters:

• ds - rank 1 dataset

Returns:

• rank 1 dataset of integer indeces.

4.85. fftFilter

public static QDataSet fftFilter(QDataSet ds,
                                int len,
                                Ops.FFTFilterType filt)

4.86. hanning

public static QDataSet hanning(QDataSet ds,
                              int len)

Hanning filter for use with fftPower. ds= fftPower( hanning( randn( 20480 ), 512 ) )

4.87. fftPower

public static QDataSet fftPower(QDataSet ds,
                               int len,
                               org.das2.util.monitor.ProgressMonitor mon)

create a power spectrum on the dataset by breaking it up and doing ffts on each segment. right now only rank 2 data is supported, but there is no reason that rank 1 shouldn't be supported. Looks for DEPEND_1.USER_PROPERTIES.FFT_Translation, which should be a rank 0 or rank 1 QDataSet. If it is rank 1, then it should correspond to the DEPEND_0 dimension.

Parameters:

• ds - rank 2 dataset ds(N,M) with M>len
• len - the number of elements to have in each fft.
• mon - a ProgressMonitor for the process

Returns:

• rank 2 fft spectrum

4.88. fftPower

public static QDataSet fftPower(QDataSet ds)

returns the power spectrum of the waveform. Positive frequencies are returned for DEPEND_0, and square of the magnitude is returned for the values.

Parameters:

• ds - rank 1 waveform or rank 2 array of waveforms

Returns:

4.89. fft

public static QDataSet fft(QDataSet ds)

Performs an FFT on the provided rank 1 dataset. A rank 2 dataset of complex numbers is returned.

Parameters:

• ds - a rank 1 dataset.

Returns:

• a rank 2 dataset of complex numbers.

4.90. fftWindow

public static QDataSet fftWindow(QDataSet ds,
                                int len)

perform ffts on the rank 1 dataset to make a rank2 spectrogram.

Parameters:

• ds - rank 1 dataset
• len - the window length

Returns:

• rank 2 dataset.

4.91. extent

public static QDataSet extent(QDataSet ds)

returns a two element, rank 1 dataset containing the extent of the data. Note this accounts for DELTA_PLUS, DELTA_MINUS properties. The property QDataSet.SCALE_TYPE is set to lin or log. The property count is set to the number of valid measurements. TODO: this could use MONOTONIC, but it doesn't. DELTA_PLUS, DELTA_MINUS make that more difficult.

Parameters:

• ds - rank N dataset.

Returns:

• two element, rank 1 "bins" dataset.

See Also:

• DataSetUtil.rangeOfMonotonic( QDataSet ds ).

4.92. extent

public static QDataSet extent(QDataSet ds,
                             QDataSet range)

returns a two element, rank 1 dataset containing the extent of the data. Note this accounts for DELTA_PLUS, DELTA_MINUS properties. The property QDataSet.SCALE_TYPE is set to lin or log. The property count is set to the number of valid measurements. This checks the monotonic property, and uses it to avoid iterating through the data if available.

Parameters:

• ds -
• range, - if non-null, return the union of this range and the extent. This must not contain fill!

Returns:

• two element, rank 1 "bins" dataset.

4.93. rescaleRange

public static QDataSet rescaleRange(QDataSet dr,
                                   double min,
                                   double max)

returns rank 1 QDataSet range relative to the range in "dr", where 0. is the minimum, and 1. is the maximum. For example rescaleRange(ds,1,2) is scanNext, rescaleRange(ds,-1,0) is scanPrevious, rescaleRange(ds,-0.5,1.5) is zoomOut.

Parameters:

• dr - a QDataSet with "min,max" for BINS_0 and with nonzero width.
• min - the new min normalized with respect to this range. 0. is this range's min, 1 is this range's max, 0 is min-width.
• max - the new max width normalized with respect to this range. 0. is this range's min, 1 is this range's max, 0 is min-width.

Returns:

• new rank 1 QDataSet range.

4.94. histogram

public static QDataSet histogram(QDataSet ds,
                                double min,
                                double max,
                                double binSize)

returns histogram of dataset, the number of points falling in each bin.

Parameters:

• ds -
• min -
• max -
• binSize -

Returns:

4.95. histogram

public static QDataSet histogram(QDataSet ds,
                                int binCount)

returns a histogram of the dataset, based on the extent and scaletype of the data. See also autoHistogram, which automatically identifies bin width, min and max.

Parameters:

• ds -
• binCount - number of bins

Returns:

• rank 1 QDataSet that is the histogram.

4.96. autoHistogram

public static QDataSet autoHistogram(QDataSet ds)

One pass auto-scaling histogram. See also histogram.

Parameters:

• ds -

Returns:

4.97. outerProduct

public static QDataSet outerProduct(QDataSet ds1,
                                   QDataSet ds2)

returns outerProduct of two rank 1 datasets, a rank 2 dataset with elements R[i,j]= ds1[i] * ds2[j].

Parameters:

• ds1 - Rank 1 dataset having length M
• ds2 - Rank 1 dataset having length N

Returns:

• Rank 2 dataset lengths M,N

4.98. floor

public static QDataSet floor(QDataSet ds1)

element-wise ceil function.

Parameters:

• ds1 -

Returns:

4.99. ceil

public static QDataSet ceil(QDataSet ds1)

element-wise ceil function.

Parameters:

• ds1 -

Returns:

4.100. signum

public static QDataSet signum(QDataSet ds1)

returns the signum function of the argument; 0.0 if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero.

Parameters:

• ds1 -

Returns:

• -1.0, 0.0, or 1.0 to indicate the sign.

See Also:

• copysign

4.101. copysign

public static QDataSet copysign(QDataSet magnitude,
                               QDataSet sign)

returns a dataset with the same geometry, but having the floating-point magnitude of the first argument with the sign of the second argument.

Parameters:

• magnitude - dataset containing magnitude
• sign - dataset with compatible geometry

Returns:

• Dataset with the magnitude and sign combined.

See Also:

• signum

4.102. findex

public static QDataSet findex(QDataSet uu,
                             QDataSet vv)

returns the floating point index of each element of vv within the monotonically increasing dataset uu. The result dataset will have the same geometry as vv. The result will be negative when the element of vv is below the smallest element of uu. The result will be greater than or equal to the length of uu minus one when it is greater than all elements.

Parameters:

• uu - rank 1 monotonically increasing dataset.
• vv - rank N dataset with values in the same physical dimension as uu.

Returns:

• rank N dataset with the same geometry as vv.

4.103. interpolate

public static QDataSet interpolate(QDataSet vv,
                                  QDataSet findex)

interpolate values from rank 1 dataset vv using fractional indeces in rank N findex. For example, findex=1.5 means interpolate the 1st and 2nd indeces with equal weight, 1.1 means 90% of the first mixed with 10% of the second. No extrapolation is done, data with findex<0 or findex>(vv.length()-1) are assigned the first or last value. Note there is no check on CADENCE. Note nothing is done with DEPEND_0, presumably because was already calculated and used for findex.

Parameters:

• vv - rank 1 dataset that is the data to be interpolated.
• findex - rank N dataset of fractional indeces.

Returns:

• the result.

4.104. interpolate

public static QDataSet interpolate(QDataSet vv,
                                  QDataSet findex0,
                                  QDataSet findex1)

interpolate values from rank 2 dataset vv using fractional indeces in rank N findex, using bilinear interpolation.

Parameters:

• vv - rank 2 dataset.
• findex0 - rank N dataset of fractional indeces for the zeroth index.
• findex1 - rank N dataset of fractional indeces for the first index.

Returns:

• rank N dataset

4.105. valid

public static QDataSet valid(QDataSet ds)

returns a dataset with zero where the data is invalid, and positive non-zero where the data is valid. (This just returns the weights plane of the dataset.) r= where( valid( ds ) )

Parameters:

• ds - a rank N dataset that might have FILL_VALUE, VALID_MIN or VALID_MAX set.

Returns:

• a rank N dataset with the same geometry, with zeros where the data is invalid and >0 where the data is valid.

4.106. smooth

public static QDataSet smooth(QDataSet ds,
                             int size)

run boxcar average over the dataset, returning a dataset of same geometry. Points near the edge are simply copied from the source dataset. The result dataset contains a property "weights" that is the weights for each point.

Parameters:

• ds - a rank 1 dataset of size N
• size - the number of adjacent bins to average

Returns:

• rank 1 dataset of size N

4.107. diff

public static QDataSet diff(QDataSet ds)

return array that is the differences between each successive pair in the dataset. Result[i]= ds[i+1]-ds[i], so that for an array with N elements, an array with N-1 elements is returned. DEPEND_0 will contain the average of the two points.

Parameters:

• ds - a rank 1 dataset with N elements.

Returns:

• a rank 1 dataset with N-1 elements.

See Also:

• accum

4.108. accum

public static QDataSet accum(QDataSet accumDs,
                            QDataSet ds)

return an array that is the running sum of each element in the array, starting with the value accum. Result[i]= accum + total( ds[0:i+1] )

Parameters:

• accum - the initial value of the running sum. Last value of Rank 0 or Rank 1 dataset is used, or may be null.
• ds - each element is added to the running sum

Returns:

• the running of each element in the array.

See Also:

• diff

4.109. accum

public static QDataSet accum(QDataSet ds)

return an array that is the running sum of each element in the array, starting with the value accum. Result[i]= total( ds[0:i+1] )

Parameters:

• ds - each element is added to the running sum

Returns:

• the running sum of each element in the array.

See Also:

• diff

4.110. labels

public static QDataSet labels(java.lang.String[] labels,
                             java.lang.String context)

create a labels dataset for tagging rows of a dataset. If the context has been used already, including "default", then the EnumerationUnit for the data will be preserved. labels(["red","green","blue"],"default") will always return an equivalent (and comparable) result during a session. Example: dep1= labels( ["X","Y","Z"], "GSM" )

Parameters:

• labels -
• context -

Returns:

• rank 1 QDataSet

4.111. labels

public static QDataSet labels(java.lang.String[] labels)

create a labels dataset for tagging rows of a dataset. Example: dep1= labels( ["red","greed","blue"] )

Parameters:

• labels -

Returns:

• rank 1 QDataSet

4.112. reform

public static QDataSet reform(QDataSet ds)

Reshape the dataset to remove the first dimension with length 1, reducing its rank by 1. Dependencies are also preserved.

Parameters:

• ds - a rank r dataset [1,m], [1,n,m], etc.

Returns:

• a rank r-1 dataset [m], [n,m], etc.

4.113. reform

public static QDataSet reform(QDataSet ds,
                             int[] qube)

change the dimensionality of the elements of the QUBE dataset. For example, convert [1,2,3,4,5,6] to [[1,2],[3,4],[5,6]].

params:

• ds
• qube the dimensions of the result dataset.

returns:

• a new dataset with the specified dimensions, and the properties (e.g. UNITS) of the input dataset.

4.114. bundle

public static QDataSet bundle(QDataSet ds1,
                             QDataSet ds2)

bundle the two datasets, adding if necessary a bundle dimension. This will try to bundle on the second dimension, unlike join. This will also isolate the semantics of bundle dimensions as it's introduced.

Parameters:

• ds1 -
• ds2 -

Returns:

4.115. isLegacyBundle

public static boolean isLegacyBundle(QDataSet zds)

return true if DEPEND_1 is set and its units are EnumerationUnits. This was the pre-bundle way of representing a bundle of datasets. It might be supported indefinitely, because it has some nice rules about the data. For example, data must be of the same units since there is no place to put the property. Note the "legacy" status has been removed. This is a fine way to easily create bundle datasets. See BUNDLE_1 for more information about bundle datasets.

Parameters:

• zds -

Returns:

• true for DEPEND_1 where units are EnumerationUnits.

4.116. isBundle

public static boolean isBundle(QDataSet zds)

return true if the dataset is a bundle. It is rank 2 or rank 1, and has the last dimension a bundle dimension.

Parameters:

• zds -

Returns:

4.117. link

public static QDataSet link(QDataSet x,
                           QDataSet y)

This is like bundle, but declare the last dataset is dependent on the first one. "link" is like a plot command where link(x,y) would behave like plot(x,y) except you get a dataset back.

Parameters:

• x - rank 1 dataset
• y - rank 1 or rank 2 dataset

Returns:

4.118. link

public static QDataSet link(QDataSet x,
                           QDataSet y,
                           QDataSet z)

like bundle, but declare the last dataset is dependent on the first two.

Parameters:

• x - rank 1 dataset
• y - rank 1 dataset
• z - rank 1 or 2 dataset.

Returns:

4.119. dependsOn

public static MutablePropertyDataSet dependsOn(QDataSet ds,
                                              int dim,
                                              QDataSet dep0)

declare that the dataset is a dependent parameter of an independent parameter. This isolates the QDataSet semantics, and verifies correctness.

Parameters:

• ds -
• dim - dimension to declare dependence: 0,1,2.
• dep0 -

Returns:

4.120. join

public static QDataSet join(QDataSet ds1,
                           QDataSet ds2)

Join two rank N datasets to make a rank N+1 dataset, with the first dimension having two elements. This is the anti-slice operator. If the first dataset is rank N+1 JoinDataset and the other is rank N, then the rank N dataset is added to the rank N+1 dataset. This is underimplemented right now, and can only join two rank N datasets or if the first dataset is the result of a join.

Parameters:

• ds1 - rank N dataset, or null
• ds2 - rank N dataset

Returns:

• rank N+1 dataset

See Also:

• slice, concatenate

4.121. safeName

public static java.lang.String safeName(java.lang.String suggest)

Make a Java-style identifier from the provided string, which will only include a-z, A-Z, 0-9 (though not the first), and _. For example, "a>b" becomes agtb.

Parameters:

• suggest - A string suggesting a name. The non-compliant characters are replaced. for example

Returns:

• a string guarenteed to be useful as an identifier.

4.122. transpose

public static QDataSet transpose(QDataSet ds)

Transpose the rank 2 dataset.

4.123. equivalent

public static boolean equivalent(QDataSet ds1,
                                QDataSet ds2)

returns true if and only if the dataset values are equivalent. Note this may promote rank, etc. A rank 0 dataset is promoted to a rank 1 by replicating the value, so for example the rank 0 "4" is equivalent to "4,4,4".

Parameters:

• ds1 - rank n dataset
• ds2 - rank m dataset

Returns:

• true if the two are equivalent.

4.124. dimensionCount

public static int dimensionCount(QDataSet dss)

returns the number of physical dimensions of a dataset. JOIN, BINS do not increase dataset dimensionality. DEPEND increases dimensionality by dimensionality of DEPEND ds. BUNDLE increases dimensionality by N where N is the number of bundled datasets. Note this includes implicit dimensions taken by the primary dataset. Z(time,freq)->3 rand(20,20)->3 B_gsm(20,[X,Y,Z])->4

Parameters:

• ds -

Returns:

• the number of dimensions occupied by the data.

5. Misc

5.1. getParam

getParam( name, default, [label] )

returns the parameter with the name, or the default if not provided. This is an interesting operator because it is defined in each context, and parameters are passed in differently in each case.

Params:

• name - the unique name of the parameter, which must be valid a Java identifier.
• default - a default value for the parameter.
• label - a short label describing the use. (This should probably be renamed "title" since a sentence is okay.)

How are these typed? "foo" is a string, 4.0 is a double, etc. TODO: need documentation on interpretation.

For python data sources, vap+jyds:<script_file>?<paramName>=<paramValue>. Use of this function will result in an item in the datasource editor.

For --script on the command line, it's a command line argument.

For application context scripts, the default value is always used, but a future rev may create a GUI.

5.2. downloadResourceAsTempFile

downloadResourceAsTempFile( url, mon ) -> File

Download the resource into a file. The URL may be any web address, and may contain parameters (unlike the FileSystem). Note, the downloaded resource may be reused by other threads for 10 seconds. This allows scripts to be simpler and more abstract, written to load one variable but actually able to load many efficiently.

Params:

• url - Url to download
• mon - ProgressMonitor to monitor the download.

Returns:

• File containing the data, which will be deleted when the application exits. (TODO: server apps?)

Throws:

• java.lang.IOException when there is a problem downloading the file

Example:

fil= downloadResourceAsTempFile( URL('http://autoplot.org/data/autoplot.dat'), monitor )

5.3. getFile( surl, mon )

getFile( surl, mon )

Download the file and make it available to the script. The URL may not contain parameters, but the result is cached.

Params:

• url - Url to download, without ? and params
• mon - ProgressMonitor to monitor the download.

Returns:

• File containing the data, which will persist in the user's cache.

5.4. getDataSet

getDataSet( uri )

returns a QDataSet for the given URI. Execution will stop at this point until the dataset is loaded.

getDataSet( uri, monitor )

can be used to monitor the download. Note "monitor" is the local variable that contains a ProgressMonitor object.

5.5. listDirectory

listDirectory( uri )

For example:

files= listDirectory( 'http://autoplot.org/data/*.cdf' )

returns a listing of the directory "uri." If uri ends with a slash, then the directory is listed without filtering, otherwise the part following the slash is a glob that is matched. Note, the list does not contain the folder name, so it is typically added to the result:

files= listDirectory( 'http://autoplot.org/data/*.cdf' )
for f in files:
   print 'http://autoplot.org/data/'+f

5.6. Color

java.awt.Color is imported, so for example Color.RED may be used.

dom.plotElements[0].style.color= Color.RED

5.7. DataSetBuilder

The DataSetBuilder object is useful for creating datasets.

from org.virbo.dsutil import DataSetBuilder
dsb= DataSetBuilder(1,100)  # creates a rank 1 with 100 records pre-allocated. 
for i in xrange(115):
  dsb.putValue(-1,0.0)    # -1 means use the built in position
  dsb.nextRecord()
plot(dsb.getDataSet())

from org.virbo.dsutil import DataSetBuilder
dsb= DataSetBuilder(2,100,10)  # creates a rank 2 with 100 10-element records pre-allocated. 
for i in range(115):
  for j in range(10):
     dsb.putValue(i,j,0.0)  
plot(dsb.getDataSet())

6. DOM

We should have a section on the DOM, or a pointer to a document that describes it.

7. Proper, Fully-Capable, Jython Scripts

Ed W at RPWG points out that python provides some of the functionality I recreate, if scientists were willing to learn a little python. Also Bob W and I were discussing a method for defining DataSourceEditorPanels for jyds sources. I've always meant to have an alternate form for specifying these scripts and this section begins this discussion.

def mysource( orbit='A' ):
  """Look up data for an orbit.
     orbit: the orbit number to lookup. A,B,C,0-41"""

class plugin:
  def dataSourceEditorPanel( uri ): uri
  def getDataSet( params ): QDataSet, or dictionary of calculated parameters
  def formatDataSet( QDataSet, params )

8. Other Commands

A few other things are imported into sessions automatically, because they are useful and we don't want to burden new users with having to import them.

• http://autoplot.org/javadoc/javadoc/org/virbo/dsops/Ops.html
• http://autoplot.org/javadoc/javadoc/org/virbo/jythonsupport/JythonOps.html
• http://autoplot.org/javadoc/javadoc/org/virbo/jythonsupport/Util.html
• http://autoplot.org/javadoc/javadoc/org/virbo/dataset/QDataSet.html (prefix with class name: QDataSet.DEPEND_0, etc)
• http://autoplot.org/javadoc/javadoc/org/virbo/dsutil/BinAverage.html

These are prefixed with the class name (e.g. Units.cm):

• http://autoplot.org/javadoc/javadoc/org/das2/datum/DatumRange.html
• http://autoplot.org/javadoc/javadoc/org/das2/datum/Units.html
• http://autoplot.org/javadoc/javadoc/org/das2/datum/DatumRangeUtil.html
• http://autoplot.org/javadoc/javadoc/org/das2/datum/TimeUtil.html
• http://autoplot.org/javadoc/javadoc/org/das2/util/TimeParser.html
• http://autoplot.org/javadoc/javadoc/org/das2/util/filesystem/FileSystem.html
• http://autoplot.org/javadoc/javadoc/org/das2/fsm/FileStorageModel.html

TODO:

• the javadoc is missing for a number of these
• remove javadoc, this is the authoratative copy