developer.book.jyscripts
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/
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
code |
function |
example |
|---|---|---|
DatumRangeUtil.parseTimeRange(time) |
parses a string timerange to the internal form which many functions need. |
tr='2014-Jan' |
generateTimeRanges(format,timerange) |
generates a list of string timeranges that cover an interval. |
trs= generateTimeRanges( '$Y-$m-$d','2000' ) |
writeToPng(file) |
export the current canvas out to a png image file. |
writeToPng( '/tmp/foo.png' ) |
putProperty(dataset,String,Object) |
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) |
getParam(name,deflt[,label[,constraints]]) |
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']) |
getDataSet(uri[,mon]) |
read in the data for the given URI. |
ds= getDataSet( 'http://autoplot.org/data/autoplot.cdf?Magnitude' ) |
formatDataSet(ds,file) |
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) |
convert the object to a Datum. |
ds= datum('4Kg') |
datumRange(o) |
convert the object to a DatumRange, or an interval in a dimension. |
ds= datumRange('4.2-6.8 Kg') |
dataset(o) |
convert the object to a dataset |
ds= dataset('4.2 Kg') |
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' ) |
** |
exponent |
ds= linspace(-5,5,100) |
- |
negation |
ds= linspace(-5,5,100) |
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)) |
PWD |
String |
the present working directory, typically the location of the script. |
print PWD |
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) |
DEPEND_1 |
QDataSet |
provide the independent dataset that is indexed by the first dimension |
ds=ripplesSpectrogramTimeSeries(100) |
UNITS |
Units |
provide the units object for the data |
ds=ripplesSpectrogramTimeSeries(100) |
TITLE |
String |
one-line description of the data, used for plot titles |
ds=ripplesSpectrogramTimeSeries(100) |
LABEL |
String |
short description of the data, used for axis labels |
ds=ripplesSpectrogramTimeSeries(100) |
- 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.
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...)
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).
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. 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.