Frequently Asked Questions (FAQ's)

Contents

1. The program executes, but the output files are empty or missing?
2. The program executes, output files are created, but data for one or more ptts (or animals) are missing?
3. Some obviously aberrant locations are included in the filtered output data?
4. The filtered output data files contain locations with implausible movement rates?
5. The filtered output data files that “pick” the best location per duty cycle (or per day) are effectively empty, or they have large data gaps?
6. What values should be assigned to the User Defined Parameters?
7. What are the accuracies of the locations in the output data sets?

1. The program executes, but the output files are empty or missing?

This symptom is almost always caused by a syntax error in the deployment logic blocks.  Under such an error condition, you’ll find that the program will execute unusually fast (<15 seconds).

Solution:

You need to critically study every line of each deployment logic block and ensure that the SAS language was encoded correctly.

Below is a correctly coded logic block:

  if ptt   = 16976
     and thetime gt '12NOV1998:11:30:00'dt
     and thetime lt '31DEC2002:00:00:00'dt then do;
     animal = 'FOX41';
     dtime  = '12NOV1998:11:30:00'dt;
     deplat = 70.255;
     deplon = -148.368;
  end;

Study each logic block, and watch for problems pertaining to any of these commonly made “typos”:

1. All text shown in black font is intact and unchanged.
2. The date-times are bounded by single quotes, and then suffixed with “dt”.
3. The date-time month notation must follow the 3-letter SAS naming convention:  JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC.
4. The animal variable is bounded by single quotes.
5. The first and second lines do not terminate with a semicolon, but all others do.
6. There must be an “end” statement closing each if-then-do block.

Other possible solutions:

Study your SAS Log, from beginning-to-end.  Look for any “ERROR” messages, which are typically printed in red font.  If found, critically study the first occurrence of an ERROR message (since subsequent ERRORS are typically generated as a consequence of the first one). 

A common ERROR message will indicate “File Not Found”, or “Directory Does Not Exist”.  This indicates you have either:  1) incorrectly documented the directory pathnames and/or filenames for your computer; or 2) you do not have a complete set of the SAS filtering program files.

Below are the 6 directory paths, and 1 file name that must conform to your hard drive naming convention.  Again, all text in black font must be intact and unchanged. 

%let deploys = c:\argos\projects\generic\sas\example_deployments.txt;
%let sasroot = c:\argos\projects\generic\sas;
%let diaroot = c:\argos\projects\generic\rawdiag;
%let ascroot = c:\argos\projects\generic\ascii;
%let kmlroot = c:\argos\projects\generic\kml;
%let arcroot = c:\argos\projects\generic\arcview;

Study your SAS code, and validate that:

1. All directories exist on your hard drive.
2. The filename of YOUR deployment logic-block definition file is correct.
3. Each line terminates with a semicolon.
4. All of these program distribution files are present in the directory defined in line #2 (e.g. the “sasroot” directory):

animal_tmpl2.apr
argosfilterv702.sas
calc_dar3.sas
cost_estimate.sas
hardcode_changes.txt
proc_export.sas
weedrate3.sas
weedrate4.sas
weedrate64_both.sas
weedrate64_mrd.sas
write_arcview5.sas
write_kml.sas
CNTRY92.DBF
CNTRY92.SHP
CNTRY92.SHX

You will likely have changed the names of these two program distribution files, after you have modified them.  They can exist anywhere on your hard drive.
 
example_deployments.txt
generic_runv702.sas

2. The program executes, output files are created, but data for one or more ptts (or animals) are missing?

This symptom indicates a logic problem in your deployment logic-block definition file.

Recall the logic-block format:

  if ptt   = 16976
     and thetime gt '12NOV1998:11:30:00'dt
     and thetime lt '31DEC2002:00:00:00'dt then do;
     animal = 'FOX41';
     dtime  = '12NOV1998:11:30:00'dt;
     deplat = 70.255;
     deplon = -148.368;
  end;
 
Solutions:

