mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2025-01-24 16:04:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added nccopy -kind_code documentation and deprecated -k format_number, need to do the same for ncgen

Browse Source
This commit is contained in:
Russ Rew 2014-12-13 19:50:21 -07:00
parent 4a6ec72db9
commit 40a7398b21
2 changed files with 70 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/guide.dox
View File

@ -1234,7 +1234,7 @@ application is also included that provides a graphical user interface
to capabilities similar to the C-based ncdump and ncgen utilities, as to capabilities similar to the C-based ncdump and ncgen utilities, as
well as CF-compliance checking and many other features. well as CF-compliance checking and many other features.
The
\section remote_client The Remote Data Access Client \section remote_client The Remote Data Access Client
@ -3256,9 +3256,9 @@ Copy a netCDF file, optionally changing format, compression, or chunking in the
\subsection nccopy_SYNOPSIS nccopy synopsis \subsection nccopy_SYNOPSIS nccopy synopsis
\code \code
nccopy [-k kind] [-d n] [-s] [-c chunkspec] [-u] [-w] [-[v|V] var1,...] nccopy [-k kind_name] [-kind_code] [-d n] [-s] [-c chunkspec] [-u] [-w]
[-[g|G] grp1,...] [-m bufsize] [-h chunk_cache] [-e cache_elems] [-[v|V] var1,...] [-[g|G] grp1,...] [-m bufsize] [-h chunk_cache]
[-r] infile outfile [-e cache_elems] [-r] infile outfile
\endcode \endcode
\subsection nccopy_DESCRIPTION nccopy description \subsection nccopy_DESCRIPTION nccopy description
@ -3274,6 +3274,17 @@ a netCDF-4 classic model file as well, permitting data compression,
efficient schema changes, larger variable sizes, and use of other efficient schema changes, larger variable sizes, and use of other
netCDF-4 features. netCDF-4 features.
If no output format is specified, with either \b -k \Ikind_name
or \b -\Ikind_code, then the output will use the same
format as the input, unless the input is classic or 64-bit offset
and either chunking or compression is specified, in which case the
output will be netCDF-4 classic model format. Attempting
some kinds of format conversion will result in an error, if the
conversion is not possible. For example, an attempt to copy a
netCDF-4 file that uses features of the enhanced model, such as
groups or variable-length strings, to any of the other kinds of netCDF
formats that use the classic model will result in an error.
\b nccopy also serves as an example of a generic netCDF-4 program, \b nccopy also serves as an example of a generic netCDF-4 program,
with its ability to read any valid netCDF file and handle nested with its ability to read any valid netCDF file and handle nested
groups, strings, and user-defined types, including arbitrarily groups, strings, and user-defined types, including arbitrarily
@ -3286,25 +3297,34 @@ local netCDF files.
\subsection nccopy_OPTIONS nccopy options \subsection nccopy_OPTIONS nccopy options
\par -k \e kind \par -k \e kind_name
Specifies the kind of file to be created (that is, the format variant) Use format name to specify the kind of file to be created
and, by inference, the data model (i.e. netcdf-3 (classic) versus and, by inference, the data model (i.e. netcdf-3 (classic) or
netcdf-4 (enhanced)). The possible arguments are as follows. \n netcdf-4 (enhanced)). The possible arguments are as follows. \n
'1' or 'classic' => netCDF classic format \n 'nc3' or 'classic' => netCDF classic format \n
'2', '64-bit-offset', or '64-bit offset' => netCDF 64-bit format \n 'nc6' or '64-bit-offset' => netCDF 64-bit format \n
'3', 'hdf5', 'netCDF-4', or 'enhanced' => netCDF-4 format (enhanced data model) \n 'nc4' or 'netCDF-4' => netCDF-4 format (enhanced data model) \n
'4', 'hdf5-nc3', 'netCDF-4 classic model', or 'enhanced-nc3' => netCDF-4 classic model format \n 'nc7' or 'netCDF-4 classic model' => netCDF-4 classic model format \n
\par \par
If no value for -k is specified, then the output will use the same Note: The old format numbers '1', '2', '3', '4', equivalent
format as the input, except if the input is classic or 64-bit offset to the format names 'nc3', 'nc6', 'nc4', or 'nc7' respectively, are
and either chunking or compression is specified, in which case the also still accepted but deprecated, due to easy confusion between
output will be netCDF-4 classic model format. Note that attempting format numbers and format names.
some kinds of format conversion will result in an error, if the
conversion is not possible. For example, an attempt to copy a \par -k \e kind_code
netCDF-4 file that uses features of the enhanced model, such as groups Use format numeric code (instead of format name) to specify the kind of file to be created
or variable-length strings, to any of the other kinds of netCDF and, by inference, the data model (i.e. netcdf-3 (classic) versus
formats that use the classic model will result in an error. netcdf-4 (enhanced)). The numeric codes are:
3 => netcdf classic format \n
6 => netCDF 64-bit format \n
4 => netCDF-4 format (enhanced data model) \n
7 => netCDF-4 classic model format \n
The numeric code "7" is used because "7=3+4", specifying the format
that uses the netCDF-3 data model for compatibility and the netCDF-4
storage format for performance. Credit is due to NCO for use of these
numeric codes instead of the old and confusing format numbers.
\par -d \e n \par -d \e n
For netCDF-4 output, including netCDF-4 classic model, specify For netCDF-4 output, including netCDF-4 classic model, specify
@ -3322,10 +3342,11 @@ the input by default.
\par \par
Note that \b nccopy requires all variables to be compressed using the Note that \b nccopy requires all variables to be compressed using the
same compression level, but the API has no such restriction. With a same compression level, but the API has no such restriction. With
program you can customize compression for each variable independently. a program you can customize compression for each variable independently.
\par -s For netCDF-4 output, including netCDF-4 classic model, specify \par -s
For netCDF-4 output, including netCDF-4 classic model, specify
shuffling of variable data bytes before compression or after shuffling of variable data bytes before compression or after
decompression. Shuffling refers to interlacing of bytes in a chunk so decompression. Shuffling refers to interlacing of bytes in a chunk so
that the first bytes of all values are contiguous in storage, followed that the first bytes of all values are contiguous in storage, followed
@ -3360,21 +3381,21 @@ file can also greatly speedup access, by choosing chunk shapes that
are appropriate for the most common access patterns. are appropriate for the most common access patterns.
\par \par
The chunkspec argument is a string of comma-separated associations, The \e chunkspec argument is a string of comma-separated associations,
each specifying a dimension name, a '/' character, and optionally the each specifying a dimension name, a '/' character, and optionally the
corresponding chunk length for that dimension. No blanks should corresponding chunk length for that dimension. No blanks should
appear in the chunkspec string, except possibly escaped blanks that appear in the chunkspec string, except possibly escaped blanks that
are part of a dimension name. A chunkspec names dimensions along are part of a dimension name. A chunkspec names at
which chunking is to take place, and omits dimensions which are least one dimension, and may omit dimensions which are not to be
not to be chunked or for chunked or for which the default chunk length is desired. If a dimension name is
which the default chunk length is desired. If a dimension name is
followed by a '/' character but no subsequent chunk length, the actual followed by a '/' character but no subsequent chunk length, the actual
dimension length is assumed. If copying a classic model file to a dimension length is assumed. If copying a classic model file to a
netCDF-4 output file and not naming all dimensions in the chunkspec, netCDF-4 output file and not naming all dimensions in the chunkspec,
unnamed dimensions will also use the actual dimension length for the unnamed dimensions will also use the actual dimension length for the
chunk length. An example of a chunkspec for variables that use chunk length. An example of a chunkspec for variables that use
'm' and 'n' dimensions might be 'm/100,n/200' to specify 100 by 200 'm' and 'n' dimensions might be 'm/100,n/200' to specify 100 by 200
chunks. chunks. To see the chunking resulting from copying with a
chunkspec, use the '-s' option of ncdump on the output file.
\par \par
The chunkspec '/' that omits all dimension names and The chunkspec '/' that omits all dimension names and
@ -3517,7 +3538,7 @@ compression, to a netCDF-3 file classic.nc:
\code \code
nccopy -k classic compressed.nc classic.nc nccopy -k classic compressed.nc classic.nc
\endcode \endcode
Note that '1' could be used instead of 'classic'. Note that 'nc3' could be used instead of 'classic'.
<H4> Remote Access to Data Subset </H4> <H4> Remote Access to Data Subset </H4>

