all
ooc_name all
-format format
-columns int
-lines int
-missing text
-keep
This provides both data and metadata from a NAO. However it does not provide all information despite the name!
The following switches are allowed:
-format format: C format (default: "" meaning automatic)
-columns int: maximum # columns (default: 6) (-1: no limit)
-lines int: maximum # lines (default: 20) (-1: no limit)
-list: print in tcl list form (using braces) e.g. "{1 9 2}"
-missing text: text printed for missing value (default: "_")
-keep: Do not delete NAO with reference count of 0
The all method provides the same information as the two commands:
ooc_name header
ooc_name value
-format format
-columns int
-lines int
-missing text
Example:
% [nap "{3#2 2#_ -9}"] all -miss n/a
::NAP::39-39 i32 MissingValue: -2147483648 References: 0 Unit: (NULL)
Dimension 0 Size: 6 Name: (NULL) Coordinate-variable: (NULL)
Value:
2 2 2 n/a n/a -9
value
ooc_name value
-format format
-columns int
-lines int
-missing text
-keep
This returns data values.
The default value is -1 for both
the switches -columns and -lines,
giving the entire array.
The following switches are allowed:
-format format: C format (default: "" meaning automatic)
-columns int: maximum # columns (default: -1 i.e. no limit)
-lines int: maximum # lines (default: -1 i.e. no limit)
-list: print in tcl list form (using braces) e.g. "{1 9 2}"
-missing text: text printed for missing value (default: "_")
-keep: Do not delete NAO with reference count of 0
The following example begins with the definition of vectors
"x" and "y" for use
in this and subsequent examples:
% nap "x = 0 .. 2 ... 0.5" ::NAP::58-58 % nap "y = x ** 2" ::NAP::61-61 % $y val -format %0.3f 0.000 0.250 1.000 2.250 4.000
ooc_name
-format format
-columns int
-lines int
-missing text
-keep
This returns data values in a similar fashion to the
value method, except that default line and column
limits restrict the size.
The following switches are allowed:
-format format: C format (default:
"" meaning automatic)
-columns int: maximum # columns
(default: 6) (-1: no limit)
-lines int: maximum # lines (default:
20) (-1: no limit)
-list: print in tcl list form (using braces) e.g. "{1 9 2}"
-missing text: text printed for missing value
(default: "_")
-keep: Do not delete NAO with reference count of 0
The following example shows why and how to use switch -columns
(abbreviated to -c):
% nap "m = reshape(0 .. 99, {10 12})"
::NAP::50-50
% $m
0 1 2 3 4 5 ..
12 13 14 15 16 17 ..
24 25 26 27 28 29 ..
36 37 38 39 40 41 ..
48 49 50 51 52 53 ..
60 61 62 63 64 65 ..
72 73 74 75 76 77 ..
84 85 86 87 88 89 ..
96 97 98 99 0 1 ..
8 9 10 11 12 13 ..
% $m -c -1
0 1 2 3 4 5 6 7 8 9 10 11
12 13 14 15 16 17 18 19 20 21 22 23
24 25 26 27 28 29 30 31 32 33 34 35
36 37 38 39 40 41 42 43 44 45 46 47
48 49 50 51 52 53 54 55 56 57 58 59
60 61 62 63 64 65 66 67 68 69 70 71
72 73 74 75 76 77 78 79 80 81 82 83
84 85 86 87 88 89 90 91 92 93 94 95
96 97 98 99 0 1 2 3 4 5 6 7
8 9 10 11 12 13 14 15 16 17 18 19
The following example shows how to use switch -format
(abbreviated to -f) to include a dollar prefix and display
two decimal places:
% [nap "{15 3.2 999}"] -f {$%.2f}
$15.00 $3.20 $999.00
The following example shows how to use switch -list:
% [nap "reshape(1.5 .. -1.5, {2 5})"] -list
{
{ 1.5 0.5 -0.5 -1.5 1.5 }
{ 0.5 -0.5 -1.5 1.5 0.5 }
}
The -format option specifies a format conversion string
similar to that used in the standard Tcl format command
(which is based on the ANSI C sprintf() function).
Such strings have the form
%[flags][width][.precision]char
where:
-: left justify
+: include sign
0: leading zeros
#: alternate form
d,
i,
o,
x,
X
or
u
conversions.
e, E or f conversions.
g or G conversions.
| char | Convert to |
|---|---|
| signed decimal integer |
| unsigned octal integer |
| unsigned hexadecimal integer |
| unsigned decimal integer |
| character |
|
decimal number in form
[-]mmm.ddd,
where number of ds is specified by the precision. Default precision is 6; precision of 0 suppresses the " .".
|
|
decimal number in form
[-]m.dddddde±xx
or
[-]m.ddddddE±xx,
where number of ds is specified by the precision. Default precision is 6; precision of 0 suppresses the " .".
|
|
%e
or
%E
are used if exponent < −4 or
exponent ≥ precision;
otherwise %f
is used.
Trailing zeros and decimal points are suppressed. |
The following example displays the same data using each of these codes.
Note that
(unlike C and the standard Tcl format command)
any data-type can be displayed with any code.
% foreach code {d i o x X u c f E e g G} {
puts "$code: [[nap "88 .. 92"] -f "%$code"]"
}
d: 88 89 90 91 92
i: 88 89 90 91 92
o: 130 131 132 133 134
x: 58 59 5a 5b 5c
X: 58 59 5A 5B 5C
u: 88 89 90 91 92
c: XYZ[\
f: 88.000000 89.000000 90.000000 91.000000 92.000000
E: 8.800000E+01 8.900000E+01 9.000000E+01 9.100000E+01 9.200000E+01
e: 8.800000e+01 8.900000e+01 9.000000e+01 9.100000e+01 9.200000e+01
g: 88 89 90 91 92
G: 88 89 90 91 92
coordinate
ooc_name coordinate ?dim_name|dim_number? ?dim_name|dim_number? …
This returns the OOC-names of the coordinate variables of selected dimensions.
If no dimensions are specified then the effect is the same as:
ooc_name coo 0 1 2 … rank-1"
Example:
% $y set coo x % $y coo ::NAP::58-58 % [$y coo] 0 0.5 1 1.5 2
count
ooc_name count
-keep
This returns the reference count.
Example (using x defined in previous example):
% $x count 2Note that the reference count is 2 because this NAO is referenced by both
x
::NAP::61-61
datatype
ooc_name datatype
This returns the data-type.
Example:
% [nap "'hello'"] dat c8
dimension
ooc_name dimension ?dim_number? ?dim_number? …
This returns
the dimension names.
ooc_name di
is equivalent to:
ooc_name di 0 1 2 … rank-1"
Example (again continuing above example):
% $y dim x
header
ooc_name header
-keep
This returns similar information to the following
(but using a different format):
ooc_name ooc
ooc_name datatype
ooc_name missing
ooc_name count
ooc_name unit
ooc_name shape
ooc_name dimension
ooc_name coordinate
Example (continuing above example):
% $y header ::NAP::61-61 f64 MissingValue: NaN References: 1 Unit: (NULL) Dimension 0 Size: 5 Name: x Coordinate-variable: ::NAP::58-58 %
label
ooc_name label
This returns the label (title, etc.) of the NAO.
Example:
% $y set label "areas of squares" % $y label areas of squares
link
ooc_name link
This returns the OOC-name of the link NAO.
Example:
% $y set link [nap 42] % [$y link] 42
missing
ooc_name missing
This returns the missing value. This is the value used to indicate null or undefined data.
Example:
% $y miss NaN
ooc
ooc_name ooc
-keep
This returns the OOC-name of the NAO.
Example:
$y ooc ::NAP::61-61
rank
ooc_name rank
This returns the rank (number of dimensions).
Example:
% $y rank 1
sequence
ooc_name sequence
-keep
This returns
the sequence number of the NAO. E.g. 42 for nao.42-9
-keep: Do not delete NAO with reference count of 0
Example:
% $y seq 61
shape
ooc_name shape
This returns the shape, which is a vector of dimension sizes.
Example:
% $y shape 5
slot
ooc_name slot
-keep
This returns
the slot number of the NAO. E.g. 9 for nao.42-9
Example:
% $y sl 61
step
ooc_name step
This returns a code which indicates whether step sizes of a vector are equal, and if not, their sign. NAP uses this information for efficiency. It indicates whether a vector (not relevant for other ranks) is monotonically ascending/descending, and if so whether it is an arithmetic progression (AP). The result code is one of following strings:
+-": at least one positive step and one negative step
>= 0": all steps >= 0
<= 0": all steps <= 0
AP": equal steps (except final one which may be shorter)
Example:
% [nap "{3 5 7 7.1}"] step
AP
unit
ooc_name unit
This returns the unit of measure. This may be used in the future to support arithmetic with automatic unit conversion, but at the moment it is just descriptive information.
Example:
% $y set unit seconds % $y unit seconds
draw
ooc_name draw xy ?value?
This draws a polyline in the NAO
ooc_name, which must be type f32 in the current version.
It sets data elements on the polyline defined by NAO xy to the value of
scalar NAO value (default: missing value).
NAO xy can be:
Example:
% [nap "z = reshape(0f32, 2 # 5)"] draw y 1 % $z 1 0 0 0 0 0 1 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 1 0 0
fill
ooc_name fill xy ?value?
This fills a polygon in the NAO
ooc_name, which must be type f32 in the current version.
It sets data elements within the
polygon defined by NAO xy to the value of
the scalar NAO value (default: missing value).
NAO xy can be:
draw method).
Example:
% [nap "z = reshape(0f32, 2 # 8)"] fill "{{2 2 4 4}{2 4 4 2}}" 1
% $z value
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 1 1 1 0 0 0
0 0 1 1 1 0 0 0
0 0 1 1 1 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
set
ooc_name set attribute arg arg …
This modifies the NAO attribute specified by attribute. The sub-methods corresponding to these attributes are discussed below in separate sections. Note that the names of these attributes is the same as that of the method which returns their value.
ooc_name set coordinate coord_var coord_var coord_var …
This sets one or more coordinate variables.
coord_var can be a name, OOC-name or "".
If coord_var is a valid name
then this is also used as dimension name if this is undefined.
If coord_var is
"" then any existing coordinate variable is removed.
If the number of coord_var
arguments < rank then trailing values default
to "".
Thus the following command removes all coordinate variables:
ooc_name se coo
See above ("Method coordinate") for an example.
ooc_name set count ?int?
?-keep?
This sets or increments the reference count.
One situation where this facility
is needed is where a GUI window points to a NAO and must be retained
until the window is destroyed.
-keep: Do not delete NAO (with new count = 0)
-keep: Do not delete NAO with reference count of 0
If int is signed then add it to reference count.
If int is unsigned then set reference count to int.
If int not specified then add 1 to reference count
(i.e. treat as "+1")
ooc_name set dimension dim_name dim_name dim_name …
This sets one or more dimension names.
If dim_name is a tcl name pointing to a NAO then
this also defines the coordinate variable if this is undefined.
If dim_name is
"" then any existing dimension name is removed.
If the number of dim_names < rank then trailing values default to
"".
Thus the following command removes all dimension names:
ooc_name se d
Example:
% $x set dim time % $x dim
ooc_name set label ?string?
This sets the label (title). The default is NULL i.e. no label.
See above ("Method label") for an example.
ooc_name set link ?nao?
This sets the link slot number to point to a NAO
The default is NULL i.e. no link.
See above ("Method link") for an example.
ooc_name set missing ?value?
This sets the missing value. The default is NULL i.e. no missing value.
Example:
% $x set miss 0 % $x _ 0.5 1 1.5 2Note that the value of 0 is now treated as missing.
ooc_name set unit ?unit?
This sets the unit of measure. The default is NULL i.e. no unit.
See above ("Method unit") for an example.
ooc_name set value ?value? ?index?
This sets the value of
data elements selected by NAO index
(default: "" i.e. whole array)
to new values copied from successive elements of NAO
value
(default: "" meaning null value).
Elements of value are recycled if necessary.
binary
ooc_name binary ?tcl_channel?
This writes raw (binary) data to the file specified by
tcl_channel,
which defaults to stdout (standard output).
For example:
% set file [open y.tmp w] file4 % $y binary $file % close $file % set file [open y.tmp] file4 % [nap_get binary $file f64] all ::NAP::248-248 f64 MissingValue: NaN References: 0 Unit: (NULL) Dimension 0 Size: 5 Name: (NULL) Coordinate-variable: (NULL) Value: 0 0.25 1 2.25 4 % close $file
hdf
ooc_name hdf ?switches? filename sds
This writes data from the NAO to
an SDS named sds within an HDF file named filename.
switches can be:
-unlimited: Create sds with unlimited dimension 0
-coordinateVariable expr: boxed NAO which
specifies coordinate variables.
-datatype type: HDF datatype:
c8, i8, i16, i32, u8, u16, u32, f32
or
f64
-range float: HDF
valid_range
-scale float: HDF
scale_factor
-offset float: HDF
add_offset
-index expr: position within SDS where
data is to be written.
If
"-coordinateVariable expr"
is not specified then the coordinate variables
of the main NAO are used if these exist.
If
"-index expr"
is not specified then the coordinate variables
of the main NAO are used if these exist,
otherwise writing starts at the beginning of the SDS.
Example:
% [nap "3 .. 7"] hdf simple.hdf vec
% exec hdp dumpsds simple.hdf
File name: simple.hdf
Variable Name = vec
Index = 0
Type= 32-bit signed integer
Ref. = 2
Rank = 1
Number of attributes = 1
Dim0: Name=fakeDim0
Size = 5
Scale Type = number-type not set
Number of attributes = 0
Attr0: Name = _FillValue
Type = 32-bit signed integer
Count= 1
Value = -2147483648
Data :
3 4 5 6 7
netcdf
ooc_name netcdf ?switches? filename var
This writes data from the NAO to
a netCDF variable named var within
the netCDF file named filename.
switches can be:
-unlimited: Create variable with unlimited dimension 0
-coordinateVariable expr: boxed NAO which
specifies coordinate variables.
-datatype type: netCDF datatype:
c8, i16, i32, u8, f32
or
f64
-range float: netCDF
valid_range
-scale float: netCDF
scale_factor
-offset float: netCDF
add_offset
-index expr: position within netCDF variable
where data is to be written.
If
"-coordinateVariable expr"
is not specified then the coordinate variables
of the main NAO are used if these exist.
If
"-index expr"
is not specified then the coordinate variables
of the main NAO are used if these exist,
otherwise writing starts at the beginning of the netCDF variable.
Example:
% $y net sq.nc area -coordinateVariable "x // {3 6 9}"
::NAP::241-241
% exec ncdump sq.nc
netcdf sq {
dimensions:
x = 8 ;
variables:
double x(x) ;
double area(x) ;
area:_FillValue = nan ;
area:long_name = "areas of squares" ;
area:units = "seconds" ;
data:
x = 0, 0.5, 1, 1.5, 2, 3, 6, 9 ;
area = 0, 0.25, 1, 2.25, 4, nan, nan, nan ;
}
Note that the netCDF variable area is dimensioned to 8
(the shape of the
argument specified by the
-coordinateVariable
swap
ooc_name swap ?tcl_channel?
Method swap is like method binary, except that bytes are swapped.
This enables writing of data to be read on a machine with opposite byte-order within words.