comp_index_1d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Compute an index time series from two time series extracted from two unidimensional variables in one or two NetCDF datasets and stored the new index time series in a NetCDF dataset.

The two original time series can be computed by comp_serie_3d, comp_serie_miss_3d or similar procedures for fourdimensional NetCDF variables.

Different operations are available for estimating the index time series from the original time series (see the description of the -op= argument below).

Different operations are also available for transforming or normalizing the index time series after its estimation from the two original time series (see the description of the -a= argument below).

Further Details

Usage

$ comp_index_1d \
  -f=input_netcdf_file \
  -v=netcdf_variable \
  -v2=netcdf_variable2 \
  -f2=input_netcdf_file2                   (optional) \
  -t=timea1,timea2                         (optional) \
  -t2=timeb1,timeb2                        (optional) \
  -a=type_of_transformation                (optional : scp, cov, cor) \
  -p=periodicity                           (optional) \
  -o=output_netcdf_file                    (optional) \
  -n=output_netcdf_variable                (optional) \
  -op=type_of_operation                    (optional : +, -, *, /) \
  -sm=smoothing_factor                     (optional) \
  -mi=missing_value                        (optional) \
  -3d                                      (optional) \
  -double                                  (optional) \
  -hdf5                                    (optional) \
  -tlimited                                (optional)

By default

-f2=
the input_netcdf_file2 is the same as input_netcdf_file. This means that the netcdf_variable2 is extracted from the same NetCDF dataset as netcdf_variable
-t=
the whole time period associated with the netcdf_variable
-t2=
the whole time period associated with the netcdf_variable2
-a=
the type_of_transformation is set to scp. This means that the index time series is computed from the raw original time series and is not normalized or transformed
-p=
the periodicity is set to 1. This means that the index time series does not have a seasonal cycle.
-o=
the output_netcdf_file is named index_netcdf_variable.netcdf_variable2.nc
-n=
the output_netcdf_variable is named netcdf_variable_netcdf_variable2_index
-op=
the type_of_operation is set to -. This means that the index time series is computed as the differences between the two original time series
-sm=
no smoothing is applied to the index time series
-mi=
the missing_value in the output NetCDF file is set to 1.e+20
-3d
the output_netcdf_variable is defined as an unidimensional NetCDF variable. However, if -3d is activated, the output_netcdf_variable is defined as an tridimensional NetCDF variable but with two dummy dimensions (e.g., with a length equal to 1 )
-double
the data are stored as single-precision floating point numbers in the output NetCDF file. If -double is activated, the data are stored as double-precision floating point numbers
-hdf5
a NetCDF classical format file is created. If -hdf5 is activated, the output NetCDF file is a NetCDF-4/HDF5 format file
-tlimited
the time dimension is defined as unlimited in the output NetCDF file. However, if -tlimited is activated, the time dimension is defined as limited in the output NetCDF file

