NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)

ncdump - تبدیل فایل netCDF به شکل متنی (CDL)

ncdump [-chistxwF] [-v var1,...] [-b lang] [-f lang] [-l len] [-n name] [-p f_digits[,d_digits]] [-g grp1,...] file

ncdump -k file

ابزار ncdump یک نمایش متنی از یک فایل مشخص‌شدهٔ netCDF را در خروجی استاندارد تولید می‌کند، با این امکان اختیاری که برخی یا همهٔ داده‌های متغیر را از خروجی حذف کند. این نمایش متنی در قالبی به نام CDL (کوتاه‌نوشت network Common Data form Language) است که می‌توان آن را مشاهده و ویرایش کرد، یا به عنوان ورودی برای ncgen استفاده نمود؛ برنامه‌ای همراه که می‌تواند از یک فایل CDL یک فایل باینری netCDF تولید کند. بنابراین، ncgen و ncdump می‌توانند به عنوان معکوس یکدیگر برای تبدیل نمایش داده بین قالب‌های باینری و متنی استفاده شوند. برای شرح نمایش‌های CDL و netCDF به مستندات ncgen مراجعه کنید.

همچنین می‌توان با استفاده از گزینهٔ -k از ncdump برای تشخیص نوع فایل netCDF (کدام نسخه از قالب فایل netCDF) استفاده کرد.

اگر هنگام ساخت ncdump پشتیبانی از DAP فعال شده باشد، نام فایل می‌تواند یک نشانی اینترنتی (URL) پروتکل DAP را مشخص کند. این قابلیت به ncdump امکان می‌دهد به منابع داده از سرورهای DAP، از جمله داده‌هایی با قالب‌های دیگر غیر از netCDF، دسترسی پیدا کند. هنگام استفاده با URLهای DAP، برنامهٔ ncdump ترجمه از مدل دادهٔ DAP به مدل دادهٔ netCDF را نشان می‌دهد.

همچنین ncdump می‌تواند به عنوان یک مرورگر ساده برای فایل‌های دادهٔ netCDF استفاده شود تا نام‌ها و طول ابعاد، نام‌ها، نوع‌ها و شکل متغیرها، نام‌ها و مقادیر مشخصه‌ها (attributes) و به‌صورت اختیاری مقادیر داده‌ها را برای همهٔ متغیرها یا متغیرهای منتخب در یک فایل netCDF نمایش دهد. برای فایل‌های netCDF-4، گروه‌ها و انواع تعریف‌شده توسط کاربر نیز در خروجی ncdump گنجانده می‌شوند.

برنامهٔ ncdump از `_' برای نمایش مقادیر داده‌ای استفاده می‌کند که با مشخصهٔ `_FillValue' برای یک متغیر برابر هستند، که هدف آن نمایش داده‌هایی است که هنوز نوشته نشده‌اند. اگر متغیری مشخصهٔ `_FillValue' نداشته باشد، از مقدار پیش‌فرض پرکننده برای آن نوع متغیر استفاده می‌شود، مگر اینکه متغیر از نوع بایت (byte) باشد.

برنامهٔ ncdump یک قالب نمایش پیش‌فرض برای هر نوع دادهٔ netCDF تعریف می‌کند، اما اگر مشخصهٔ `C_format' برای یک متغیر netCDF تعریف شده باشد، این قالب قابل تغییر است. در این حالت، ncdump از مشخصهٔ `C_format' برای قالب‌بندی هر مقدار استفاده می‌کند. برای مثال، اگر مشخص باشد که داده‌های ممیز شناور متغیرِ netCDF به نام `Z' تنها تا سه رقم معنادار دقیق هستند، استفاده از مشخصهٔ متغیر زیر مناسب خواهد بود:

Z:C_format = "%.3g"

