.. _how_to_write_set_cast_params.m: How to write ``set_cast_params.m`` ================================== We explain in the following the MATLAB script ``set_cast_params.m`` used to process the data with the LDEO sofware during I5S 2009 (see :ref:`set_cast_params.m` for the uninterrupted script). See Section :ref:`which_ancillary_data_do_we_need` and the documentation `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ for details on the ancillary data. Notice that there are many more default parameters that are already set up in ``default.m`` located in ``/home/currents/programs/ladcp_ldeo/routines/``. All default parameters in ``default.m`` can be overwritten in ``set_cast_params.m``. One example is given at the :ref:`end of the script` where one cast was treated without bottom tracking. :: % cruise ID and name of person who processes the data %%%%%%%%%%% p.cruise_id = 'I5S_2009'; .. Write the name of the directory that corresponds to your cruise. We could use ``current_cruise`` but because this parameter is going to be used in the title of the figures, it is better to put the actual name of the cruise. :: p.whoami = 'F. Ascani'; .. Write the name of the LADCP operator. :: % station number %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% p.ladcp_station = stn; .. This is hardwired. Don't change it. :: % filename of the raw LADCP data %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ladcp_datapath = ['/home/science/' p.cruise_id '/data/ladcp/'] .. This is the path to the raw LADCP data. This should be hardwired. Don't change it. :: ladcp_filename_start = 'bb'; .. All raw LADCP data filenames should start with a two-letter prefix: typically ``bb`` if the broad-band instrument is used or ``wh`` if the WorkHorse instrument is used. Put the adequate prefix. Notice that **if the instrument is changed during the cruise** (say from stations 1 to 50, we use the broad-band and from stations 51 to 100, we use the WorkHorse), then you will need to correct the script as follow: :: if stn <=50 ladcp_filename_start = 'bb'; else ladcp_filename_start = 'wh'; end .. or something equivalent. :: ladcp_filename_end = '.dat'; .. This is the suffix of the raw LADCP data filenames. This should be standard. Don't change it. A standard raw LADCP data filename is thus ``bb056_02.dat`` for station #56 corresponding to cast #2. Given the previous parameters, the following lists the raw LADCP data filename for station ``stn``. The first line gives the indeces of the cast number in the raw LADCP data filename. In this example, a typical name is ``bb056_02.dat`` and the cast number ``02`` corresponds to the 7th and 8th characters: :: cast_loc_index = [7 8]; stn_str = sprintf('%03d',stn); [w,ladcp_list]=unix(['ls ' ladcp_datapath ladcp_filename_start stn_str '*' ladcp_filename_end]); if w ~= 0 error('error while reading the LADCP data...') end if size(ladcp_list,1) > 1 error(['multiple files for station: ' stn_str '...']) end ladcp_filename = ladcp_list(1:end-1); cast_str = ladcp_filename(length(ladcp_datapath)+cast_loc_index); .. The rest should be standard and should not be changed. ``ladcp_filename`` should be the full path to the raw LADCP data file and ``cast_str`` gives the actual cast number read in that filename. :: f.ladcpdo = sprintf(ladcp_filename); %f.ladcpup = ('raw/LADCP/%03d',stn); % there is an upward-looking instrument as well .. This is where the full path to the raw LADCP data is entered in the structure ``f`` used by the LDEO program. The first line ``f.ladcpdo`` is for a downward-looking instrument, the second one ``f.ladcpup`` is for an upward-looking instrument. The second line is commented out by a ``%`` because on this cruise --and true also for most CLIVAR cruises--, only a downward-looking instrument was used. In the following, we introduce the parameters concerning ancillary data. First the CTD time series. :: % CTD time series %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% if stn ~= 102 % problem with ctd data for station 102 ctd_data='y' % 'y'=yes, 'n'=no else ctd_data='n'; end .. The above script was added later during the cruise because there was a problem of CTD data at station #102. The script just says that as long as the station is not 102, CTD time series are available. In your case, at least at the beginning, you should only need: :: ctd_data == 'y' % 'y'=yes, 'n'=no .. The following is valid when CTD time series are available. :: if ctd_data == 'y' ctd_datapath = ['/home/science/' p.cruise_id '/data/ctd_timeseries/']; .. This is the full path to the CTD time series. This should be standard. The next step is to look at the filename of the CTD time series. This might change from cruise to cruise. Here a typical example was ``05602.ctd``. Notice the difference with the raw LADCP data filename: The filename has no prefix and it finishes by ``ctd``. This is reflected in the next two lines: :: ctd_filename_start = ''; ctd_filename_end = '.ctd'; .. The next lines build the full path to the CTD time series and enter this value in the structure used by the LDEO software. This should be standard and should not be changed: :: ctd_filename=[ctd_datapath stn_str cast_str ctd_filename_end]; f.ctd = sprintf(ctd_filename); .. The following provides information on the file containing the CTD data. The data should come with a ``README`` file [see for instance :ref:`readme_ctd_ts_I5S_2009`] that gives you all the details needed. * Is there a header? In this case, there was none: :: % number of header lines (before the CTD data start) %%%%%%%%%%%% f.ctd_header_lines = 0; % file layout .. * How many quantities (columns) are in the data? In this case, there were 11 quantities. :: % number of data fields per CTD scan %%%%%%%%%%%%%%%%%%%%%%%%%%%% f.ctd_fields_per_line = 11; .. * What was the number of the column for pressure, temperature, salinity and time? :: % field number for pressure, temperature, salinity and time %%%%% f.ctd_pressure_field = 2; f.ctd_temperature_field = 3; f.ctd_salinity_field = 4; f.ctd_time_field = 1; .. * What was the type of time used? In this case, it was *elapsed time* [see p. 9 in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ for a clear explanation of the different types of time]. :: % time base to use %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.ctd_time_base = 0; % 0=elapsed, 1=year-day, 2=gregorian end .. Now, it is the turn of the GPS data. It is highly recommended that GPS data be included with CTD time series, which should be the case on CLIVAR cruises. :: % GPS data? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% if stn ~=102 % problem with ctd data for station 102 gps_data='y' % 'y'=yes, 'n'=no else gps_data='n'; end .. Again, because of problem at station #102, GPS data --*via* CTD data-- were not available at that station. :: if gps_data == 'y' % GPS filename %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.nav = f.ctd; % if GPS and CTD data are in the same file %f.nav = sprintf('/GPS/%03d',stn); % otherwise .. Here, because GPS data are included with CTD time series, the path to the GPS data is the same as the path to the CTD time series. The line commented out below shows how to give a different path in principle; the exact command will be specific to the cruise. .. The following provides information on the file containing the GPS data: header, total number of fields, columns for time, latitude and longitude, and type of time used: :: % number of header lines (before the GPS data start) %%%%%%%%%%%% f.nav_header_lines = 0; % number of fields per scan %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.nav_fields_per_line = 11; % field number for time, latitude and longitude %%%%%%%%%%%%%%%%% f.nav_time_field = 1; f.nav_lat_field = 10; f.nav_lon_field = 11; % time base to use %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.nav_time_base = 0; % 0=elapsed (default), 1=year-day, 2=gregorian % 0 only if GPS and CTD data are co-recorded end .. See p. 11 in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ for details on GPS data. Especially, be careful of the choice of the time field. Although in the ``README`` file the 9th quantity corresponds to *GPS timestamp* [see for instance :ref:`readme_ctd_ts_I5S_2009`], it is not the time field that needs to be used for the GPS data in ``f.nav_time_field``. The time field that needs to be used is the same as the CTD data, that is the *elapse time*: "*Do not use elapsed time as a time base for GPS data unless the GPS data are co-recorded with the CTD data, in which case it is recommended.*" [See p. 11 in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_]. Although SADCP data were not used to process the LADCP data during the cruise, the following can be used as a basis to use them for processing [See Section 8 in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ ]: :: % SADCP data? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% sadcp_data_from_UH='n' % 'y'=yes, 'n'=no if sadcp_data_from_UH == 'y' % SADCP MATLAB file %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.sadcp = 'SADCP/SADCP.mat'; p.sadcp_dtok = 0 mkSADCP('/ProcessingPC/ADCP/LADDER-1','../data/SADCP/SADCP.mat'); end .. Finally, the following provides information on the file containing the CTD vertical profile. :: % CTD profile? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% if stn ~= 102 % problem with ctd data for station 102 ctdprof = 'y'; else ctdprof = 'n'; end .. Again, there was no data for station #102. The following provides the path to the data. A typical filename is, as for the CTD time series, ``05602.ctd``. The data are organized differently than in the CTD time series, however, but they come also with a ``README`` file that you should consult [see for instance :ref:`readme_ctd_2DB_I5S_2009`]: :: if ctdprof == 'y' ctdprof_datapath = ['/home/science/' p.cruise_id '/data/ctd_2db/']; ctdprof_filename_start = ''; ctdprof_filename_end = '.ctd'; ctdprof_filename=[ctdprof_datapath stn_str cast_str ctdprof_filename_end]; f.ctdprof = sprintf(ctdprof_filename); end .. The following is the last requirement to process the data: estimate the magnetic declination. If GPS data are used, then there is nothing to do. Otherwise, there are two ways to estimate this quantity: either using the routine ``magdev`` that takes the latitude and longitude of the station as input or putting the starting and end position of the ship during the cast. However, "Once GPS time-series data are included in processing it is important that the magnetic declination (``p.drot``, or ``p.poss`` and ``p.pose``) are not set manually" [See p. 4, 5 and 11 in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ ]: :: % magnetic declination %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% if gps_data == 'n' % only if there is no GPS data; if there is, % the magnetic devation will be set using geomag60 p.drot = magdev(-34,73.5) % magnetic declination at 34S and 73.5E %or % p.poss = 0; % start position % p.pose = 0; % end position end .. The following tells the software if the MATLAB files shoud be saved and if ``png`` files should be produced (maybe to put on the web). Because we have our own way to produce figures for the web, we commented the last line out: :: % save matlab files? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% p.savemat = 1; % yes=1, no=0 (default) % save figures? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % p.saveplot_png = []; % yes=nothing, no=1 (default) .. The following is hardwired. Do not change it: :: more off clear pk % basename of the checkpoint files %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.checkpoints = sprintf('checkpoints/%03d',stn); % basename of the output files %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% f.res = sprintf('processed/%03d',stn); % plot title p.name = sprintf('%s cast #%d',p.cruise_id,p.ladcp_station); .. The next line gives the ``.ps`` figures that should be saved. See Appendix F in `LDEO How-To [PDF] <../ProcessingPC/LDEO_howto.pdf>`_ for the list of plots and the comments below to see which figures should be saved: :: % which plot(s) to save (see Appendix F in 'howto.pdf' for the list of plots) % note: ProcFig. 4 will be generated only if CTD data are provided % ProcFig. 12 triggers a mistake when used with auxiliary data % Add ProcFig. 5, 6 and 10 if an uplooker instrument is used % Add ProcFig. 9 for SADCP p.saveplot = [1:4 7:8 11 13:14]; %p.saveplot = []; .. The following is hardwired. Do not change it. :: % The following disables a constraint. Do it in most circumstances ps.smallfac = [1 0]; .. .. _example_no_bottom_tracking: Finally, here is an example where a default value from ``default.m`` can be overwritten. In this case, we do not want bottom tracking to be used on station #2: :: % Specific to stations if stn==2 % try w/o bottom-tracking p.btrk_mode=0; end ..