docs/graph-production-workflow/enrichment-by-mining/affiliation_matching.md

@@ -4,9 +4,14 @@ sidebar_position: 1
 
 # Affiliation matching
 
-***Short description:*** The goal of the affiliation matching module is to match affiliations extracted from the pdf and xml documents with organizations from the OpenAIRE organization database.
+***Short description:***  The goal of the affiliation matching module is to pair affiliations with organizations listed in either OpenAIRE or ROR organization database. 
+Depending on the data source, we currently employ two distinct methodologies:
 
-***Algorithmic details:***
+	* The first method revolves around affiliations extracted from PDF and XML documents, which are subsequently matched with organizations within the OpenAIRE database.
+	* The second concerns affiliations retrieved from platforms such as Crossref, PubMed, and Datacite, and are matched to organizations of the ROR database. 
+
+
+***Algorithmic details of the first method:***
 
 *The buckets concept*
 
@@ -55,3 +60,48 @@ Java, Spark
 ***References:*** -
 
 ***Authority:*** ICM • ***License:*** AGPL-3.0 • ***Code:*** [CoAnSys/affiliation-organization-matching](https://github.com/CeON/CoAnSys/tree/master/affiliation-organization-matching)
+
+
+***Algorithmic details of the second method:***
+
+*Categorization*
+
+The affiliations' strings are imported and undergo cleaning, tokenization, and removal of stopwords. Similar to the “buckets concept”  of the first method, the goal is to split the affiliation strings, as well as the ROR organizations, into coherent groups. To achieve this, data preprocessing has already been conducted on ROR's data, involving the analysis of word frequency ('keywords') within the legal names of ROR's organizations to define specific categories. These categories include universities and institutes, laboratories, hospitals, companies, museums, governments, foundation, and rest organizations. ROR's organizations have subsequently been assigned to these categories based on their legal names. The algorithm employs a similar approach to categorize affiliations into these same groups.
+
+*String Shortening*
+
+The objective is to extract pertinent details from each affiliation string. The algorithm divides the string whenever a comma (,) or semicolon (;) is detected. It then applies specific 'rules' to these segments and retains only those containing relevant keywords. Additionally, it trims down the segments by preserving words in proximity to particular keywords like "university," "institute," "laboratory," or "hospital." As a result, the average string length is reduced from 90 to 35 characters.
+
+*Matching with ROR's Database*
+
+The algorithm checks whether a substring containing a keyword is linked to a legal name or to an alternative name in the organizations listed in the ROR's database. In order to identify the most accurate match, the algorithm employs cosine similarity.. Although alternative methods like Levenshtein Distance or Jaro-Winkler Distance were considered for measuring string similarity, it was concluded that cosine similarity was the most appropriate choice for this specific application.
+
+*Refinement*
+
+If multiple matches are found above the desired similarity thresholds, the algorithm performs another check. It applies cosine similarity between the organizations found in the ROR's database and the original affiliation string. This comparison takes into account additional information present in the original affiliation, such as addresses or city names. The algorithm aims to identify the best fit among the potential matches. Note that the case where two or more different organizations share the same name is also considered.
+
+***Parameters:***
+
+* input
+	* source of affiliations: JSON Crossref or XML Pubmed or Parquet DataCite files.
+
+	* organizations: [dix_acad.pkl](https://github.com/mkallipo/affiliation-matching/blob/main/dictionaries/dix_acad.pkl), [dix_mult](https://github.com/mkallipo/affiliation-matching/blob/main/dictionaries/dix_mult.pkl, [dix_city](https://github.com/mkallipo/affiliation-matching/blob/main/dictionaries/dix_city.pkl), [dix_country](https://github.com/mkallipo/affiliation-matching/blob/main/dictionaries/dix_country.pkl)  (four pickled dictionaries with keys legalnames and alternativenames of organizations in the ROR database.)
+
+	* similarity thresholds: simU for universities, simG for other organizations (default values are simU = 0.64, simG = 0.87).
+    cument-organization pairs which are used as a hint for matching affiliations
+    
+* output
+	* [MatchedOrganization](https://github.com/openaire/iis/blob/master/iis-wf/iis-wf-affmatching/src/main/resources/eu/dnetlib/iis/wf/affmatching/model/MatchedOrganization.avdl) avro datastore location with matched publications with organizations.
+    
+    
+***Limitations:*** -
+
+***Environment:*** 
+Python
+
+***References:*** -
+
+***Authority:*** OpenAIRE • ***License:***AGPL-3.0   • ***Code:*** [AffRo](https://github.com/mkallipo/affiliation-matching)
+
+
+