Remarks

  1. The -v=netcdf_variable specifies the first unidimensional time series for computing the index and the -f=input_netcdf_file argument specifies that this NetCDF variable must be extracted from the NetCDF file input_netcdf_file.

  2. The -v2=netcdf_variable2 specifies the second unidimensional time series for computing the index and the -f2=input_netcdf_file2 argument specifies that this NetCDF variable must be extracted from the NetCDF file input_netcdf_fil2e. If the -f2= argument is absent, it is assumed that this netcdf_variable2 is also in the NetCDF dataset specifies by the -f= argument.

  3. If the -t=timea1,timea2 argument is missing, the whole time period associated with the netcdf_variable is used to compute the first time series.

    The selected time period is a vector of two integers specifying the first and last time observations. The indices are relative to 1. Note that the output NetCDF file will have ntime = timea2 - timea1 + 1 time observations.

  4. If the -t=timeb1,timeb2 argument is missing, the whole time period associated with the netcdf_variable2 is used to compute the second time series.

    The selected time period is a vector of two integers specifying the first and last time observations. The indices are relative to 1. Note that the output NetCDF file will have ntime = timeb2 - timeb1 + 1 time observations.

  5. The selected number of time observations by the -t= and -t2= arguments must be equal. This means that the following equality must hold

    timea2 - timea1 + 1 = timeb2 - timeb1 + 1

    otherwise, an error message will be issued and the program will stop.

  6. The -a=type_of_transformation argument specifies how the index time series is normalized or transformed. If:

    • -a=scp, the raw index time series is stored
    • -a=cov, the anomalies of the raw index time series are computed and stored in the output NetCDF file
    • -a=cor, the standardized anomalies of the raw index time series are computed and stored in the output NetCDF file.

    The default is -a=scp meaning that the raw index time series is stored.

  7. If the -p= argument is specified and -a=cov or -a=cor, the anomalies or the standardized anomalies are computed from the raw index time series by taken into account the periodicity of the data as specified by the -p= argument.

  8. The -op=type_of_operation argument specifies how the index time series is computed from the two original time series. If:

    • -op=-, the default, the index is computed as the difference between the two original time series
    • -op=+`, the index is computed as the sum of the two original time series
    • -op=*, the index is computed as the product of the two original time series
    • -op=/, the index is computed as the quotient of the two original time series.

  9. -sm=smoothing_factor means that the (transformed) index time series must be smoothed with a moving average of approximately 2*smoothing_factor+1 terms. smoothing_factor must be an integer greater than 0. However, if missing values are present in the time original time series or generated in the computation of the index, smoothing is not allowed.

  10. The -n=output_netcdf_variable argument specifies the NetCDF variable which will contains the computed time series in the output NetCDF file, output_netcdf_file, specified by the -o=output_netcdf_file argument.

  11. Missing values are allowed in both NetCDF variables associated with the two original time series. However, if missing values are present, the -sm= argument is not allowed.

  12. The -mi=missing_value argument specifies the missing value indicator associated with the NetCDF variable in the output_netcdf_file. If the -mi= argument is not specified missing_value is set to 1.e+20.

  13. The -3d argument specify that the index time series must be stored as a tridimensional NetCDF variable with two dummy dimensions in the output NetCDF file.

    By default, the index time series is stored as an unidimensional NetCDF variable.

  14. The -double argument specify that, the index time series is stored as double-precision floating point numbers in the output NetCDF file.

    By default, the index time series is stored as single-precision floating point numbers in the output NetCDF file.

  15. The -hdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF4 macro (eg -D_USE_NETCDF4) and linked to the NetCDF 4 library or higher.

    If this argument is specified, the output_netcdf_file will be a NetCDF-4/HDF5 format file instead of a NetCDF classic format file. However, this argument is recognized in the procedure only if the NCSTAT software has been built with the _USE_NETCDF4 CPP macro.

  16. Duplicate parameters are allowed, but this is always the last occurrence of a parameter which will be used for the computations. Moreover, the number of specified parameters must not be greater than the total number of allowed parameters.

Outputs

comp_index_1d creates an output NetCDF file that contains the computed index time series. The output NetCDF dataset contains the following NetCDF variable (in the description below, ntime is the number of time steps selected with the -t= and -t2= arguments):

  1. output_netcdf_variable(ntime) : the computed index time series defined as an unidimensional variable.

or if the -3d argument has been specified :

  1. output_netcdf_variable(ntime,1,1) : the computed index time series defined as a tridimensional variable with two dummy dimensions.

Examples

  1. For computing an index time series named siod as the difference between two unidimensional NetCDF variables both called sst and extracted, respectively, from the files HadISST1_2m_187001_200702_swiosst_nt67.nc and HadISST1_2m_187001_200702_seiosst_nt67.nc, and store the result in a file named HadISST1_2m_187001_200702_sdisst_nt67.nc, use the following command :

    $ comp_index_1d \
  -f=HadISST1_2m_187001_200702_swiosst_nt67.nc -v=sst \
  -f2=HadISST1_2m_187001_200702_seiosst_nt67.nc -v2=sst \
  -o=HadISST1_2m_187001_200702_sdisst_nt67.nc -n=siod
Flag Counter