# 1. .jy scripts

Jython is Python written for Java. In the same way that Python can be used to call C code, Jython can call Java code, and Autoplot provides routines that can be used in Jython scripts to create new and useful functionality. For example, suppose we have a plot of one day's worth of data, formatted the way we like, it is easy to write a script that creates images for the entire mission:

trs= generateTimeRanges( '$Y-$m-$d','2000' ) for tr in trs: dom.timeRange= DatumRangeUtil.parseTimeRange(tr) writeToPng( '/tmp/%s.png' % tr ) These scripts are conventionally named with a .jy extension, and can be run by entering the location of the .jy script in the address bar. This allows one user to deliver functionality to another user via a script on a website the same way data URIs can be used. Note that these scripts have the same access you do on a system, so a script can accidentally delete data, and malicious scripts could damage your system. For this reason, always review scripts before running them, unless they come from a trusted source. http://autoplot.org/cookbook has a number of example scripts, and more are found in the Autoplot source: https://svn.code.sf.net/p/autoplot/code/autoplot/trunk/Autoplot/src/scripts/ # 2. commonly used functions A number of functions are often used in scripts, and this section hopes to introduce them. A more complete reference is available here: developer.scripting ## 2.1. commonly used functions code function example DatumRangeUtil.parseTimeRange(time) time,string indicating time range parses a string timerange to the internal form which many functions need. tr='2014-Jan' drtr= DatumRangeUtil.parseTimeRange( tr ) generateTimeRanges(format,timerange) format,format for output times timerange,the span to cover generates a list of string timeranges that cover an interval. trs= generateTimeRanges( '$Y-$m-$d','2000' )
writeToPng(file)
file, the file name
export the current canvas out to a png image file. writeToPng( '/tmp/foo.png' )
putProperty(dataset,String,Object)
dataset
String,property name
Object,the object depends on property
set the dataset property. If the dataset is not writable, a copy is returned. If the value can be coerced to the correct type, it will be. ds= ripples(40,40)
ds= putProperty( ds, QDataSet.TITLE, 'Fake Data' )
plot(ds)
getParam(name,deflt[,label[,constraints]])
String,tag
Object,default value
[String,label for the parameter]
constraints is an array of enumerated values.
get an input parameter for the script. This will create a GUI when shift is held with the execute button, or when the script is run from the address bar. name= getParam('sc','A','RBSP Spacecraft',['A','B'])
print(name)
getDataSet(uri[,mon])
file, the filename URI.
[monitor, a progress monitor]
read in the data for the given URI. ds= getDataSet( 'http://autoplot.org/data/autoplot.cdf?Magnitude' )
plot( ds )
formatDataSet(ds,file)
ds, the dataset to format
file, the filename URI.
format the data to the given filename and implied file format. Options can be provided with optional arguments following a question mark. ds= getDataSet( 'http://autoplot.org/data/autoplot.cdf?Magnitude' )
datum(o)
o, an object which can be converted to a datum (numerical value and unit)
convert the object to a Datum. ds= datum('4Kg')
t=datum('2018-08-07T15:22Z')
datumRange(o)
o, an object which can be converted to a datum range (two numerical values and unit)
convert the object to a DatumRange, or an interval in a dimension. ds= datumRange('4.2-6.8 Kg')
t=datumRange('2018-08-07')
dataset(o)
o, an object which can be converted to a data set
convert the object to a dataset ds= dataset('4.2 Kg')
ds=dataset([1,2,3,4,5])
ds=dataset([1,2,3,4,5],units='eV')

## 2.2. math operators

Jython provides operator overloading, and the following operators are available. Since QDataSet carries units around, these operators are generally aware of fill data and units. The units are presently simple names, so often units are dropped in operations. For example '5 cm' / '1 s' doesn't result in '5 cm/s' but the unit is dropped and the result is dimensionless.

operator function example
+,-,/,* add, subtract, multiply, divide ds1= getDataSet( 'http://www.autoplot.org/data/image/Capture_00158.jpg?channel=greyscale' )
ds2= getDataSet( 'http://www.autoplot.org/data/image/Capture_00159.jpg?channel=greyscale' )
result= abs( ds2- ds1 )
** exponent ds= linspace(-5,5,100)
plot(ds**2)
- negation ds= linspace(-5,5,100)
ds= -ds
plot(ds)

