<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>File: README.rdoc</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="fileHeader">
<h1>README.rdoc</h1>
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Path:</strong></td>
<td>README.rdoc
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Last Update:</strong></td>
<td>Tue May 12 11:20:38 -0400 2009</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<h1>ofac</h1>
<ul>
<li><a href="http://kevintyll.github.com/ofac">kevintyll.github.com/ofac</a>
</li>
<li><a href="http://www.drexel-labs.com">www.drexel-labs.com</a>
</li>
<li><a
href="http://www.treas.gov/offices/enforcement/ofac/sdn/index.shtml">www.treas.gov/offices/enforcement/ofac/sdn/index.shtml</a>
</li>
</ul>
<h2>DESCRIPTION:</h2>
<p>
ofac is a ruby gem that tries to find a match of a person‘s name and
address against the Office of Foreign Assets Control‘s Specially
Designated Nationals list...the so called terrorist watch list.
</p>
<p>
This gem, like the ssn_validator gem, started as a need for the company I
work for, Clarity Services Inc. We decided once again to create a gem out
of it and share it with the community. Much thanks goes to the management
at Clarity Services Inc. for allowing this code to be open sourced. Thanks
also to Larry Berland at Clarity Services Inc. The matching logic in the
ofac_match.rb file was derived from his work.
</p>
<h2>FEATURES:</h2>
<p>
Creates a score, 1 - 100, based on how well the name, address and city
match the data on the SDN list. Since we have to match on strings, the
likely hood of an exact match are virtually nil. So we‘ve created an
algorithm that creates a score. The better the match, the higher the score.
A score of 100 would be a perfect match.
</p>
<p>
The score is calculated by adding up the weightings of each part that is
matched. So if only name is matched, then the max score is the weight for
<tt>:name</tt> which is 60
</p>
<p>
It‘s possible to get partial matches, which will add partial weight
to the score. If there is not a match on the element as it is passed in,
then each word element gets broken down and matches are tried on each
partial element. The weighting is distrubuted equally for each partial that
is matched.
</p>
<p>
If exact matches are not made, then a sounds like match is attempted. Any
match made by sounds like is given 75% of it‘s weight to the score.
Example:
</p>
<p>
If you are trying to match the name Kevin Tyll and there is a record for
Smith, Kevin in the database, then we will try to match both Kevin and Tyll
separately, with each element Smith and Kevin. Since only Kevin will find a
match, and there were 2 elements in the searched name, the score will be
added by half the weighting for <tt>:name</tt>. So since the weight for
<tt>:name</tt> is 60, then we will add 30 to the score.
</p>
<p>
If you are trying to match the name Kevin Gregory Tyll and there is a
record for Tyll, Kevin in the database, then we will try to match Kevin and
Gregory and Tyll separately, with each element Tyll and Kevin. Since both
Kevin and Tyll will find a match, and there were 3 elements in the searched
name, the score will be added by 2/3 the weighting for <tt>:name</tt>. So
since the weight for <tt>:name</tt> is 60, then we will add 40 to the
score.
</p>
<p>
If you are trying to match the name Kevin Tyll and there is a record for
Kevin Gregory Tyll in the database, then we will try to match Kevin and
Tyll separately, with each element Tyll and Kevin and Gregory. Since both
Kevin and Tyll will find a match, and there were 2 elements in the searched
name, the score will be added by 2/2 the weighting for <tt>:name</tt>. So
since the weight for <tt>:name</tt> is 60, then we will add 60 to the
score.
</p>
<p>
If you are trying to match the name Kevin Tyll, and there is a record for
Teel, Kevin in the database, then an exact match will be found for Kevin,
and a sounds like match will be made for Tyll. Since there were 2 elements
in the searched name, and the weight for <tt>:name</tt> is 60, then each
element is worth 30. Since Kevin was an exact match, it will add 30, and
since Tyll was a sounds like match, it will add 30 * .75. So the
<tt>:name</tt> portion of the search will be worth 53.
</p>
<p>
If data is in the database for city and or address, and you pass data in
for these elements, the score will be reduced by 10% of the weight if there
is no match or sounds like match. So if you get a match on name,
you‘ve already got a score of 60. So if you don‘t pass in an
address or city, or if you do, but there is no city or address info in the
database, then your final score will be 60. But if you do pass in a city,
say Tampa, and the city in the Database is New York, then we will deduct
10% of the weight (30 * .1) = 3 from the score since 30 is the weight for
<tt>:city</tt>. So the final score will be 57.
</p>
<p>
If were searching for New York, and the database had New Deli, then there
would be a match on New, but not on Deli. Since there were 2 elements in
the searched city, each hit is worth 15. So the match on New would add 15,
but the non-match on York would subtract (15 * .1) = 1.5 from the score. So
the score would be (60 + 15 - 1.5) = 74, due to rounding.
</p>
<p>
Only <tt>:city</tt> and <tt>:address</tt> subtract from the score, No match
on name simply returns 0.
</p>
<p>
Matches for name are made for both the name and any aliases in the OFAC
database.
</p>
<p>
Matches for <tt>:city</tt> and <tt>:address</tt> will only be added to the
score if there is first a match on <tt>:name</tt>.
</p>
<p>
We consider a score of 60 to be reasonable as a hit.
</p>
<h2>SYNOPSIS:</h2>
<p>
Accepts a hash with the identity‘s demographic information
</p>
<pre>
Ofac.new({:name => 'Oscar Hernandez', :city => 'Clearwater', :address => '123 somewhere ln'})
</pre>
<p>
<tt>:name</tt> is required to get a score. If <tt>:name</tt> is missing, an
error will not be thrown, but a score of 0 will be returned.
</p>
<p>
The more information provided, the higher the score could be. A score of
100 would mean all fields were passed in, and all fields were 100% matches.
If only the name is passed in without an address, it will be impossible to
get a score of 100, even if the name matches perfectly.
</p>
<p>
Acceptable hash keys and their weighting in score calculation:
</p>
<ul>
<li><tt>:name</tt> (weighting = 60%) (required) This can be a person, business,
or marine vessel
</li>
<li><tt>:address</tt> (weighting = 10%)
</li>
<li><tt>:city</tt> (weighting = 30%)
</li>
<li>Instantiate the object with the identity‘s name, street address, and
city.
<pre>
ofac = Ofac.new(:name => 'Kevin Tyll', :city => 'Clearwater', :address => '123 Somewhere Ln.')
</pre>
</li>
<li>Then get the score
<pre>
ofac.score => return the score 1 - 100
</pre>
</li>
<li>You can also get the list of all the partial matches with the score of each
record.
<pre>
ofac.possible_hits => returns an array of hashes.
</pre>
</li>
</ul>
<h2>REQUIREMENTS:</h2>
<ul>
<li>Rails 2.0.0 or greater
</li>
</ul>
<h2>INSTALL:</h2>
<ul>
<li>To install the gem:
<pre>
sudo gem install kevintyll-ofac
</pre>
</li>
<li>To create the necessary db migration, from the command line, run:
<pre>
script/generate ofac_migration
</pre>
</li>
<li>Require the gem in your environment.rb file in the Rails::Initializer
block:
<pre>
config.gem 'kevintyll-ofac', :lib => 'ofac'
</pre>
</li>
<li>To load your table with the current OFAC data, from the command line, run:
<pre>
rake ofac:update_data
* The OFAC data is not updated with any regularity, but you can sign up for email notifications when the data changes at
http://www.treas.gov/offices/enforcement/ofac/sdn/index.shtml.
</pre>
</li>
</ul>
<h2>Copyright</h2>
<p>
Copyright (c) 2009 Kevin Tyll. See LICENSE for details.
</p>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>