restoreio.scan

restoreio.scan(input, scan_velocity=False, scan_other_var='', terminate=False, verbose=False)

Reads a netcdf file and returns data info.

Parameters:

inputstr

The input netcdf file URL (if remote file) or file name (if local data). The URL should either have no extension, if it does have an extension, the file extension should be either of .nc, .nc4, .ncd, .nc.gz, .ncml, or .ncml.gz.

scan_velocitybool, default=False

Scans the velocity arrays in the file. This is useful to find the min and max range of the velocity data to adjust the color bar for plotting.

scan_other_varstr, default=’’

Scans other arrays in the file. This is useful to find the min and max range of the other arrays data to adjust the color bar for plotting. This argument should be comma-separated name of variables.

terminatebool, default=False

If True, the program exists with code 1. This is useful when this package is executed on a server to pass exit signals to a Node application. On the downside, this option causes an interactive python environment to both terminate the script and the python environment itself. To avoid this, set this option to False. In this case, upon an error, the ValueError is raised, which cases the script to terminate, however, an interactive python environment will not be exited.

verbosebool, default=False

Prints the output dictionary. Note when scan is used in the command-line, the result is always verbose, whereas if used in the python environment, the verbosity is determined by this argument.

Returns:

infodict

A dictionary containing information about the netcdf file dataset.

See also

restoreio.restore

Notes

• If the scan_velocity option (or -V in command line) is used to scan min and max of velocities, we do not find the min and max of velocity for all time frames. This is because if the nc file is large, it takes a long time. Also we do not load the whole velocities like U[:] or V[:] because it the data is large, the netCDF4 package raises an error.

Examples

This code shows acquiring information for an HF radar dataset:

>>> from restoreio import scan
>>> input = 'https://transport.me.berkeley.edu/thredds/dodsC/' + \
...         'root/WHOI-HFR/WHOI_HFR_2014_original.nc'

>>> # Run script
>>> info = scan(input, scan_velocity=True, terminate=False,
...             verbose=True)

The above info variable is a Python dictionary. You can print it using print(info), but this may not produce a readable output. To achieve better readability, you can convert the dictionary into a JSON object and then print it with proper indentation. Here’s how:

>>> import json
>>> json_obj = json.dumps(info, indent=4)
>>> print(json_obj)
{
    "Scan": {
        "ScanStatus": true,
        "Message": ""
    },
    "TimeInfo": {
        "InitialTime": {
            "Year": "2014",
            "Month": "07",
            "Day": "01",
            "Hour": "00",
            "Minute": "00",
            "Second": "00",
            "Microsecond": "000000"
        },
        "FinalTime": {
            "Year": "2014",
            "Month": "09",
            "Day": "30",
            "Hour": "23",
            "Minute": "29",
            "Second": "59",
            "Microsecond": "000000"
        },
        "TimeDuration": {
            "Day": "91",
            "Hour": "23",
            "Minute": "29",
            "Second": "59"
        },
        "TimeDurationInSeconds": "7946999.0",
        "DatetimeSize": "4416"
    },
    "SpaceInfo": {
        "DataResolution": {
            "LongitudeResolution": "39",
            "LatitudeResolution": "36"
        },
        "DataBounds": {
            "MinLatitude": "41.08644",
            "MidLatitude": "41.212500000000006",
            "MaxLatitude": "41.33856",
            "MinLongitude": "-70.797912",
            "MidLongitude": "-70.616667",
            "MaxLongitude": "-70.435422"
        },
        "DataRange": {
            "LongitudeRange": "30355.79907013849",
            "LatitudeRange": "28065.8700187999",
            "ViewRange": "42498.11869819389",
            "PitchAngle": "45.06303"
        },
        "CameraBounds": {
            "MinLatitude": "41.036086627216",
            "MaxLatitude": "41.388913372784",
            "MinLongitude": "-70.87033700055551",
            "MaxLongitude": "-70.3629969994445"
        }
    },
    "VelocityInfo": {
        "EastVelocityName": "east_vel",
        "NorthVelocityName": "north_vel",
        "EastVelocityStandardName": "eastward_wind",
        "NorthVelocityStandardName": "northward_wind",
        "VelocityStandardName": "wind",
        "MinEastVelocity": "-0.48760945773342956",
        "MaxEastVelocity": "0.3507359965788057",
        "MinNorthVelocity": "-0.36285106142279266",
        "MaxNorthVelocity": "0.312877327708193",
        "TypicalVelocitySpeed": "0.6121967517719955"
    }
}