## 2.3. predefined objects

There are a set of variables that are often useful that are defined any time a script is started. They are:

name data type function example
monitor ProgressMonitor shows progress for data loads or script processing. ds= getDataSet( 'http://autoplot.org/data/sst.mnmean.nc?sst', monitor )
dom Application the current state of the application plot(rand(20))
dom.plotElements[0].style.color=Color.RED
PWD String the present working directory, typically the location of the script.
Note this can refer to local directories or http sites.
If the editor is not saved to a file, PWD is not defined.
print PWD
print URI(PWD).path

## 2.4. QDataSet properties

Here are QDataSet properties that are often used:

QDataSet property data type function example
DEPEND_0 QDataSet provide the independent dataset that is indexed by the first dimension ds=ripplesSpectrogramTimeSeries(100)
ttag= ds.property( QDataSet.DEPEND_0 )
print extent(ttag)
DEPEND_1 QDataSet provide the independent dataset that is indexed by the first dimension ds=ripplesSpectrogramTimeSeries(100)
energy= ds.property( QDataSet.DEPEND_1 )
plot(energy)
UNITS Units provide the units object for the data ds=ripplesSpectrogramTimeSeries(100)
ds= putProperty( ds, QDataSet.UNITS, Units.MeV)
plot(ds)
TITLE String one-line description of the data, used for plot titles ds=ripplesSpectrogramTimeSeries(100)
ds= putProperty( ds, QDataSet.TITLE, 'Fake Data')
plot(ds)
LABEL String short description of the data, used for axis labels ds=ripplesSpectrogramTimeSeries(100)
ds= putProperty( ds, QDataSet.LABEL, 'Fake Data')
plot(ds)

# 3. Jython vs Python

• differences in the libraries. Many Python libraries are implemented in native code, and are not available in Jython. For example, SciPy is not available in Jython.
• Jython binds to any Java object trivially. For example, the Apache Commons Math library is bundled in the Autoplot distribution, and can be used directly from Autoplot scripts.
• Jython is Python 2.2, and will soon be Python 2.7, the last version before Python 3.0.
• Autoplot provides a good editor for Jython, for example using Java introspection to provide completions.

# 4. comparison to SciPy

Both SciPy and Autoplot's scripting were developed with a common goal: to provide a familiar environment where scientists familiar with IDL and Matlab can develop code using Python. Because of this, two environments have similar code. In one case study, a SciPy code several hundred lines long was ported to Autoplot within minutes.

The differences come from how data is modeled. SciPy and IDL use arrays to model data, whereas Autoplot uses QDataSet. Because of this, Autoplot can perform similar functions that are more abstract and typically require shorter and simpler code.

(This section should have a side-by-side comparison between scripts in the environments...)

# 5. QDataSet

Instead of representing data in arrays, Autoplot's scripting uses QDataSet to represent data. QDataSet is an interface to the data, and different implementations are used to provide efficiency. For example, in IDL when you say ds[*,10] to look at a slice of ds, a new array is created and the data is copied. In Autoplot a new dataset is created that is backed by the same data internally, and the data is never copied.

QDataSets have metadata which make them more abstract, and make interfaces simplier. For example, in IDL to plot YY which is a function of XX, you would say plot, XX, YY. With QDataSet you would already have the association of YY[XX] and you can just say plot(YY).

# 6. script and console tabs

Autoplot provides an editor and output console to assist in using scripts.

The console tab has an "AP>" prompt that allows commands be entered interactively. For example,

AP> plot('http://autoplot.org/data/autoplot.cdf?Magnitude')
AP> ds= dom.dataSourceFilters[0].controller.dataSet   # get the data read in
AP> print max(ds)

Note that the feature "Server" provides a similar interface, but via telnet into a port.

The script editor is a simple editor that provides syntax highliting and completions. For example, enter QDataSet.<TAB> and see that completions like "QDataSet.DEPEND_0" are shown.

There is a selection for the script context, and when the context is "Data Source" (for .jyds scripts) commands that control the application are not available. When the context is "Application" all commands are available. Note when a script is run here and there is an error, a red squiggle is drawn under (or near) the failure and the Python session is left open. With this you can inspect the current value of symbols by highliting the symbol and hovering over the highlite until the tooltip containing the value appears.