Functions: np, nf and n

Definition

These functions compute and return the number of profiles (np), of floats (nf) or both (n). They can also sort the results by some given profile properties.

Default output format

The default output is a JSON array where the first value is the number of profiles and the second value is the number of floats. For the NA-ARC web API, the 'number of floats' is the number of unique WMO ID found in a list of profiles (by default the whole database). Using the function np will returns only the number of profiles, and function nf only the number of floats.

Examples

?get=n

An API response example to this request is:

Options

Functions n, np and nf from service get come with a handy option to retrieve more detailled numbers. The option 'by' allows to count the number of profiles/floats according to a list of predefined properties. Those properties are:

  • dac: Data Assembly Center name
  • dmode: Data Mode (R, D or A)
  • wmo: World Meteorological Organization unique float ID
  • cyc: Profile's cycle number
  • year: Profile's year
  • month: Profile's month (1 to 12)
  • ticket: Is a ticket filled or not for profiles (0 or 1)
  • area: Profile's coordinate area code (0, 1 or 2)
  • pres, temp, psal, doxy: Profile's availability of parameter (0 or 1)
  • pres_qc, temp_qc, psal_qc, doxy_qc: Profile's quality flag of parameter (A, B, C, D, E, F or empty)

For instance, to count the number of floats for each Data Assembly Center (DAC), simply use:

?get=n&by=dac

which results in the following output in the JSON default format:

This is a JSON object with a list of key/value where keys are DAC names and value an array with the number of profiles/floats.

NOTE:

The 'by' option supports up to 2 sorting parameters.

For instance, to count the number of floats for each Data Assembly Center (DAC) and Data Mode, simply use:

?get=n&by=dac,dmode

In this usage can, the output is a JSON object with a list of key_1/object_1 where key_1 are DAC names and object_1 is a list of key_2/value_2 where key_2 are Data Modes and value_2 an array with the number of profiles/floats:

The option 'by' is used on the NA-ARC website to populate graphics on the 'Charts' and 'Time series' panels. The two sorting key option is used to populate the 'Good vs Bad profiles per year' infography on the 'Time series' panel.

Other output format

To specify an output format different than JSON, simply use the format restriction followed by either: matlab or csv.

Matlab

For the matlab format, the following query:

?get=n&format=matlab

results in the output:

This is a Matlab array with the number of profiles/floats in the first/second columns. To learn how to use the API from Matlab, see the 'Using the API from Matlab' section.

Using the 'by' option results in the following output (using 'dac' ordering):

This is a Matlab cell with a DAC name in the first column and the corresponding number of profiles/floats in the second/third one. There is one row for each DAC. More generally, all unique occurrences of the sorting parameter specified with the option by are listed in the first column.

Coma Separated Values (CSV)

The csv output format will prompt the user to download a text file with a coma separated list of the results (after the commented header). Querying the API with the following:

?get=n&format=csv

produces a file which contains:

and using the 'by' option with 'dac' ordering, we obtain: