基本雷达测高工具箱BRAT(Basic Radar Altimetry Toolbox)的API

要点

BRAT的介绍和简单使用看这里。

API能提供更加个性化的操作。

API的使用要点是：

1.理解数据的处理流程，比如数据格式，如何计算（这其实和API关系不大，但很重要）

2.理解API的参数

掌握这两点就可以拿到API就用，不用关心函数的具体实现，但如果有时候上面两点没有理解正确，可能就会踩到坑。

参数

在brat的user_manual中可以看到它提供了几下几种语言的API接口：

• matlab
• fortran
• c
• python

读取最关键的函数是brathl_ReadData，它的参数如下：

• [in] fileNames: file name string (one file) or file names array

• [in] recordName: Name of the fields record (for netCDF files the recordName is ‘data’)

• [in] selection: Expression involving data fields which has to be true to select returned data. (if the string is empty nothing is selected (in other words all of the data is taken)

• [in] dataExpressions: Expression string (one expression) or expressions array applied to data fields to build the wanted value.

• [in] units: Wanted unit for each expression (string (one unit) or units array).(if empty string, no unit conversion is applied to the data of the corresponding expression. When a unit conversion has to be applied, the result of the expression is considered to be the base unit (SI). For example if the wanted unit is grammes/litre, the unit of the expression is supposed to be kilogrammes/m3 (internally all data are converted to the basic unit of the actual fields unit which is coherent with the above assumption).

• [in/out] results: Data read. Must be an array (dim = number of dataExpressions) of values to read.

• [in] ignoreOutOfRange: Skip excess data. 0=false, other = true Must be false if ‘statistics’ is true.

• [in] statistics: returns statistics on data instead of data themselves 0=false, other = true If statistics is true, ignoreOutOfRange must be false.

  The returned values (5 values) for each expression are:

  • Count of valid data taken into account.
    Invalid data are those which are equal to the default/missing value
  • Mean of the valid data.
  • Standard deviation of the valid data
  • Minimum value of the valid data
  • Maximum value of the valid data

• [in] defaultValue: value to use for default/missing values

  This is the value you want to indicate that a value is missing or invalid.

  return 0 or error code.

参数比较多，这里就不翻译了，说一下如何使用，matlab中的例子：

% Set data input file
% 要处理的文件路径
files={'E:\brat\data_sample\jason1\JA1_GDR_2PaP124_001.CNES';
        'E:\brat\data_sample\jason1\JA1_GDR_2PaP124_002.CNES';
        'E:\brat\data_sample\jason1\JA1_GDR_2PaP124_003.CNES'};

% Set record name 
% 可以在brat中查看
record='data';

% Set data selection - (set selection = "" to retrieve all data row)
% 选择，这个比较好理解
selection=''; %'latitude > 20 && latitude < 30';

% Set expressions (here 2 expressions) 
% 要输出的量，也可以做一些计算后输出
expr='latitude';%'latitude + longitude';

% Set units for each expression
% 单位，可以在brat中查看
units='radians';

ignoreOutOfrange=false;

% No statistics
statistics=false;

% Default value is 0
defaultValue=0;

% Call ReadData function
dataResults = brathl_ReadData(files, record, selection, expr, units, ignoreOutOfrange, statistics, defaultValue)

• record

这个是什么？看参数说明其实是不太容易明白的，一个简单的方法是，在brat中查看一个文件，就可以找到它的record的名字：

这里可以看到最上面给出来了这个文件是那个卫星的，什么格式的，有一个Record字段，下面就是每一个变量的属性，这里全是data，所以程序中的record的就被赋值为data。当然，不是所有的变量的record属性都是data，用的时候一定要看清楚。unit（单位）也可以在这里查看。

测试

python的程序基本一样。我测试的时候matlab总是报错，ERROR : Unknown error，不知道是什么地方出错了。测试python则可以。

在安装目录下就有测试程序，比如我的目录是C:\Program Files\brat-3.3.0\examples，python中的程序大概如下：

    fileNames   = [currentDirectory + '/j2.nc']
    recordName  = 'data'
    selection   = ''               # 'lon_mwr_l1b > 10 && lon_mwr_l1b < 40'
    expressions = ['lon', 'lat'] # ['lat_mwr_l1b', 'lon_mwr_l1b']
    units       = ['degrees_north', 'degrees_north']      # ['radians', 'radians']
    ignoreOutOfRange = False
    statistics       = False
    defaultValue = 0

    dataResults = brathl_ReadData(fileNames,
                                  recordName,
                                  selection,
                                  expressions,
                                  units,
                                  ignoreOutOfRange,
                                  statistics,
                                  defaultValue)
    print ("--------------------- Read data --------------------")
    for i in range(len(dataResults)):
        print (expressions[i], "(", len(dataResults[i]), " values)")
    print ("----------------------------------------------------")

    ## Printing values to output.txt file #########################
    file = open (currentDirectory + '/output.txt', 'w')
    for i in range(len(dataResults)):
        file.write (expressions[i] + "(" + str(len(dataResults[i])) + " values):\n")
        for j in range(len(dataResults[i])):
            file.write ( str(j) )
            file.write (" = ")
            file.write ( str(dataResults[i][j]) )
            file.write ("\n")
    file.close()
    print ("Please check the values read in output.txt.")

输出的结果都放了在当前目录下的output.txt文件里面，可以查看，大概如下：

lon(3276 values):
0 = 222.51180499999998
1 = 222.641528
2 = 222.858903
3 = 223.023519
4 = 223.15322999999998
5 = 223.67663299999998
.....
.....
lat(3276 values):
0 = 66.147257
1 = 66.147205
2 = 66.146857
3 = 66.146378
4 = 66.145868
5 = 66.142634

需要说明的是，如果在matlab中用ncread读一个二维的变量，比如lat_20hz，那么读出来的是一个矩阵，而在这里用brathl_ReadData读来的则是一维的，不过都是有规律的。在程序中如果要进行其它的操作，也没什么问题。