نمایش مقادیر متغیرهای مختصات (متغیرهای یک‌بعدی هم‌نام با ابعاد) و همچنین اعلان‌های همهٔ ابعاد، متغیرها، مقادیر مشخصه‌ها، گروه‌ها و انواع تعریف‌شده توسط کاربر. مقادیر داده‌های متغیرهای غیرمختصاتی در خروجی گنجانده نمی‌شوند. این گزینه معمولاً مناسب‌ترین گزینه برای یک نگاه اجمالی به ساختار و محتوای یک فایل netCDF است.
تنها نمایش اطلاعات سرایند (header) در خروجی، یعنی خروجی دادن فقط اعلان‌های ابعاد، متغیرها، مشخصه‌ها، گروه‌ها و انواع تعریف‌شده توسط کاربر از فایل ورودی، بدون هیچ مقدار داده‌ای برای متغیرها. خروجی این گزینه دقیقاً مشابه گزینهٔ -c است، با این تفاوت که مقادیر متغیرهای مختصات نیز گنجانده نمی‌شوند. (حداکثر یکی از گزینه‌های -c یا -h می‌تواند مشخص شود.)
خروجی علاوه بر اعلان تمام ابعاد، متغیرها و مشخصه‌ها، شامل مقادیر داده برای متغیرهای مشخص‌شده خواهد بود. یک یا چند متغیر باید با نام در فهرستی جداشده با کاما به دنبال این گزینه مشخص شوند. این فهرست باید یک آرگومان واحد برای دستور باشد، بنابراین نمی‌تواند شامل فاصله‌های اسکیپ‌نشده یا نویسه‌های فاصله خالی دیگر باشد. متغیرهای نام‌برده باید متغیرهای معتبر netCDF در فایل ورودی باشند. یک متغیر درون یک گروه در فایل netCDF-4 را می‌توان با مسیر مطلق، مانند `/GroupA/GroupA2/var'، مشخص کرد. استفاده از مسیر نسبی مانند `var' یا `grp/var' تمام نام‌های متغیر منطبق در فایل را مشخص می‌کند. در صورت عدم استفاده از این گزینه و نبودِ گزینه‌های -c یا -h، حالت پیش‌فرض گنجاندن مقادیر داده برای همهٔ متغیرها در خروجی است.
توضیحی مختصر به صورت یک یادداشت CDL (متنی که با نویسه‌های «//» شروع می‌شود) در بخش داده‌های خروجی برای هر «سطر» از داده‌ها گنجانده می‌شود تا به شناسایی مقادیر داده برای متغیرهای چندبُعدی کمک کند. اگر lang با `C' یا `c' آغاز شود، از قراردادهای زبان C استفاده خواهد شد (نمایه‌های مبتنی بر صفر، سریع‌ترین تغییر در آخرین بُعد). اگر lang با `F' یا `f' آغاز شود، از قراردادهای زبان فرترن (Fortran) استفاده خواهد شد (نمایه‌های مبتنی بر یک، سریع‌ترین تغییر در نخستین بُعد). در هر دو حالت، داده‌ها با همان ترتیب ارائه می‌شوند و تنها یادداشت‌ها متفاوت خواهند بود. این گزینه می‌تواند برای مرور مقادیر زیاد داده‌های چندبُعدی سودمند باشد.
توضیحات کامل به صورت یادداشت‌های پایانی CDL (متنی که با نویسه‌های «//» آغاز می‌شود) برای تک‌تک مقادیر داده (به جز نویسه‌های منفرد در آرایه‌های نویسه‌ای) در بخش داده‌ها گنجانده خواهد شد. اگر lang با `C' یا `c' آغاز شود، از قراردادهای زبان C استفاده می‌شود. اگر lang با `F' یا `f' آغاز شود، از قراردادهای زبان فرترن استفاده می‌شود. در هر دو حالت، داده‌ها با همان ترتیب نمایش داده می‌شوند و تنها یادداشت‌ها متفاوت خواهند بود. این گزینه می‌تواند برای ارسال داده‌ها با لوله‌کشی (pipe) به فیلترهای دیگر سودمند باشد، زیرا هر مقدار داده روی یک خط جداگانه و به طور کامل شناسایی‌شده ظاهر می‌شود. (حداکثر یکی از گزینه‌های '-b' یا '-f' می‌تواند مشخص شود.)
تغییر حداکثر طول خط پیش‌فرض (80) مورد استفاده در قالب‌بندی فهرست مقادیر داده‌های غیرنویسه‌ای.
فرمت CDL نیازمند نامی برای فایل netCDF است تا توسط ncgen -b در ایجاد نام پیش‌فرض فایل netCDF استفاده شود. به طور پیش‌فرض، ncdump این نام را از آخرین بخش نام فایل ورودی netCDF با حذف پسوند آن می‌سازد. از گزینهٔ -n برای مشخص کردن نامی متفاوت استفاده کنید. اگرچه نام فایل خروجی استفاده‌شده توسط ncgen -b قابل تعیین است، اما ممکن است عاقلانه باشد که از ncdump بخواهید نام پیش‌فرض را تغییر دهد تا از رونویسی تصادفی یک فایل باارزش netCDF هنگام استفاده از ncdump، ویرایش فایل حاصل CDL، و استفاده از ncgen -b برای ایجاد فایل netCDF جدید از فایل CDL ویرایش‌شده جلوگیری شود.
دقت پیش‌فرض (تعداد ارقام بااهمیت) مورد استفاده در نمایش مقادیر داده‌های ممیز شناور (floating-point) یا دقت مضاعف (double precision) را برای مشخصه‌ها و متغیرها تعیین می‌کند. در صورت تعیین، این مقدار بر مقدار مشخصهٔ C_format (در صورت وجود) برای متغیر برتری دارد. داده‌های ممیز شناور با float_digits رقم معنادار نمایش داده خواهند شد. اگر double_digits نیز مشخص شود، مقادیر دقت مضاعف با همان تعداد ارقام بااهمیت نمایش می‌یابند. در غیاب هرگونه مشخصه‌سازی با -p، داده‌های ممیز شناور و دقت مضاعف به ترتیب با ۷ و ۱۵ رقم معنادار نمایش داده می‌شوند. در صورتی که دقت کمتری نیاز باشد، می‌توان اندازه فایل‌های CDL را کوچک‌تر کرد. اگر هر دو دقت ممیز شناور و مضاعف تعیین شوند، این دو مقدار باید با یک کاما (بدون فاصله) به عنوان یک آرگومان واحد برای دستور ظاهر شوند. (برای نمایش جزء به جزء دقت در یک فایل CDL برای همهٔ مقادیر ممکن ممیز شناور، به -p 9,17 نیاز است.)
نوع فایل netCDF که مسیر به آن ارجاع دارد را نشان می‌دهد؛ یکی از موارد `classic'، `64-bit offset'، `netCDF-4' یا `netCDF-4 classic model'. پیش از نسخهٔ 3.6، تنها یک نوع فایل netCDF وجود داشت که به عنوان `classic' (همچنین شناخته‌شده به عنوان گونهٔ قالب ۱) مشخص می‌شد. پشتیبانی از فایل‌های حجیم، گونهٔ دیگری از قالب را معرفی کرد که به عنوان `64-bit offset' (گونهٔ قالب ۲) شناخته می‌شود. NetCDF-4 از گونهٔ سوم این قالب یعنی `netCDF-4' (گونهٔ قالب ۳) استفاده می‌کند. گونهٔ دیگر قالب که به عنوان `netCDF-4 classic model' (گونهٔ قالب ۴) مشخص شده است، محدود به ویژگی‌های پشتیبانی‌شده توسط مدل دادهٔ netCDF-3 است اما با استفاده از قالب HDF5 نمایش داده می‌شود، به طوری که یک برنامهٔ تغییرنیافتهٔ netCDF-3 می‌تواند تنها با پیوند مجدد با کتابخانهٔ netCDF-4 فایل را بخواند یا بنویسد. رشتهٔ خروجی از کاربرد گزینهٔ `-k' را می‌توان به عنوان مقدار گزینهٔ `-k' به ncgen(1) داد تا نوع دقیق فایل netCDF برای تولید را مشخص کند، زمانی که می‌خواهید مقدار پیش‌فرض استنباط‌شده از CDL را نادیده بگیرید.
نمایش مشخصه‌های مجازی ویژه‌ای که اطلاعات مربوط به کارایی را در مورد قالب فایل و ویژگی‌های متغیر برای داده‌های netCDF-4 ارائه می‌دهند. این مشخصه‌های مجازی ویژه در واقع بخشی از داده‌ها نیستند، بلکه صرفاً روشی مناسب برای نمایش ویژگی‌های گوناگون داده‌ها در CDL (و در نهایت NcML) هستند. این موارد عبارتند از: `_ChunkSizes'، `_DeflateLevel'، `_Endianness'، `_Fletcher32'، `_Format'، `_NoFill'، `_Shuffle'، و `_Storage'. `_ChunkSizes' فهرستی از اندازه‌های قطعات (chunk) برای هر بُعد از متغیر است. `_DeflateLevel' یک عدد صحیح بین 0 تا 9 (شامل هر دو) است در صورتی که فشرده‌سازی برای متغیر مشخص شده باشد. `_Endianness' بسته به اینکه متغیر در زمان نوشتن نخستین بار چگونه ذخیره شده است، `little' یا `big' است. `_Fletcher32' در صورتی که ویژگی جمع کنترلی (checksum) برای متغیر تنظیم شده باشد، برابر `true' است. `_Format' یک مشخصهٔ سراسری است که گونهٔ قالب netCDF را مشخص می‌کند، یکی از موارد `classic'، `64-bit offset'، `netCDF-4' یا `netCDF-4 classic model'. `_NoFill' در صورتی که ویژگی پایدار NoFill برای متغیر در زمان تعریف آن تنظیم شده باشد، برابر `true' است. `_Shuffle' در صورتی که استفاده از فیلتر برزدن (shuffle) برای متغیر تعیین شده باشد، برابر `true' است. `_Storage' بسته به اینکه داده‌های متغیر چگونه ذخیره شده‌اند، `contiguous' یا `compact' یا `chunked' است.
کنترل نحوهٔ نمایش داده‌های زمان، در صورتی که در متغیری ذخیره شده باشند که از نمایشی از زمان سازگار با udunits استفاده می‌کند (مانند `days since 1970-01-01' یا `seconds since 2009-03-15 12:01:17')، یا متغیری که در یک مشخصهٔ "bounds" از چنین متغیر زمانی مشخص شده، یا یک مشخصهٔ عددی از یک متغیر زمان. اگر این گزینه مشخص شود، مقادیر داده‌های زمان به جای مقادیر عددی به صورت رشته‌های تاریخ-زمان خوانا برای انسان و با توجه به مشخصهٔ متغیر `calendar' (در صورت تعیین) نمایش داده می‌شوند. برای مشخصه‌های عددی متغیرهای زمانی، مقدار خوانای زمان پس از مقدار واقعی در یک یادداشت همراهِ CDL نمایش داده می‌شود. مقادیر مشخصهٔ Calendar که با این گزینه تفسیر می‌شوند شامل مقادیر قراردادهای CF مانند `gregorian' یا `standard'، `proleptic_gregorian'، `noleap' یا `365_day'، `all_leap' یا `366_day'، `360_day' و `julian' هستند.
مشابه گزینهٔ '-t'، با این تفاوت که داده‌های زمانی را به صورت رشته‌های تاریخ-زمان با جداکنندهٔ استاندارد 'T' در ISO-8601 به جای فاصله نمایش می‌دهد.
برای فایل‌های netCDF-4، خروجی تنها شامل مقادیر داده‌ها برای گروه‌های مشخص‌شده خواهد بود. یک یا چند گروه باید با نام در فهرستی جداشده با کاما به دنبال این گزینه مشخص شوند. این فهرست باید یک آرگومان واحد برای دستور باشد. گروه‌های نام‌برده باید گروه‌های معتبر netCDF در فایل ورودی باشند. یک گروه در فایل netCDF-4 می‌تواند با یک نام مسیر مطلق یا نسبی مشخص شود. استفاده از نام مسیر نسبی تمام نام‌های گروه‌های منطبق در فایل را مشخص می‌کند. حالت پیش‌فرض، بدون این گزینه و در غیاب گزینه‌های -c یا -h، گنجاندن مقادیر داده‌ها برای همهٔ گروه‌ها در خروجی است.
برای نام فایل‌هایی که درخواست دسترسی از راه دور با استفاده از URLهای DAP را دارند، داده‌ها را با حافظهٔ پنهانِ سمت کلاینت برای متغیرهای کامل واکشی می‌کند.
خروجی دادن XML (به فرمت NcML) به جای CDL. ساختار NcML شامل مقادیر داده‌ها نمی‌شود. گزینهٔ خروجی NcML در حال حاضر فقط برای داده‌های مدل کلاسیک netCDF کار می‌کند.
استفاده از مشخصه‌های _Filter و _Codecs به جای _Fletcher32، _Shuffle و _Deflate.

بررسی ساختار داده‌ها در فایل netCDF با نام `foo.nc':

ncdump -c foo.nc

تولید نسخهٔ CDL یادداشت‌نویسی‌شده از ساختار و داده‌ها در فایل netCDF با نام `foo.nc' با استفاده از نمایه‌گذاری سبک C برای یادداشت‌ها:

ncdump -b c foo.nc > foo.cdl

خروجی دادن داده‌ها فقط برای متغیرهای `uwind' و `vwind' از فایل netCDF با نام `foo.nc'، و نمایش داده‌های ممیز شناور تنها با سه رقم بااهمیتِ دقت:

ncdump -v uwind,vwind -p 3 foo.nc

تولید یک فهرست کاملاً یادداشت‌نویسی‌شده (یک مقدار داده در هر خط) از داده‌ها برای متغیر `omega' با استفاده از قراردادهای فورترن برای نمایه‌ها، و تغییر نام مجموعه دادهٔ netCDF در فایل CDL حاصل به `omega':

ncdump -v omega -f fortran -n omega foo.nc > Z.cdl

ncgen(1), netcdf(3)

با آرایه‌های نویسه‌ای حاوی بایت تهی (null-byte) مانند رشته‌های زبان C رفتار می‌شود، بنابراین هیچ نویسه‌ای پس از بایت تهی در خروجی ظاهر نمی‌شود.

آرایه‌های رشته‌ای چندبُعدی به خوبی مدیریت نمی‌شوند، زیرا نحو CDL برای شکستن یک رشتهٔ نویسه‌ای طولانی به چند خط کوتاه‌تر ضعیف است.

باید روشی برای تعیین این وجود داشته باشد که داده‌ها به ترتیب «رکورد» نمایش داده شوند، یعنی تمام مقادیر متغیرهای رکورد که دارای مقدار یکسانی از بُعد رکورد هستند در کنار هم قرار گیرند.

2012-03-08 Release 4.2