[272] | 1 | ;+ |
---|
| 2 | ; |
---|
| 3 | ; @file_comments |
---|
| 4 | ; get the time axis from a netcdf_file and transforms it in |
---|
| 5 | ; Julian days of IDL. |
---|
| 6 | ; |
---|
| 7 | ; @categories |
---|
| 8 | ; Read NetCDF file |
---|
| 9 | ; |
---|
| 10 | ; @param filename {in}{required}{type=scalar string} |
---|
| 11 | ; the name of the ncdf_file |
---|
| 12 | ; |
---|
[389] | 13 | ; @param cdfid {in}{optional}{type=scalar} |
---|
| 14 | ; the ID of the ncdf_file, if the file is already open. |
---|
| 15 | ; if not provided, ncdf_gettime open the file defined by filename |
---|
[272] | 16 | ; |
---|
| 17 | ; @keyword TIMEVAR {type=string} |
---|
| 18 | ; It define the name of the variable that |
---|
| 19 | ; contains the time axis. This keyword can be useful if there |
---|
| 20 | ; is no unlimited dimension or if the time axis selected by default |
---|
| 21 | ; (the first 1D array with unlimited dimension) is not the good one. |
---|
| 22 | ; |
---|
[370] | 23 | ; @keyword CALLER {required}{type=string} |
---|
[272] | 24 | ; Used to specify the error messages. Give the name of the calling |
---|
[370] | 25 | ; procedure. It can be only '<pro>read_ncdf</pro>' or '<pro>scanfile</pro>'. |
---|
[272] | 26 | ; |
---|
[401] | 27 | ; |
---|
| 28 | ; @keyword CALTYPE |
---|
| 29 | ; Used to specify (or orverwrite) the type of calendar that should be |
---|
| 30 | ; used. We accept only 'noleap', '360d', 'greg' and 'gregorian'. By |
---|
| 31 | ; default, we use the type of calendar defied in the attibute |
---|
| 32 | ; calendar. if not, we define it as gregorian. |
---|
| 33 | ; |
---|
[272] | 34 | ; @keyword ERR |
---|
| 35 | ; Set this keyword to a named variable in which the value of the error |
---|
| 36 | ; message will be returned |
---|
| 37 | ; |
---|
| 38 | ; @keyword _EXTRA |
---|
| 39 | ; _EXTRA to be able to call ncdf_getmask with _extra keyword |
---|
| 40 | ; |
---|
| 41 | ; @returns |
---|
| 42 | ; a double 1D array of IDL Julian days |
---|
| 43 | ; In case of error return -1 if the time dimension was not found |
---|
[297] | 44 | ; or return -jpt if it as been found that the time dimension size is jpt |
---|
[272] | 45 | ; |
---|
| 46 | ; @restrictions |
---|
| 47 | ; the calendar variable must have the units attribute |
---|
[358] | 48 | ; following the syntax below: |
---|
[272] | 49 | ; |
---|
| 50 | ; time_counter:units = "seconds since 0001-01-01 00:00:00" ; |
---|
| 51 | ; time_counter:units = "hours since 0001-01-01 00:00:00" ; |
---|
| 52 | ; time_counter:units = "days since 1979-01-01 00:00:00" ; |
---|
| 53 | ; time_counter:units = "months since 1979-01-01 00:00:00" ; |
---|
| 54 | ; time_counter:units = "years since 1979-01-01 00:00:00" ; |
---|
| 55 | ; |
---|
| 56 | ; @history |
---|
| 57 | ; August 2007: Sebastien Masson (smasson\@lodyc.jussieu.fr) |
---|
| 58 | ; |
---|
| 59 | ; @version |
---|
| 60 | ; $Id$ |
---|
| 61 | ;- |
---|
[401] | 62 | FUNCTION ncdf_gettime, filename, cdfid, CALTYPE = caltype $ |
---|
[389] | 63 | , TIMEVAR = timevar, CALLER = caller, ERR = err, _EXTRA = ex |
---|
[272] | 64 | ; |
---|
| 65 | compile_opt idl2, strictarrsubs |
---|
| 66 | ; |
---|
| 67 | @cm_4cal ; needed for key_caltype |
---|
| 68 | ; |
---|
[389] | 69 | IF n_elements(cdfid) EQ 0 THEN BEGIN |
---|
[396] | 70 | cdfid = ncdf_open(isafile(filename, title = 'which file must be open by ncdf_gettime?', IODIRECTORY = iodir, _extra = ex)) |
---|
[389] | 71 | tobeclosed = 1 |
---|
| 72 | ENDIF |
---|
[272] | 73 | inq = ncdf_inquire(cdfid) |
---|
| 74 | ;---------------------------------------------------- |
---|
| 75 | ;`find the variable containing the time axis |
---|
| 76 | ;---------------------------------------------------- |
---|
| 77 | ; we get its name through the keyword timevar |
---|
| 78 | IF keyword_set(timevar) THEN BEGIN |
---|
| 79 | timeid = ncdf_varid(cdfid, timevar) |
---|
[389] | 80 | IF timeid EQ -1 THEN BEGIN ; the variable is not found |
---|
[272] | 81 | CASE caller OF |
---|
| 82 | 'read_ncdf':err = 'No variable ' + timevar + 'found in '+filename+'. Use the TIMESTEP keyword' |
---|
| 83 | 'scanfile':err = 'No variable ' + timevar + 'found in '+filename+'. We create a fake calendar' |
---|
| 84 | ENDCASE |
---|
[389] | 85 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 86 | return, -1 |
---|
| 87 | ENDIF |
---|
| 88 | timeinq = ncdf_varinq(cdfid, timeid) |
---|
| 89 | inq.recdim = timeinq.dim[0] |
---|
| 90 | ncdf_diminq, cdfid, inq.recdim, timedimname, jpt |
---|
| 91 | ENDIF ELSE BEGIN |
---|
| 92 | ; we try to find the time axis automatically |
---|
| 93 | ; we look for the infinite dimension |
---|
| 94 | IF inq.recdim EQ -1 THEN BEGIN |
---|
| 95 | CASE caller OF |
---|
| 96 | 'read_ncdf':err = 'the file '+filename+' as no infinite dimension. !C Use TIMESTEP or TIMEVAR keyword' |
---|
| 97 | 'scanfile':err = 'the file '+filename+' as no infinite dimension. We create a fake calendar' |
---|
| 98 | ENDCASE |
---|
[389] | 99 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 100 | return, -1 |
---|
| 101 | ENDIF |
---|
| 102 | ncdf_diminq, cdfid, inq.recdim, timedimname, jpt |
---|
| 103 | ; we look for the variable containing the time axis |
---|
| 104 | ; we look for the first variable having for only dimension inq.recdim |
---|
| 105 | timeid = 0 |
---|
[389] | 106 | REPEAT BEGIN ; As long as we have not find a variable having only one dimension: the infinite one |
---|
[272] | 107 | timeinq = ncdf_varinq(cdfid, timeid) ; that the variable contain. |
---|
[438] | 108 | tstok = n_elements(timeinq.dim) EQ 1 AND timeinq.dim[0] EQ inq.recdim |
---|
[272] | 109 | timeid = timeid+1 |
---|
[438] | 110 | ENDREP UNTIL tstok OR timeid EQ inq.nvars |
---|
[439] | 111 | IF NOT tstok THEN BEGIN |
---|
[272] | 112 | CASE caller OF |
---|
| 113 | 'read_ncdf':err = 'the file '+filename+' as no time axis variable. !C Use the TIMESTEP keyword' |
---|
[407] | 114 | 'scanfile':err = 'the file '+filename+' has no time axis.!C we create a fake calendar ...' |
---|
[272] | 115 | ENDCASE |
---|
[389] | 116 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 117 | return, -jpt |
---|
| 118 | ENDIF |
---|
| 119 | timeid = timeid-1 |
---|
| 120 | ENDELSE |
---|
| 121 | ;---------------------------------------------------- |
---|
| 122 | ; look for attribute units and calendar to know how to compte the calendar |
---|
| 123 | ;---------------------------------------------------- |
---|
| 124 | ; no attribute for time variable... |
---|
| 125 | IF timeinq.natts EQ 0 then begin |
---|
| 126 | CASE caller OF |
---|
| 127 | 'read_ncdf':err = 'the variable '+timeinq.name+' has no attribute.!C Use the TIMESTEP keyword' |
---|
| 128 | 'scanfile':err = 'the variable '+timeinq.name+' has no attribute.!C we create a fake calendar ...' |
---|
| 129 | ENDCASE |
---|
[389] | 130 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 131 | return, -jpt |
---|
| 132 | ENDIF |
---|
| 133 | ; get attributes names |
---|
| 134 | attnames = strarr(timeinq.natts) |
---|
| 135 | for attiq = 0, timeinq.natts-1 do attnames[attiq] = strlowcase(ncdf_attname(cdfid, timeid, attiq)) |
---|
| 136 | ; do we find units attribute? |
---|
| 137 | IF (where(attnames EQ 'units'))[0] EQ -1 then BEGIN |
---|
| 138 | CASE caller OF |
---|
| 139 | 'read_ncdf':err = 'Attribute ''units'' not found for the variable '+timeinq.name+' !C Use the TIMESTEP keyword' |
---|
| 140 | 'scanfile':err = 'Attribute ''units'' not found for the variable '+timeinq.name+'!C we create a fake calendar ...' |
---|
| 141 | ENDCASE |
---|
[389] | 142 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 143 | return, -jpt |
---|
| 144 | ENDIF |
---|
| 145 | ; Is attribute "calendar" existing? |
---|
| 146 | ; If no, we suppose that the calendar is gregorian calendar |
---|
| 147 | ; |
---|
[344] | 148 | ncdf_getatt, cdfid, timeid, calendar = calendar, units = value |
---|
[401] | 149 | IF keyword_set(caltype) THEN calendar = strlowcase(caltype) |
---|
[344] | 150 | CASE calendar OF |
---|
| 151 | 'noleap':key_caltype = 'noleap' |
---|
| 152 | '360d':key_caltype = '360d' |
---|
| 153 | 'greg':key_caltype = 'greg' |
---|
[401] | 154 | 'gregorian':key_caltype = 'greg' |
---|
| 155 | ELSE:BEGIN |
---|
| 156 | dummy = report( ['unknow calendar type: '+calendar, 'we use gregorian calendar'] ) |
---|
| 157 | key_caltype = 'greg' |
---|
| 158 | END |
---|
[344] | 159 | ENDCASE |
---|
[272] | 160 | ;---------------------------------------------------- |
---|
| 161 | ; decode units attribute |
---|
| 162 | ;---------------------------------------------------- |
---|
| 163 | ; |
---|
[396] | 164 | value = strlowcase(value) |
---|
| 165 | IF value NE 'true julian day' THEN BEGIN |
---|
[272] | 166 | ; time_counter:units = "seconds since 0001-01-01 00:00:00" ; |
---|
| 167 | ; time_counter:units = "hours since 0001-01-01 00:00:00" ; |
---|
| 168 | ; time_counter:units = "days since 1979-01-01 00:00:00" ; |
---|
| 169 | ; time_counter:units = "months since 1979-01-01 00:00:00" ; |
---|
| 170 | ; time_counter:units = "years since 1979-01-01 00:00:00" ; |
---|
| 171 | ; |
---|
| 172 | ; we decript the "units" attribute to find the time origin |
---|
[396] | 173 | words = str_sep(value, ' ') |
---|
| 174 | units = words[0] |
---|
| 175 | IF strpos(units, 's', strlen(units)-1) NE -1 THEN units = strmid(units, 0, strlen(units)-1) |
---|
| 176 | IF strpos(units, 'julian_') NE -1 THEN units = strmid(units, 7) |
---|
| 177 | IF units NE 'second' AND units NE 'hour' AND units NE 'day' $ |
---|
| 178 | AND units NE 'month' AND units NE 'year' THEN BEGIN |
---|
| 179 | CASE caller OF |
---|
| 180 | 'read_ncdf':err = 'time units does not start with seconds/hours/days/months/years !C Use the TIMESTEP keyword' |
---|
| 181 | 'scanfile':err = 'time units does not start with seconds/hours/days/months/years !C we create a fake calendar ...' |
---|
| 182 | ENDCASE |
---|
| 183 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
| 184 | return, -jpt |
---|
| 185 | ENDIF |
---|
| 186 | IF stregex(value, '[^ ]* since ([0-9]){1,4}-([0-9]){1,2}-([0-9]){1,2}.*', /boolean) EQ 0 THEN BEGIN |
---|
| 187 | CASE caller OF |
---|
| 188 | 'read_ncdf':err = 'attribute units of time has not the good format: [^ ]* since ([0-9]){1,4}-([0-9]){1,2}-([0-9]){1,2}.*!C Use the TIMESTEP keyword' |
---|
| 189 | 'scanfile':err = 'attribute units of time has not the good format: [^ ]* since ([0-9]){1,4}-([0-9]){1,2}-([0-9]){1,2}.*!C we create a fake calendar ...' |
---|
| 190 | ENDCASE |
---|
| 191 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
| 192 | return, -jpt |
---|
| 193 | ENDIF |
---|
| 194 | start = str_sep(words[2], '-') |
---|
| 195 | ENDIF ELSE units = value |
---|
[272] | 196 | ;---------------------------------------------------- |
---|
| 197 | ; compute time axis |
---|
| 198 | ;---------------------------------------------------- |
---|
| 199 | ncdf_varget, cdfid, timeid, time |
---|
| 200 | time = double(time) |
---|
[396] | 201 | case units OF |
---|
| 202 | 'true julian day': |
---|
[272] | 203 | 'second':time = julday(start[1], start[2], start[0], 0, 0, 0)+time/86400.d |
---|
| 204 | 'hour':time = julday(start[1], start[2], start[0], 0, 0, 0)+time/24.d |
---|
| 205 | 'day':time = julday(start[1], start[2], start[0], 0, 0, 0)+time |
---|
| 206 | 'month':BEGIN |
---|
| 207 | if total(fix(time) NE time) NE 0 then $ ; we switch to days with 30d/m |
---|
[396] | 208 | time = julday(start[1], start[2], start[0], 0, 0, 0) + round(time*30) $ |
---|
| 209 | ELSE time = julday(start[1]+fix(time), replicate(start[2], jpt), replicate(start[0], jpt), 0, 0, 0) |
---|
[272] | 210 | END |
---|
| 211 | 'year':BEGIN |
---|
| 212 | if total(fix(time) NE time) NE 0 then $ ; we switch to days with 365d/y |
---|
[396] | 213 | time = julday(start[1], start[2], start[0], 0, 0, 0) + round(time*365) $ |
---|
| 214 | ELSE time = julday(replicate(start[1], jpt), replicate(start[2], jpt), start[0]+fix(time), 0, 0, 0) |
---|
[272] | 215 | END |
---|
| 216 | ENDCASE |
---|
| 217 | time = double(time) |
---|
| 218 | ; |
---|
[389] | 219 | IF keyword_set(tobeclosed) THEN ncdf_close, cdfid |
---|
[272] | 220 | return, time |
---|
| 221 | END |
---|