search

dankelley / oce

R package for oceanographic processing
http://dankelley.github.io/oce/
GNU General Public License v3.0
143 stars 42 forks source link

read.amsr() should decode time (and other things) #2219

Closed dankelley closed 4 months ago

dankelley commented 4 months ago

I just noticed that time is not stored in the object returned by read.amsr(). I usually infer that from the filename, but that seems like a bad idea because a user might rename files. FYI, below shows the info in a file I just downloaded.

It looks like we ought to save the start and stop times. I'll decide whether to name them timeStart and timeEnd or just make a 2-element item called time. (I think the former makes more sense but the latter will be easier to guess.

$ ncdump -h RSS_AMSR2_ocean_L3_3day_2024-06-09_v08.2.nc
netcdf RSS_AMSR2_ocean_L3_3day_2024-06-09_v08.2 {
dimensions:
    lon = 1440 ;
    lat = 720 ;
variables:
    float lon(lon) ;
        lon:long_name = "center longitude of grid cell" ;
        lon:standard_name = "longitude" ;
        lon:units = "degrees_east" ;
        lon:valid_min = 0.125f ;
        lon:valid_max = 359.875f ;
        lon:axis = "X" ;
        lon:coverage_content_type = "coordinate" ;
    float lat(lat) ;
        lat:long_name = "center latitude of grid cell" ;
        lat:standard_name = "latitude" ;
        lat:units = "degrees_north" ;
        lat:valid_min = -89.875f ;
        lat:valid_max = 89.875f ;
        lat:axis = "Y" ;
        lat:coverage_content_type = "coordinate" ;
    float SST(lat, lon) ;
        SST:long_name = "AMSR2 sea surface temperature" ;
        SST:standard_name = "sea_surface_temperature" ;
        SST:units = "degrees_Celsius" ;
        SST:valid_min = -3.f ;
        SST:valid_max = 35.f ;
        SST:resolution = "spatial resolution of retrieval is approx. 46km" ;
        SST:coverage_content_type = "physicalMeasurement" ;
        SST:_FillValue = -999.f ;
    float wind_speed_LF(lat, lon) ;
        wind_speed_LF:long_name = "AMSR2 Low Frequency (LF) wind speed" ;
        wind_speed_LF:comment = "AMSR2 10m ocean surface wind speed using 10.65 - 36.5 GHz channels" ;
        wind_speed_LF:standard_name = "wind_speed" ;
        wind_speed_LF:units = "m s-1" ;
        wind_speed_LF:valid_min = 0.f ;
        wind_speed_LF:valid_max = 70.f ;
        wind_speed_LF:resolution = "spatial resolution of retrieval is approx. 32km" ;
        wind_speed_LF:coverage_content_type = "physicalMeasurement" ;
        wind_speed_LF:_FillValue = -999.f ;
    float wind_speed_MF(lat, lon) ;
        wind_speed_MF:long_name = "AMSR2 Medium Frequency (MF) wind speed" ;
        wind_speed_MF:comment = "AMSR2 10m ocean surface wind speed using 18.7 - 36.5 GHz channels" ;
        wind_speed_MF:standard_name = "wind_speed" ;
        wind_speed_MF:units = "m s-1" ;
        wind_speed_MF:valid_min = 0.f ;
        wind_speed_MF:valid_max = 70.f ;
        wind_speed_MF:resolution = "spatial resolution of retrieval is approx. 18km" ;
        wind_speed_MF:coverage_content_type = "physicalMeasurement" ;
        wind_speed_MF:_FillValue = -999.f ;
    float wind_speed_AW(lat, lon) ;
        wind_speed_AW:long_name = "AMSR2 All Weather (AW) wind speed" ;
        wind_speed_AW:comment = "AMSR2 10m ocean surface all-weather wind speed using 6.93 and 10.65 GHz channels" ;
        wind_speed_AW:standard_name = "wind_speed" ;
        wind_speed_AW:units = "m s-1" ;
        wind_speed_AW:valid_min = 0.f ;
        wind_speed_AW:valid_max = 70.f ;
        wind_speed_AW:resolution = "spatial resolution of retrieval is approx. 46km" ;
        wind_speed_AW:coverage_content_type = "physicalMeasurement" ;
        wind_speed_AW:_FillValue = -999.f ;
    float water_vapor(lat, lon) ;
        water_vapor:long_name = "AMSR2 columnar water vapor" ;
        water_vapor:standard_name = "atmosphere_mass_content_of_water_vapor" ;
        water_vapor:units = "kg m-2" ;
        water_vapor:valid_min = 0.f ;
        water_vapor:valid_max = 120.f ;
        water_vapor:resolution = "spatial resolution of retrieval is approx. 18km" ;
        water_vapor:coverage_content_type = "physicalMeasurement" ;
        water_vapor:_FillValue = -999.f ;
    float cloud_liquid_water(lat, lon) ;
        cloud_liquid_water:long_name = "AMSR2 columnar cloud liquid water" ;
        cloud_liquid_water:standard_name = "atmosphere_mass_content_of_cloud_liquid_water" ;
        cloud_liquid_water:units = "kg m-2" ;
        cloud_liquid_water:valid_min = -0.1f ;
        cloud_liquid_water:valid_max = 5.f ;
        cloud_liquid_water:resolution = "spatial resolution of retrieval is approx. 9km" ;
        cloud_liquid_water:coverage_content_type = "physicalMeasurement" ;
        cloud_liquid_water:_FillValue = -999.f ;
    float rain_rate(lat, lon) ;
        rain_rate:long_name = "AMSR2 surface rain rate" ;
        rain_rate:comment = "liquid rain only; does not include snow or ice" ;
        rain_rate:standard_name = "rainfall_rate" ;
        rain_rate:units = "mm h-1" ;
        rain_rate:valid_min = 0.f ;
        rain_rate:valid_max = 25.f ;
        rain_rate:resolution = "spatial resolution of retrieval is approx. 9km" ;
        rain_rate:coverage_content_type = "physicalMeasurement" ;
        rain_rate:_FillValue = -999.f ;
    byte land_mask(lat, lon) ;
        land_mask:long_name = "land mask" ;
        land_mask:standard_name = "land_binary_mask" ;
        land_mask:units = "1" ;
        land_mask:valid_min = 0b ;
        land_mask:valid_max = 1b ;
        land_mask:land_mask_values = "0 = water.  1 = land." ;
        land_mask:flag_masks = 0b, 1b ;
        land_mask:flag_meanings = "water land" ;
        land_mask:coverage_content_type = "auxiliaryInformation" ;
    byte sea_ice_mask(lat, lon) ;
        sea_ice_mask:long_name = "AMSR2 sea ice mask" ;
        sea_ice_mask:comment = "flag is set when sea ice detected is greater than 0%" ;
        sea_ice_mask:standard_name = "sea_ice_extent" ;
        sea_ice_mask:units = "1" ;
        sea_ice_mask:valid_min = 0b ;
        sea_ice_mask:valid_max = 1b ;
        sea_ice_mask:sea_ice_mask_values = "0 = no sea ice detected in grid cell.  1 = sea ice detected in grid cell." ;
        sea_ice_mask:flag_masks = 0b, 1b ;
        sea_ice_mask:flag_meanings = "no_sea_ice_detected sea_ice_detected" ;
        sea_ice_mask:coverage_content_type = "qualityInformation" ;
    byte coast_mask(lat, lon) ;
        coast_mask:long_name = "coast mask" ;
        coast_mask:standard_name = "land_binary_mask" ;
        coast_mask:units = "1" ;
        coast_mask:valid_min = 0b ;
        coast_mask:valid_max = 1b ;
        coast_mask:coast_mask_values = "0 = away from coast.  1 = close to coast." ;
        coast_mask:flag_masks = 0b, 1b ;
        coast_mask:flag_meanings = "away_from_coast close_to_coast" ;
        coast_mask:coverage_content_type = "qualityInformation" ;
    byte noobs_mask(lat, lon) ;
        noobs_mask:long_name = "no observation mask" ;
        noobs_mask:standard_name = "number_of_missing_observations" ;
        noobs_mask:units = "1" ;
        noobs_mask:valid_min = 0b ;
        noobs_mask:valid_max = 1b ;
        noobs_mask:no_observation_values = "0 = observation exists.  1 = no observation." ;
        noobs_mask:flag_masks = 0b, 1b ;
        noobs_mask:flag_meanings = "observation_exists no_observation" ;
        noobs_mask:coverage_content_type = "auxiliaryInformation" ;

// global attributes:
        :Conventions = "CF-1.6" ;
        :title = "RSS AMSR2 V8.2 Air-Sea Essential Climate Variables (AS-ECV)" ;
        :summary = "RSS climate quality air-sea products (SST, wind, vapor, cloud, rain), derived from JAXA microwave radiometer AMSR2 aboard JAXA GCOM-W1, produced by Remote Sensing Systems, gridded at .25 degree resolution in time averaged files, carefully intercallibrated with other microwave radiometers and scatterometers including WindSat, GMI, and ASCAT." ;
        :version = "8.2" ;
        :processing_level = "Level 3: 3 day maps" ;
        :history = "created by RSS" ;
        :date_created = "2024-06-10T14:15:16Z" ;
        :institution = "Remote Sensing Systems, Santa Rosa, CA, USA" ;
        :source = "RSS AMSR2 V8.2 AS-ECV Algorithms" ;
        :sensor = "AMSR2" ;
        :platform = "GCOM-W1" ;
        :instrument = "AMSR2 radiometer" ;
        :project = "Air-Sea Essential Climate Variables (AS-ECV) from Satellite Microwave Radiometers" ;
        :keywords = "sea surface temperature, wind speed, winds in rain, water vapor, cloud liquid water, rain rate, AMSR2, microwave, RSS" ;
        :creator_name = "Frank Wentz, Thomas Meissner, Lucrezia Ricciardulli, Andrew Manaster, Marty Brewer, Michael Densberger, Remote Sensing Systems" ;
        :creator_email = "support@remss.com" ;
        :creator_url = "http://www.remss.com" ;
        :publisher_name = "Remote Sensing Systems" ;
        :publisher_email = "support@remss.com" ;
        :publisher_url = "http://www.remss.com" ;
        :dataset_citation_authors = "Wentz, F., T. Meissner, L. Ricciardulli, A. Manaster, M. Brewer, M. Densberger" ;
        :dataset_citation_year = "2021" ;
        :dataset_citation_product = "Remote Sensing Systems AMSR2 V8.2 Air-Sea Essential Climate Variables (AS-ECV) on 0.25 deg grid" ;
        :dataset_citation_version = "8.2" ;
        :dataset_citation_institution = "Remote Sensing Systems, Santa Rosa, CA, USA" ;
        :dataset_citation_url = "http://www.remss.com/missions/amsr/" ;
        :netCDF_version_id = "4" ;
        :date_def = "starting midnight UTC" ;
        :time_coverage_start = "2024-06-07T00:00:00Z" ;
        :time_coverage_end = "2024-06-09T23:59:59Z" ;
        :time_coverage_duration = "P3D" ;
        :cdm_data_type = "grid" ;
        :geospatial_lat_min = -90.f ;
        :geospatial_lat_max = 90.f ;
        :geospatial_lat_resolution = 0.25f ;
        :geospatial_lat_units = "degrees_north" ;
        :geospatial_lon_min = 0.f ;
        :geospatial_lon_max = 360.f ;
        :geospatial_lon_resolution = 0.25f ;
        :geospatial_lon_units = "degrees_east" ;
        :references = "Source_of_AMSR2_radiometer_observations: JAXA AMSR2 L1A via JAXA G-Portal." ;
        :averaging_procedure = "observations averaged over specified time_coverage_duration" ;
        :acknowledgement = "AMSR2 AS-ECVs are produced by Remote Sensing Systems and sponsored by NASA. We are grateful to JAXA for AMSR2 source data." ;
}
dankelley commented 4 months ago

For reference, here is what an AMSR object, say a, now holds:

a[["?]]
$metadata
[1] "filename"   "flags"      "latitude"   "longitude"  "spacecraft"
[6] "type"       "units"

$metadataDerived
NULL

$data
 [1] "AWwind"     "cloud"      "coastMask"  "landMask"   "LFwind"
 [6] "MFwind"     "noObsMask"  "rain"       "seaIceMask" "SST"
[11] "vapor"

$dataDerived
NULL
dankelley commented 4 months ago

I'll add time and maybe some other things later today.

dankelley commented 4 months ago

The updated read.amsr() saves 6 more entries in the metadata slot. The entries timeEnd, platform, and instrument, are reported by summary(). The entries version, sensor, and references are of less general interest, so they are not reported by summary. Of course, all are available through the [[ mechanism, and are revealed by the [["?"]] scheme.