How gen-too/primat works
Project Type and Purpose
• PRIMAT is an open-source Java toolbox for privacy-preserving record linkage (PPRL).
• It provides two desktop applications (Data Owner and Linkage Unit) built with JavaFX and Maven.
• It implements a PPRL workflow: data preprocessing, Bloom-filter encoding, blocking/filtering, matching/classification, post-processing, and evaluation.
File-Structure Analysis
• Top-level directories:
• datasets/ – sample CSV files for testing.
• primat/ – Maven project root.
• Under primat/src/main/java/dbs/pprl/toolbox/:
• data_owner/ – modules for data owners: preprocessing, encoding, blocking setup, GUI (DataOwnerApp).
• lu/ – modules for linkage unit: blocking, similarity, classification, post-processing, evaluation, GUI (LinkageUnitApp).
• utils/ – shared utilities: CSV I/O, component loader, string/bitset helpers.
• Resources:
• src/main/resources/gui/view & style – FXML views and CSS for JavaFX UIs.
Key Architectural Patterns
• Modular “toolbox” structure: separate packages for each PPRL stage (preprocessing, encoding, blocking, matching, evaluation).
• Task/Pipeline pattern: tasks implement a common interface, chained via configuration.
• MVC for GUI: FXML view files + controllers under gui/controller.
• Maven as build and dependency manager.
Main Components
a. Data Owner Application
• GUI Layer: JavaFX controllers & FXML (DataOwnerApp).
• Preprocessing Module: Task → various Preprocessors.
• Encoding Module: BloomFilterEncoder, FeatureExtractor, EncoderTask.
• Blocking Setup: BlockingTask & BlockingFunction(s) for data owner.
• Input/Output: CSVReader / CSVWriter.
• Configuration Loader: XML/JSON config objects under config/ (BlockingConfig, CSVInputFileConfig, etc.).
b. Linkage Unit Application
• GUI Layer: JavaFX controllers & FXML (LinkageUnitApp).
• Blocking Module: metric-space & LSH blockers.
• Similarity Calculation Module: SimilarityCalculator(s).
• Classification Module: ThresholdClassificator, AdaptiveThresholdClassificator.
• Post-processing Module: Hungarian, StableMarriage, Hybrid postprocessors.
• Evaluation Module: QualityEvaluator, PseudoMeasureEvaluator, MetricCollector.
• Input/Output: CSVToEncodedRecordTransformer.
c. Shared / Common
• Utilities: CSVReader/Writer, StringUtils, BitSetUtils.
• Data Models: EncodedRecord, PreparedRecord, Attribute Definitions.
• Configuration Objects.
Relationships & Data Flows
1. CSV Input (datasets) → Data Owner GUI
2. DataOwnerApp Controller invokes PreprocessingTask → cleans data
3. Preprocessed data → EncodingTask → outputs encoded records (Bloom filters)
4. Encoded records → optionally apply DataOwner blocking rules → export to file
5. LinkageUnitApp loads encoded record files → Blocking Module generates candidate pairs
6. Candidate pairs → Similarity Calculation → CandidatePairWithSimilarity
7. Candidate similarities → Classification Module → match/no-match decisions
8. Matches → Post-processing Module → one-to-one refinement
9. Results → Evaluation Module → metrics & visualizations
10. Outputs → GUI tables / CSVWriter