1. The first and second date-time entries (lines #2 and #3) temporally bound the deployment interval of the ptt on the respectively defined animal.  Make sure these bounding dates are valid.  Also ensure that the date-time defined for “dtime” is exactly the same as that defined in line #2.
2. Verify that deployment locations in the southern hemisphere are coded with negative latitude and those in the western hemisphere are coded with negative longitude.

If your input DIAG data contain records of a single PTT deployed on more than one animal, then verify that your respective logic-blocks possess non-overlapping, temporal continuity.  For example:

  if ptt   = 16976
     and thetime gt '12NOV1998:11:30:00'dt
     and thetime lt '31DEC2002:00:00:00'dt then do;
     animal = 'FOX41';
     dtime  = '12NOV1998:11:30:00'dt;
     deplat = 70.255;
     deplon = -148.368;
  end;
  if ptt   = 16976
     and thetime gt '03MAY2004:21:10:00'dt
     and thetime lt '31DEC2009:00:00:00'dt then do;
     animal = 'GOOSE_4332';
     dtime  = '03MAY2004:21:10:00'dt;
     deplat = 61.378;
     deplon = -159.295;
  end;

Above, the first logic-block places ptt 16976 on a fox on 12 November 1998.  The ptt provided data until some unknown time in 2002, so the deployment is liberally extended to the end of 2002 to ensure that no data are truncated (but this date should be before the ptt is rebuilt and tested).  Ptt 16976 was rebuilt during the spring of 2004, and then deployed on a goose in early May, with termination of the deployment dated well into the future (2009).

Alternatively, if your input DIAG data contain records of more than one PTT being deployed on the same animal, then verify that your respective logic-blocks possess non-overlapping, temporal continuity.  For example:

  if ptt   = 16976
     and thetime gt '31JUL2004:14:45:00'dt
     and thetime lt '15AUG2005:16:30:00'dt then do;
     animal = 'BEAR_65A';
     dtime  = '31JUL2004:14:45:00'dt;
     deplat = 55.927;
     deplon = -101.684;
  end;
  if ptt   = 63498
     and thetime gt '15AUG2005:16:30:01'dt
     and thetime lt '31DEC2009:00:00:00'dt then do;
     animal = 'BEAR_65A';
     dtime  = '15AUG2005:16:30:01'dt;
     deplat = 54.327;
     deplon = -99.936;
  end;

Above, the first logic-block places ptt 16976 on a bear on 31 July 2004.  The next summer, on 15 August, the same bear was recaptured and fitted with a new ptt (63498). The deployment of the second ptt begins 1 second after the termination of the first deployment; hence, the output data for this animal will be continuous despite the fact that the animal wore more than one ptt.

Other possible solutions:

If the format of the raw Argos DIAG data has been corrupted, then it won’t input correctly and it will be omitted from the output files.  The DIAG data files must have ASCII text file format.  You should not attempt to “edit” your raw DIAG files: even removing a blank space, or including an extraneous one, will cause the input statements to fail for the respective overpass.

The directory that contains your DIAG data should not contain any files that are not ASCII text.  If binary files such as Word documents, Excel spreadsheets, etc., exist in the DIAG directory, the program will attempt to read them and likely crash altogether.

3. Some obviously aberrant locations are included in the filtered output data?

This symptom is common to large tracking data sets, and most often occurs because the program made an incorrect choice between the primary and alternate locations for one or more overpasses.  In large data sets, there is invariably some peculiar sequence of overpasses that contain primary and alternate locations whose spatial configurations confuse my algorithm that chooses between the two Argos solutions.  This is one of the biggest reasons I recommend you “quality control” the filter output.  In my experience, there are always a few very gross anomalies that pass the plausibility tests, and the problems often trace back to an incorrect choice between the primary and alternate locations.

Solution:

1. Study plausibility of both the primary and alternate locations for the overpass in question (variables lat_p, lon_p and lat_a, lon_a in the output data sets), and compare them with the location that the algorithm chose (latitude, longitud in the output data sets).  Make note of the value of the “line” variable for the record in question, you’ll need it to hard-code a solution (see #6 below).
2. If there is a chronologic sequence of bad locations, then focus on the first occurrence because resolving that problem will often fix the subsequent ones.
3. If both the primary and alternate locations are implausible, then the overpass should be entirely removed from the input data set (see #6 below for method).
4. If the primary location is plausible, but the algorithm chose the alternate, then the primary location should be “hard-coded” into the input data set (see #6 below for method).
5. If the alternate location is plausible, but the algorithm chose the primary, then the alternate location should be “hard-coded” into the input data set (see #6 below for method).

6. Modify the accompanying “hardcode_changes.txt” ASCII text file to include the necessary changes pertaining to any anomalies that need resolution, then re-execute the filtering algorithm and re-verify the filtered output.  Do not change the name of the file, nor its directory location.  Be sure to save the file as ASCII text (using the NotePad text editor helps to ensure the ASCII format is maintained). Instructions on how to modify the hardcode_changes.txt file are provided within the file itself.  For example:

The logic-block below will force selection of the primary location (by over-writing the alternate location) for the overpass identified by the unique “line” variable 726107062001:142301Z99.  Note that a message is written to the SAS log file to confirm the change was implemented.

if line = '726107062001:142301Z99' then do;
  lat_a = lat_p;
  lon_a = lon_p;
  file log;
  put 'HARDCODED PRIMARY LOCATION CHOICE' line=;
end;

The logic-block below will force selection of the alternate location (by over-writing the primary location) for the overpass identified by the unique “line” variable.

if line = '726107062001:142301Z99' then do;
  lat_p = lat_a;
  lon_p = lon_a;
  file log;
  put 'HARDCODED ALTERNATE LOCATION CHOICE' line=;
end;

The logic-block below will entirely remove the overpass identified by the unique “line” variable

if line = '726010162000:210745Z99' then do;
  file log;
  put 'HARDCODED AN OVERPASS REMOVAL' line=;
  return;
end;

Other possible solutions:

In the Program Version 7.02, a new user option (CROSSVAL) was introduced that affects how the algorithm chooses between the primary and alternate locations. 

If you are tracking an animal that can move hundreds of kilometers between locations (which most frequently occurs between duty-cycles of ptts attached to migrating birds), then you should first try setting CROSSVAL = 1.  Setting CROSSVAL = 1 implements the logic that was used in all previous versions.  The logic was prepared to resolve a problem we encountered when tracking birds that migrated from Alaska to Siberia.  For example, consider a bird that flies entirely from Alaska to Russia during a period when the ptt is not transmitting (e.g. between duty cycles).  Then, when the bird is FIRST located in Russia, consider what happens if the alternate location falls in between Alaska and Russia (say, near the Aleutian Islands).  Using only minimum travel-distance criteria to select between the primary and alternate locations would cause the location in between Alaska and Russia to be incorrectly chosen, giving the undocumented impression that the bird followed the Aleutian Chain in route to Russia.  So, additional logic was programmed to reassess the choices by “looking ahead” one overpass to cross validate the decisions.  In the preceding example, the subsequent overpass would have likely confirmed the bird’s presence in Russia, so the initial choice of the location in the Aleutian Islands would be over-ridden in favor of its image location that was in Russia to begin with.  When the initial decision between primary and alternate is “over ridden” during the reassessment, the SWITCH variable in the output data sets has a value of either 3 or 4.

So, if you’re tracking a highly mobile animal that can move hundreds of kilometers between locations: set CROSSVAL = 1, run the program, and then critically review all overpasses where SWITCH = 3 or SWITCH = 4.  Were the choices to over-ride the initial decision good ones?  Or, did they mostly (or entirely) result in bad choices?  If they appear to be bad choices, then set CROSSVAL = 0, run the program, and hopefully things will improve.

But, if you’re tracking a more sedentary animal that does not move great distances (hundreds of km) between locations, simply set CROSSVAL = 0. It’s becoming more apparent that the cross validation logic seems to create more problems than it resolves for more sedentary animals.

Neither value for CROSSVAL will likely resolve all problems associated with incorrect choices between the primary and alternate locations, meaning some number of manual interventions using the hardcode_changes.txt file will probably be necessary.

4. The filtered output data files contain locations with implausible movement rates?

Both filtering methods (MRD and DAR) will invariably contain movement rates greater than that specified by the user-defined MINRATE threshold.  In the case of the MRD filter, rate of movement is not used for any plausibility checking.  In the case of the DAR (distance-angle-rate) filter, rate of movement is NOT considered IF the associated distance traveled is less than the MAXREDUN threshold. 

In other words, the MAXREDUN threshold is also important to the DAR filtering logic.  If two consecutive locations are separated by less than the distance that was defined as representing spatial redundancy, then the associated rate of movement between the two locations is ignored.  Consider the proverbial “ptt on a fence post”.  Pairs of consecutive locations may possess reasonable accuracy, but if the two respective satellite overpasses are nearly coincident in time, very high movement rates will result.  For example, if two satellites pass over a ptt at the same time (the animal is functionally stationary), the derived locations may be quite accurate but only seconds apart, resulting in a very high, artificial movement rate.  Near-synchronous satellite orbits occur more frequently at polar latitudes; and globally, since Argos has freely implemented multi-satellite service for animal tracking studies.  Rather than filtering either, both locations are retained because they provide mutually corroborating evidence that the animal (probably) occupied the respective locale (where the spatial scale of a locale is dictated by the user’s choice for MAXREDUN).

Suggestion:

If you examine the output data from the DAR and MRD filters (r#d#lc#.txt and d#lc#.txt, respectively), you should find that the vast majority of records with movement rates greater than your MINRATE threshold will be associated with distances that are less than your MAXREDUN threshold.  These records should not concern you for the reason described above.  However, records where both MINRATE and MAXREDUN exceed your thresholds may be useful indicators where the filtering logic failed and manual intervention (i.e. “hardcode_changes.txt”) is warranted.  Examine the following attributes for each record where both MINRATE and MAXREDUN were exceeded:

1. Is it the “LATEST” (most recent) location for the respect animal?  The last location for each animal in NEVER filtered by the DAR logic because it lacks sufficient data (i.e. a subsequent location).  If both the primary and alternate location for the last overpass are considered implausible, the overpass should be deleted from in the input data (i.e. hardcode_changes.txt”).
2. Does the location class quality index meet or exceed that which you specified in the KEEP_LC user option?  Recall that locations with acceptable Argos location class quality indices (those that meet or exceed your KEEP_LC threshold) are never filtered.  If such a location is associated with an implausible rate of movement over a distance that exceeds MAXREDUN, then manual intervention (i.e. hardcode_changes.txt) may be warranted.  Note that the preceding location may be the source of the problem, especially if the preceding location has an auxiliary location quality (i.e. LC 0, A, B, or Z).
3. If the record is from the MRD data set (d#lc#.txt), it may be indicating a pair of spatially-redundant consecutive locations that were not filtered but were in fact both erroneous (and now elucidated by the fact that either their outbound or inbound vectors possess an implausible movement rate).  The MRD filter is premised on the observation that Argos locations rarely make gross errors in the same locale, twice (consecutively) – but it’s not impossible.  So be very suspicious of two consecutive MRD locations if either one is associated with implausible rates of movement over distances that exceed MAXREDUN, especially if both locations possess auxiliary location qualities (0,A,B, or Z).  You may find that such instances (an erroneous pair of locations associated with an outbound or inbound rate) in the MRD output are absent from the MRD-DAR Hybrid output (br#d#lc#.txt), because the Hybrid results (beginning in version 7.02) are parsed through a final rate-only plausibility filter.

Note: In the “pick” output data sets, which contain just one location per duty cycle (or one location per day), the movement rates should not exceed the MINRATE threshold.  If you find such instances, manual intervention may be warranted (hardcode_changes.txt).

5. The filtered output data files that “pick” the best location per duty cycle (or per day) are effectively empty, or they have large data gaps?

This symptom is typical when the user has not correctly defined the MINOFFH parameter.  Please read the instructions in the User Manual for determining a value for MINOFFH.

If one MINOFFH value is not applicable for all of the ptts in your input data (e.g. some ptts had duty cycles while others transmitted continuously, and you want to “pick” the best location per duty cycle for the cycled ptts, but “pick” the best location per day for the continuous ptts), then you will need to execute the filtering algorithm independently for each group of ptts, which is easily accomplished by creating two different (respective) “deployment definition” files.

6. What values should be assigned to the User Defined Parameters?

Preface:

If you have evaluated this algorithm, please consider sharing the User Defined Parameter values that you applied for your study.  If you email me (david_douglas@usgs.gov) a listing of your parameters, along with your filtering preference (MRD vs. DAR vs. the “Both” Hybrid), I will post them at this website.  This will not only help others get started, but may also help promote standardization among published studies.

Examples of species-specific User Defined Parameters that have been implemented in past studies:

Bar-headed Goose
            [Contributed by David Douglas, USGS Alaska Science Center]
Northern Right Whale
            [Contributed by David Douglas, USGS Alaska Science Center]
Golden Eagle
            [Contributed by David Douglas, USGS Alaska Science Center]

Introduction:

The filtering algorithm was intentionally written to give the user control of key filtering parameters, because no single fixed-set of parameters is applicable to all species.  The choice of parameter values depends largely on: 1) species; and 2) the analytical scale of spatial interpretation; and to a lesser degree on other factors such as ptt design and ptt attachment (as it pertains to the amount and quality of data you ultimately receive).  Since, one size does not fit all – you must consider your species, the overall quality of your data, and your anticipated scale of spatial interpretation.

Keep in mind that when you set KEEP_LC = 1, filtering is only performed on the auxiliary locations (LC 0, A, B, Z).  Many published analyses of Argos data have used only standard location classes (LC 1, 2, 3).  The over-arching purpose of this algorithm is to make more reliable use of the auxiliary location classes.  If you find, however, that including filtered auxiliary locations does not enhance the biological interpretations you’d make using LC 1, 2, 3 locations alone, then you should seriously consider employing the very parsimonious filtering method of simply restricting your analyses to the standard location classes (LC 1, 2 and 3).

Suggestions:

Three user-defined variables play a dominant role (MAXREDUN, MINRATE, and KEEP_LC) – below are some guidelines.

MAXREDUN (and KEEP_LC): 

1. If you are studying continental scale movements such as long distance migratory birds that travel thousands of kilometers, use MAXREDUN = 15 (with KEEP_LC = 1).
2. If you are studying inter-state movements on the scale of hundreds of kilometers, such as between states with a region of the conterminous US or between a cluster of countries in Europe, use MAXREDUN = 10 (with KEEP_LC = 1).
3. If you are studying intra-state movements on the scale of tens to hundreds of kilometers, then use MAXREDUN = 5 (with KEEP_LC = 1).

If you are considering more local scale interpretations then beware, you’re asking a lot of Argos Doppler-derived locations.  You might start by comparing #3 above with results from MAXREDUN = 3 and KEEP_LC = 2, and with MAXREDUN = 2 and KEEP_LC = 3.  In each case, the filtering will remove more and more data. The remaining data will probably be more and more robust to local-scale errors, but at the expense of sample size.  How well you may be able to address local-scale interpretations depends a lot on the quality of your DIAG data (i.e. the relative frequency of high-quality location classes, which will be a function of your duty cycle, output power, latitude, and many other factors). 

MINRATE

While we know that animals can attain their peak movement rates over short intervals of time, MINRATE should reflect an expected sustained (migratory) movement rate over a relatively longer periods (say, at least an hour or more).  It’s risky to try and use Argos Doppler-derived locations to estimate peak movement rates for highly mobile species.  Since absolute peak movement rates will occur over short intervals, the measured distance of travel will include a greater fraction of Argos location error, but perhaps even more important is that if an animal is rapidly moving, then accuracy of the Argos location is severely compromised by the movement itself.
 
I suggest establishing the MINRATE value by asking:  What is an expected minimum sustained migration velocity for the species, keeping in mind potential environmental factors that could facilitate the velocity, such as tailwinds or trailing ocean currents.  As examples, I have used these MINRATE values in the past:

Whale:               14 km/hr
Walrus:                8 km/hr
Eagle:               100 km/hr
Caribou:             10 km/hr
Sea Turtle:          7 km/hr

7. What are the accuracies of the locations in the output data sets?

Presented below are preliminary results of two evaluations (free-ranging geese and captive eiders) that compare unfiltered (raw) Argos location accuracy to the accuracy of locations that passed the filtering plausibility tests.  A third example is presented (whale) that qualitatively compares manual filtering decisions to those of the filtering algorithm.

FREE-RANGING GEESE

This evaluation uses data from 4 Argos-linked, solar powered, GPS receivers that were built by Microwave Telemetry and harnessed to free-ranging bar-headed geese to track their trans-Himalaya migrations from India and Nepal to Tibet during 2005 [data from John Takekawa, USGS].  The GPS receivers attempted 16 locations per day at hourly intervals.  For the Argos accuracy assessment, the GPS locations are considered “truth”.  Argos locations were “paired” with GPS locations by rounding the Argos location date-time to the nearest hour.  The distance between the Argos location and the corresponding GPS location is used as a measure of Argos location error (units = km in the tables below). 

Important Notes to First Understand About These Data:

1. Clearly, these free-ranging geese may have moved during the maximum 30-minute disparity between the Argos and GPS locations, so the results below are contaminated by such events.  However, given the sedentary behavior of geese while they roost during the night and afternoons, or while they attended nests and molted, the majority of Argos-GPS paired locations probably represent comparisons that have inconsequential contamination by movements during the intervening period (< 30 minutes) between the two locations.
2. The sample size for location class Z is very small; the statistics should be considered unreliable.

Illustration:

GPS tracks of two bar-headed geese (cyan line) compared to the Argos Doppler locations that were retained (red) and rejected (yellow) by the “Both” Hybrid filter using the algorithm parameters documented here.

CAPTIVE EIDERS

Important Notes to First Understand About These Data:

1. The accuracy statistics of the raw data DO NOT represent the capabilities of the Argos System nor the quality of the ptts owing to several artificial conditions that bias the results:  a) the enclosure was adjacent to a tall building that blocked a large portion of the sky, so overall, fewer transmissions were received during a satellite overpass and hence the large proportion of LC A and LC B locations; b) this truncated overpass visibility also reduces the realized pass duration, which biases the received messages toward one side of the Doppler curve and further reduces the overall accuracy of the estimated locations. 
2. The Tables below serve to quantify how the average accuracy of the auxiliary location classes (0, A, B, and Z) is improved by the MRD filter when the MAXREDUN threshold is defined to be more and more conservative (i.e. 10 km vs. 5 km vs. 2 km).
3. The MAXREDUN threshold was the only user parameter that was varied; the other parameters (which affect the MRD filter output) remained constant: keep_lc = 1; keeplast = 0; skiploc = 0; crossval = 0. KEEP_LC = 1 in all cases, hence, only the auxiliary locations were filtered and statistics for the standard locations remain constant.

llustrations (UTM projection):

Captive eider Argos locations that were accepted (green) and rejected (black) by the MRD filter using MAXREDUN = 10 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the enclosure location.

Captive eider Argos locations that were accepted (cyan) and rejected (black) by the MRD filter using MAXREDUN = 5 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the enclosure location.

Captive eider Argos locations that were accepted (red) and rejected (black) by the MRD filter using MAXREDUN = 5 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the enclosure location.

Supporting Illustrations:

Rooftop Argos locations that were accepted (green) and rejected (black) by the MRD filter using MAXREDUN = 10 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the building location.

Rooftop Argos locations that were accepted (cyan) and rejected (black) by the MRD filter using MAXREDUN = 5 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the building location.

Rooftop Argos locations that were accepted (red) and rejected (black) by the MRD filter using MAXREDUN = 2 km, and KEEP_LC = 1. Concentric circles demarcate 5, 10, and 15 km distances away from the building location.

NORTHERN RIGHT WHALE

Raw Argos track (green) and manually selected track (white).

Manually selected track (white, as above) and DAR filtered track (red).