The apply operator produces a result array that has the same shape (same dimensions, same non-empty cells) as it's source array, but with additional attribute(s) whose values are calculated from expressions you supply.

Synopsis

apply( source_array, new_attribute1, expression1, [, new_attribute2, expression2 ]...)

Summary

The apply operator lets you produce a result array with new attributes and compute values for them. The resultant array has the same shape (same dimensions, same non-empty cells) as the input array and includes all attributes present in the source array, plus the newly created attribute(s). Any newly created attribute(s) must not have the same name as any of the existing attributes of the source array.

Examples

Produce an Array with an Addition Attribute

Given an array with a single attribute that contains distance values in miles, to produce a result array with the same shape but with an additional attribute (called kilometers) whose value is computed from the source array's miles values, do the following:

Create an array called distance with an attribute called miles:
```
AFL% CREATE ARRAY distance <miles:double>[i=0:9];
```
Store values of 0–900 into the distance array's miles attribute:
```
AFL% store(build(distance,i*100.0),distance); 
```

Apply the expression 1.6 * miles to the distance array and name the new attribute kilometers:

AFL% apply(distance,kilometers,1.61*miles);

The output is:

{i} miles,kilometers
{0} 0,0
{1} 100,161
{2} 200,322
{3} 300,483
{4} 400,644
{5} 500,805
{6} 600,966
{7} 700,1127
{8} 800,1288
{9} 900,1449

Enlarge a Version of an Existing Array

To combine the apply operator and the xgrid operator to produce a result array that is an enlarged version of an existing array with a new attribute, do the following:

The enlargement includes more cells (via xgrid) and an additional attribute called val_2 (via apply).

Create a 1-dimensional array called vector:

AFL% CREATE ARRAY vector <val:double>[i=0:9];

Put values of 1–10 into vector and store the result:
```
AFL% 
store(
	build(vector,i+1),
	vector
); 
```

Expand vector with the xgrid operator and use the apply operator to add an attribute whose values contain the additive inverse of the dimension index:

AFL% 
apply(
	xgrid(vector,2),val_2,-i
);

The output is:

{i} val,val_2
{0} 1,0
{1} 1,-1
{2} 2,-2
{3} 2,-3
{4} 3,-4
{5} 3,-5
{6} 4,-6
{7} 4,-7
{8} 5,-8
{9} 5,-9
{10} 6,-10
{11} 6,-11
{12} 7,-12
{13} 7,-13
{14} 8,-14
{15} 8,-15
{16} 9,-16
{17} 9,-17
{18} 10,-18
{19} 10,-19

Produce an Array whose Attribute Values are Cast to New Datatype

In this example the store operator both creates and populates the new array A from the results of the build operator.

To use the apply operator and a data type conversion function to produce a result array with values cast to a new datatype, do the following:

Create an array called A with an int64 attribute called val.
```
AFL% 
store(
	build(<val:int64>[i=0:9],i+1),
	A
); 
```
Use the apply operator to convert the int64 type values to double type values in a new attribute named val_2.
```
AFL% 
apply(
	A,val_2,double(val)
); 
```
The output is:
```
{i} val,val_2
{0} 1,1
{1} 2,2
{2} 3,3
{3} 4,4
{4} 5,5
{5} 6,6
{6} 7,7
{7} 8,8
{8} 9,9
{9} 10,10
```
To confirm that the data type of the val_2 attribute in the query above is of the desired type, use the show operator.
```
AFL% 
show ( 'apply(A,val_2,double(val)', 'afl'); 
```
The output is:
```
{i} schema
{0} 'A@1<val:int64,val_2:double>[i=0:9]'
```

Bugs

It would be convenient if the maximum coordinate, *, were available to use with apply in the context of apply(....., chrom_end=24, pos_end=*), where pos_end needs to represent the maximum coordinate. As a workaround ,use the current implementation of the coordinate in numerical form, 4611686018427387903, for example: apply(....., chrom_end=24, pos_end=4611686018427387903)