37
ncdump/nccopy.1
View File

@ -1,8 +1,7 @@
.\" $Id: nccopy.1 400 2010-08-27 21:02:52Z russ $ .\" $Id: nccopy.1 400 2010-08-27 21:02:52Z russ $
.TH NCCOPY 1 "2012-03-08" "Release 4.2" "UNIDATA UTILITIES" .TH NCCOPY 1 "2012-03-08" "Release 4.2" "UNIDATA UTILITIES"
.SH NAME .SH NAME
nccopy \- Copy a netCDF file to specified variant of netCDF format, nccopy \- Copy a netCDF file, optionally changing format, compression, or chunking in the output.
optionally compressing or chunking data in the output copy.
.SH SYNOPSIS .SH SYNOPSIS
.ft B .ft B
.HP .HP
@ -42,7 +41,7 @@ If no output format is specified, with either \fB-k \fP \fI kind_name\fP
or \fB-\fP\fIkind_code\fP, then the output will use the same or \fB-\fP\fIkind_code\fP, then the output will use the same
format as the input, unless the input is classic or 64-bit offset format as the input, unless the input is classic or 64-bit offset
and either chunking or compression is specified, in which case the and either chunking or compression is specified, in which case the
output will be netCDF-4 classic model format. Note that attempting output will be netCDF-4 classic model format. Attempting
some kinds of format conversion will result in an error, if the some kinds of format conversion will result in an error, if the
conversion is not possible. For example, an attempt to copy a conversion is not possible. For example, an attempt to copy a
netCDF-4 file that uses features of the enhanced model, such as netCDF-4 file that uses features of the enhanced model, such as
@ -62,7 +61,7 @@ local netCDF files.
.IP "\fB -k \fP \fI kind_name \fP" .IP "\fB -k \fP \fI kind_name \fP"
Use format name to specify the kind of file to be created Use format name to specify the kind of file to be created
and, by inference, the data model (i.e. netcdf-3 (classic) or and, by inference, the data model (i.e. netcdf-3 (classic) or
netcdf-4 (enhanced)). The possible arguments are as follows. netcdf-4 (enhanced)). The possible arguments are:
.RS .RS
.RS .RS
.IP "'nc3' or 'classic' => netCDF classic format" .IP "'nc3' or 'classic' => netCDF classic format"
@ -79,7 +78,7 @@ format numbers and format names.
.IP "[\fB-\fP\fIkind_code\fP]" .IP "[\fB-\fP\fIkind_code\fP]"
Use format numeric code (instead of format name) to specify the kind of file to be created Use format numeric code (instead of format name) to specify the kind of file to be created
and, by inference, the data model (i.e. netcdf-3 (classic) versus and, by inference, the data model (i.e. netcdf-3 (classic) versus
netcdf-4 (enhanced)). The possible arguments are as follows. netcdf-4 (enhanced)). The
.RS .RS
.RS .RS
.IP "3 => netcdf classic format" .IP "3 => netcdf classic format"
@ -88,11 +87,10 @@ netcdf-4 (enhanced)). The possible arguments are as follows.
.IP "7 => netCDF-4 classic model format" .IP "7 => netCDF-4 classic model format"
.RE .RE
.RE .RE
The mnemonic for the numeric code "7" is "7=3+4" to specify the format The numeric code "7" is used because "7=3+4", specifying the format
that uses the netCDF-3 data model for compatibility and the netCDF-4 that uses the netCDF-3 data model for compatibility and the netCDF-4
storage format (based on HDF5) for performance. Credit is due to NCO for storage format for performance. Credit is due to NCO for use of these
use of these numeric codes instead of the old and confusing format numeric codes instead of the old and confusing format numbers.
numbers.
.IP "\fB -d \fP \fI n \fP" .IP "\fB -d \fP \fI n \fP"
For netCDF-4 output, including netCDF-4 classic model, specify For netCDF-4 output, including netCDF-4 classic model, specify
deflation level (level of compression) for variable data output. 0 deflation level (level of compression) for variable data output. 0
@ -107,16 +105,19 @@ specified and the input file has compressed variables, the compression
will still be preserved in the output, using the same chunking as in will still be preserved in the output, using the same chunking as in
the input by default. the input by default.
.IP .IP
Note that specifying output deflation level with \fBnccopy\fP results in Note that \fBnccopy\fP requires all variables to be compressed using the
all output variables compressed using same compression level, but the API has no such restriction. With
the same compression level, but the API has no such restriction. With
a program you can customize compression for each variable independently. a program you can customize compression for each variable independently.
.IP "\fB -s \fP" .IP "\fB -s \fP"
For netCDF-4 output, including netCDF-4 classic model, specify For netCDF-4 output, including netCDF-4 classic model, specify
shuffling of variable data bytes before compression or after shuffling of variable data bytes before compression or after
decompression. This option is ignored unless a non-zero deflation decompression. Shuffling refers to interlacing of bytes in a chunk so
level is specified. Turning shuffling on sometimes improves that the first bytes of all values are contiguous in storage, followed
compression. by all the second bytes, and so on, which often improves compression.
This option is ignored unless a non-zero deflation level is specified.
Using -d0 to specify no deflation on input data that has been
compressed and shuffled turns off both compression and shuffling in
the output.
.IP "\fB -u \fP" .IP "\fB -u \fP"
Convert any unlimited size dimensions in the input to fixed size Convert any unlimited size dimensions in the input to fixed size
dimensions in the output. This can speed up variable-at-a-time dimensions in the output. This can speed up variable-at-a-time
@ -142,7 +143,7 @@ The \fIchunkspec\fP argument is a string of comma-separated
associations, each specifying a dimension name, a '/' character, and associations, each specifying a dimension name, a '/' character, and
optionally the corresponding chunk length for that dimension. No optionally the corresponding chunk length for that dimension. No
blanks should appear in the chunkspec string, except possibly escaped blanks should appear in the chunkspec string, except possibly escaped
blanks that are part of a dimension name. A chunkspec must name at blanks that are part of a dimension name. A chunkspec names at
least one dimension, and may omit dimensions which are not to be least one dimension, and may omit dimensions which are not to be
chunked or for which the default chunk length is desired. If a chunked or for which the default chunk length is desired. If a
dimension name is followed by a '/' character but no subsequent chunk dimension name is followed by a '/' character but no subsequent chunk
@ -214,7 +215,7 @@ performance, if the output fits in memory.
.IP "\fB -h \fP \fI chunk_cache \fP" .IP "\fB -h \fP \fI chunk_cache \fP"
For netCDF-4 output, including netCDF-4 classic model, an integer or For netCDF-4 output, including netCDF-4 classic model, an integer or
floating-point number that specifies the size in bytes of chunk cache floating-point number that specifies the size in bytes of chunk cache
for each chunked variable. This is not a property of the file, but merely allocated for each chunked variable. This is not a property of the file, but merely
a performance tuning parameter for avoiding compressing or a performance tuning parameter for avoiding compressing or
decompressing the same data multiple times while copying and changing decompressing the same data multiple times while copying and changing
chunk shapes. A suffix of K, M, G, or T multiplies the chunk cache chunk shapes. A suffix of K, M, G, or T multiplies the chunk cache
@ -228,7 +229,7 @@ cache size has been implemented yet. Using the '-w' option may
provide better performance, if the output fits in memory. provide better performance, if the output fits in memory.
.IP "\fB -e \fP \fI cache_elems \fP" .IP "\fB -e \fP \fI cache_elems \fP"
For netCDF-4 output, including netCDF-4 classic model, specifies For netCDF-4 output, including netCDF-4 classic model, specifies
number of chunkss that the chunk cache can hold. A suffix of K, M, G, number of chunks that the chunk cache can hold. A suffix of K, M, G,
or T multiplies the number of chunks that can be held in the cache or T multiplies the number of chunks that can be held in the cache
by one thousand, million, billion, or trillion, respectively. This is not a by one thousand, million, billion, or trillion, respectively. This is not a
property of the file, but merely a performance tuning parameter for property of the file, but merely a performance tuning parameter for