If you're into geocaching, you probably got here because you are using, or contemplating using, the GSAK macro called LonelyFinds. If you don't know what geocaching is, then you probably got here by mistake, though you're certainly welcome to take a look and perhaps join the game.
LonelyFinds has two distinct though related functions. Both functions help with challenge caches which require you to find other caches which haven't been found in a long time, or which sometimes don't get found for a long time.
Personal loneliness: Identify caches which you found after some months of no finds.
Cache habitual loneliness: Identify caches which have at some point gone unfound for a long time.
LonelyFinds does the calculations for you, but you have to take a few steps to help it.
If you don't already have GSAK version 8.2.1.11 or later, get it and install it. Without at least this version, you won't be able to load all the necessary log entries into your GSAK database. GSAK displays its version in the upper left corner. To update, first check the download link on GSAK home page; if that gets a version later than 8.2.1.11, use it. If not, get the latest version from the forum thread 8.2.1 Updates. (The latter is a pre-release but is usually stable.)
Create the database you want to analyze. Build the database using standard GSAK techniques, probably including pocket queries. If you are doing the "personal loneliness" case, you'll probably start with the "My Finds" pocket query.
Add all log entries to the database. With the database open, do "geocaching.com access -> Get Logs". If this is your first time using direct access, you'll need to log on via GSAK. Pick "All in current filter" and set "Max logs per cache" to 99999. Click OK. Wait ... possibly a long time. If your database has more than a few dozen caches, go for coffee. If it has thousands, make sure your computer isn't configured to go to sleep overnight. Getting logs does not count against your direct access limits, but the rate is throttled and amounts to about 700 logs per minute, so if you've found thousands of caches, it will take a while, possibly days.
If you have thousands of caches in the database, then you may want to split up the logs download into multiple sessions. To do this, use GSAK filters, in particular the Mfilter, which allows you to specify any filter criteria. LonelyFinds operates on the caches in the current filter, not the entire database. This enables you to filter your database into multiple non-overlapping parts and download the logs one part at a time. Filters are a standard GSAK feature.
Run the LonelyFinds macro. It displays a dialog box asking what you want to do.
First, it tells you to read these instructions. There's a good chance you already clicked on that button.
Second, it asks which kind of analysis you want, as discussed in the Purpose section above.
Third, if you asked for the "personal loneliness" analysis, it asks how to identify your logs. The normal choice (marked "recommended") is to identify them exactly as GSAK does. The other choice is to enter a specific geocaching.com ID#; you might use this option to run the analysis for someone else.
Use View->Add/Remove Columns to display the custom data fields added by the macro. For the "cache habitual loneliness" case, these are LongestFindGap and LongestGapEnd. For the "personal loneliness" case, they are MonthsSincePreviousFind and DateOfPreviousFind. You may want to rename the column headings. You will very likely want to order by one of these fields to view the results. You can do all the things with these columns that you would normally do in GSAK.
LonelyFinds is intended to locate candidate caches for the listed purposes. It is not intended to verify compliance with challenge requirements. You need to verify the results. Most importantly, "Found it" logs sometimes have incorrect dates. Also, the lack of Publish Listing logs on caches published before August 2005 means that the gap after publication cannot be analyzed. (The Placed date is under the control of the hider, and so is treated as unreliable.)
Event caches are not considered. This makes sense since normally all event finds ("Attended") are on the same date, so event caches are not relevant to "lonely caches" challenges.
If there is no Publish Listing log (caches published before August 2005), and the longest gap is between publication and the first find, LonelyFinds will not identify that gap. As noted above, the Placed date is under the control of the hider, and so is treated as unreliable.
If you've logged more than one find on a cache (rare, but can occur in valid situations), the macro will store the stats for your first find.
If there were other finders on the same day as your qualifying find, LonelyFinds cannot determine whether your find should be considered as a qualifying find or not. GSAK and gc.com just don't have that information. In other words, if you were the first finder of the day, or in a group that found it together, you should get credit, but not if you found it later. The lonely months and previous find date for these caches will be calculated as though you were the first finder of the day, so you have to check them. See the first note above: LonelyFinds identifies candidates.
If you were FTF and there is no Publish Listing log (caches published before August 2005), the macro will not compute the gap before your find. This is because it looks for a previous "Found it" or "Publish Listing" log, and your log is the first for the cache. In this case the log data is insufficient to determine the lonely time, and the Placed date is unreliable because it's under the control of the hider. If you think this is relevant to you, there's a technique using SQLiteSpy which I've not incorporated into a macro. If you know how to use SQLiteSpy, the query is
select myc.name 'Cache name',myl.lparent 'GC code',myl.ldate 'log date'
from (caches myc join logs myl on myc.code = myl.lparent)
left join logs other on myl.lparent=other.lparent and myl.ldate>
other.ldate
where myl.ltype='Found it' and myl.ldate<'2005-08-01' and myl.lby like
'YOUR GC.COM NAME HERE'
and other.ltype is null
order by name;
If you found a cache before publication (test find), on the day of publication, or (sometimes) on the day after publication, LonelyFinds does not calculate the loneliness fields for various technical reasons. This should not matter when talking about lonely caches.