resfinder-parser 0.1.0__tar.gz

resfinder_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 João Dourado Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

resfinder_parser-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: resfinder-parser
+Version: 0.1.0
+Summary: Parser for ResFinder output data
+License: MIT
+License-File: LICENSE
+Author: João Dourado Santos
+Author-email: joao.dourado@insa.min-saude.pt
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pandas (>=2.0,<3.0)
+Description-Content-Type: text/markdown
+
+# ResFinderParser
+
+_Harmonizing ResFinder outputs for scalable AMR analysis_
+
+**ResFinderParser** is a Python tool that parses and standardizes JSON outputs generated by ResFinder (CGE/DTU) across multiple isolates. It compiles per-sample resistance detection results into structured, analysis-ready tabular datasets.
+
+ResFinder integrates multiple resistance detection layers, including acquired resistance genes (ResFinder database), chromosomal mutations (PointFinder), disinfectant-associated determinants (DisinFinder), and predicted phenotypic resistance. Although biologically comprehensive, these outputs are generated independently for each isolate and are not directly optimized for cross-sample analyses.
+
+The parser restructures these results into harmonized matrices suitable for:
+
+- Antimicrobial resistance (AMR) surveillance
+- Comparative resistance profiling
+- Resistance frequency and trend analysis
+- Integration into automated genomic analysis pipeline
+
+By transforming nested JSON outputs into standardized TSV files, the tool enables scalable genomic resistance analyses across research and surveillance contexts.
+
+## Requirements
+
+- Python 3.8+
+- pandas 2.0+
+
+## Installation
+
+### Using Poetry (recommended)
+
+```bash
+poetry install
+```
+
+### Using pip
+
+```bash
+pip install resfinder-parser
+```
+
+## Input
+
+**ResFinderParser** expects the JSON output files generated by ResFinder. The tool should be run on a directory containing one subfolder per isolate, each including the corresponding ResFinder `*.json` file (and, if available, PointFinder and DisinFinder results).
+
+Example structure:
+
+```
+RESFINDER_DIR/
+├── ISOLATE_001/
+│   └── ResFinder_results.json
+├── ISOLATE_002/
+│   └── ResFinder_results.json
+└── ...
+```
+
+The parser extracts resistance genes, chromosomal mutations, disinfectant-associated determinants, and predicted phenotypes directly from the JSON structure.
+
+### Outputs
+
+The parser generates four standardized TSV files:
+
+1. **isolate_summaries.tsv**
+   One row per isolate containing:
+   - isolate_id
+   - analysis_date
+   - ResFinder version
+   - databases used
+   - provided species
+   - predicted phenotype summary
+     Useful for run tracking and dataset documentation.
+
+2. **resfinder_results.tsv**
+   Long-format table (isolate × antibiotic) including:
+   - antibiotic
+   - resistance class
+   - amr_resistant (True/False)
+   - identity
+   - coverage
+   - grade
+     Suitable for resistance frequency analysis and comparative profiling.
+
+3. **pointfinder_results.tsv**
+   Long-format mutation table including:
+   - gene
+   - mutation
+   - nucleotide change
+   - associated phenotype
+   - PMID
+     Enables mutation-level resistance analysis.
+
+---
+
+4. **combined_presence_absence.tsv**
+   Wide-format matrix:
+   - One row per isolate
+   - One column per detected gene (ResFinder + DisinFinder)
+   - One column per relevant mutation (PointFinder)
+     Designed for comparative analyses, clustering, and integration with epidemiological metadata.
+     All outputs are directly compatible with R, Python (pandas), and automated genomic analysis pipelines.
+
+## Usage
+
+### Command Line
+
+```bash
+resfinder-parser -r /path/to/RESFINDER_DIR -o /path/to/output_dir
+```
+
+### As a Python Module
+
+```python
+from resfinder_parser import ResfinderCollector
+
+collector = ResfinderCollector("/path/to/RESFINDER_DIR", "/path/to/output_dir")
+collector.collect()
+```
+
+Arguments:
+
+- `-r`, `--resfinder_dir` (required): directory containing isolate subfolders
+- `-o`, `--output_dir` (optional): directory where output files will be written
+
+### Development
+
+Run tests:
+
+```bash
+poetry run pytest
+```
+
+## Citation
+
+If you use resfinder_parser in your work, please cite:
+Santos JG et al. resfinder_parser. GitHub repository.
+
+We also recommend citing ResFinder and its associated databases:
+
+- Zankari et al., 2012. Journal of Antimicrobial Chemotherapy.
+- Florensa et al., 2022. Microbial Genomics.
+- CGE/DTU ResFinder platform.
+

resfinder_parser-0.1.0/README.md

@@ -0,0 +1,136 @@
+# ResFinderParser
+
+_Harmonizing ResFinder outputs for scalable AMR analysis_
+
+**ResFinderParser** is a Python tool that parses and standardizes JSON outputs generated by ResFinder (CGE/DTU) across multiple isolates. It compiles per-sample resistance detection results into structured, analysis-ready tabular datasets.
+
+ResFinder integrates multiple resistance detection layers, including acquired resistance genes (ResFinder database), chromosomal mutations (PointFinder), disinfectant-associated determinants (DisinFinder), and predicted phenotypic resistance. Although biologically comprehensive, these outputs are generated independently for each isolate and are not directly optimized for cross-sample analyses.
+
+The parser restructures these results into harmonized matrices suitable for:
+
+- Antimicrobial resistance (AMR) surveillance
+- Comparative resistance profiling
+- Resistance frequency and trend analysis
+- Integration into automated genomic analysis pipeline
+
+By transforming nested JSON outputs into standardized TSV files, the tool enables scalable genomic resistance analyses across research and surveillance contexts.
+
+## Requirements
+
+- Python 3.8+
+- pandas 2.0+
+
+## Installation
+
+### Using Poetry (recommended)
+
+```bash
+poetry install
+```
+
+### Using pip
+
+```bash
+pip install resfinder-parser
+```
+
+## Input
+
+**ResFinderParser** expects the JSON output files generated by ResFinder. The tool should be run on a directory containing one subfolder per isolate, each including the corresponding ResFinder `*.json` file (and, if available, PointFinder and DisinFinder results).
+
+Example structure:
+
+```
+RESFINDER_DIR/
+├── ISOLATE_001/
+│   └── ResFinder_results.json
+├── ISOLATE_002/
+│   └── ResFinder_results.json
+└── ...
+```
+
+The parser extracts resistance genes, chromosomal mutations, disinfectant-associated determinants, and predicted phenotypes directly from the JSON structure.
+
+### Outputs
+
+The parser generates four standardized TSV files:
+
+1. **isolate_summaries.tsv**
+   One row per isolate containing:
+   - isolate_id
+   - analysis_date
+   - ResFinder version
+   - databases used
+   - provided species
+   - predicted phenotype summary
+     Useful for run tracking and dataset documentation.
+
+2. **resfinder_results.tsv**
+   Long-format table (isolate × antibiotic) including:
+   - antibiotic
+   - resistance class
+   - amr_resistant (True/False)
+   - identity
+   - coverage
+   - grade
+     Suitable for resistance frequency analysis and comparative profiling.
+
+3. **pointfinder_results.tsv**
+   Long-format mutation table including:
+   - gene
+   - mutation
+   - nucleotide change
+   - associated phenotype
+   - PMID
+     Enables mutation-level resistance analysis.
+
+---
+
+4. **combined_presence_absence.tsv**
+   Wide-format matrix:
+   - One row per isolate
+   - One column per detected gene (ResFinder + DisinFinder)
+   - One column per relevant mutation (PointFinder)
+     Designed for comparative analyses, clustering, and integration with epidemiological metadata.
+     All outputs are directly compatible with R, Python (pandas), and automated genomic analysis pipelines.
+
+## Usage
+
+### Command Line
+
+```bash
+resfinder-parser -r /path/to/RESFINDER_DIR -o /path/to/output_dir
+```
+
+### As a Python Module
+
+```python
+from resfinder_parser import ResfinderCollector
+
+collector = ResfinderCollector("/path/to/RESFINDER_DIR", "/path/to/output_dir")
+collector.collect()
+```
+
+Arguments:
+
+- `-r`, `--resfinder_dir` (required): directory containing isolate subfolders
+- `-o`, `--output_dir` (optional): directory where output files will be written
+
+### Development
+
+Run tests:
+
+```bash
+poetry run pytest
+```
+
+## Citation
+
+If you use resfinder_parser in your work, please cite:
+Santos JG et al. resfinder_parser. GitHub repository.
+
+We also recommend citing ResFinder and its associated databases:
+
+- Zankari et al., 2012. Journal of Antimicrobial Chemotherapy.
+- Florensa et al., 2022. Microbial Genomics.
+- CGE/DTU ResFinder platform.

resfinder_parser-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "resfinder-parser"
+version = "0.1.0"
+description = "Parser for ResFinder output data"
+authors = ["João Dourado Santos <joao.dourado@insa.min-saude.pt>"]
+license = "MIT"
+readme = "README.md"
+packages = [{include = "resfinder_parser", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+pandas = "^2.0"
+
+[tool.poetry.scripts]
+resfinder-parser = "resfinder_parser.__main__:main"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^7.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

resfinder_parser-0.1.0/src/resfinder_parser/__init__.py

@@ -0,0 +1,14 @@
+__version__ = "0.1.0"
+
+from .data_classes import Phenotype, IsolatePhenotypes, SeqRegion, IsolateSummary
+from .resfinder_result_parser import ResfinderParser, ResfinderCollector
+
+__all__ = [
+    "__version__",
+    "Phenotype",
+    "IsolatePhenotypes", 
+    "SeqRegion",
+    "IsolateSummary",
+    "ResfinderParser",
+    "ResfinderCollector",
+]

resfinder_parser-0.1.0/src/resfinder_parser/__main__.py

@@ -0,0 +1,26 @@
+import argparse
+from resfinder_parser import ResfinderCollector
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-r",
+        "--resfinder_dir",
+        help="Path to the directory containing the resfinder results.",
+        required=True,
+    )
+    parser.add_argument(
+        "-o",
+        "--output_dir",
+        help="Path to the directory to write the results to.",
+        required=False,
+    )
+    args = parser.parse_args()
+
+    collector = ResfinderCollector(args.resfinder_dir, args.output_dir)
+    collector.collect()
+
+
+if __name__ == "__main__":
+    main()

resfinder_parser-0.1.0/src/resfinder_parser/data_classes.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass
+from typing import List, Dict
+import pandas as pd
+
+
+@dataclass
+class IsolateSummary:
+    key: str
+    provided_species: str
+    result_summary: str
+    databases: str
+
+
+class SeqRegion:
+    def __init__(self, seq_region_output: str):
+        seq_region_output = seq_region_output.split(";;")
+
+        self.gene = seq_region_output[0].strip()
+        self.version = seq_region_output[1].strip()
+        self.homolog = seq_region_output[2].strip()
+
+    def __str__(self):
+        return f"{self.gene};;{self.version};;{self.homolog}"
+
+    def __repr__(self):
+        return str(self)
+
+
+class Phenotype:
+    phenotype_fields = [
+        "amr_classes",
+        "amr_resistant",
+        "amr_species_relevant",
+        "grade",
+        "seq_regions",
+    ]
+
+    def __init__(self, name):
+        self.name = name
+        self.seq_regions: List[SeqRegion] = []
+
+    def add_seq_region(self, seq_region: str):
+        self.seq_regions.append(SeqRegion(seq_region))
+
+    def add_regions(self, regions: List[str]):
+        for region in regions:
+            self.add_seq_region(region)
+
+    def feed_data(self, data: dict):
+        for field in self.phenotype_fields:
+            found = data.get(field, None)
+            if found is not None:
+                if isinstance(found, list):
+                    if field == "seq_regions":
+                        self.add_regions(found)
+                        continue
+                    found = ";".join(found)
+
+            setattr(self, field, str(found))
+
+
+class IsolatePhenotypes:
+    def __init__(self, isolate_id: str, result_summary: str):
+        self.isolate_id = isolate_id
+        self.result_summary = result_summary
+        self.phenotypes: Dict[str, Phenotype] = {}
+        self.all_genes_affected: Dict[str, list] = {}
+
+    def add_phenotype(self, phenotype: Phenotype):
+        self.phenotypes[phenotype.name] = phenotype
+
+    def phenotype_dataframe(self):
+        data_keep = []
+        default_columns = ["antibiotic"] + Phenotype.phenotype_fields
+        
+        for phenotype_name, phenotype in self.phenotypes.items():
+            phenotype_data = [phenotype_name]
+            for field in phenotype.phenotype_fields:
+                found = getattr(phenotype, field, None)
+                if found is not None:
+                    if isinstance(found, list):
+                        if len(found) == 0:
+                            found = "0"
+                        else:
+                            found = ";".join([str(x) for x in found])
+
+                phenotype_data.append(str(found))
+
+            data_keep.append(phenotype_data)
+
+        if data_keep:
+            columns = ["antibiotic"] + phenotype.phenotype_fields
+        else:
+            columns = default_columns
+            
+        df = pd.DataFrame(data_keep, columns=columns)
+
+        return df
+
+    def collect_all_genes_affected(self):
+        for phenotype_name, phenotype in self.phenotypes.items():
+            for seq_region in phenotype.seq_regions:
+                if seq_region.gene not in self.all_genes_affected.keys():
+                    self.all_genes_affected[seq_region.gene] = [phenotype_name]
+                else:
+                    if phenotype_name not in self.all_genes_affected[seq_region.gene]:
+                        self.all_genes_affected[seq_region.gene].append(phenotype_name)
+
+    def all_genes(self):
+        genes = []
+        for _, phenotype in self.phenotypes.items():
+            for seq_region in phenotype.seq_regions:
+                genes.append(seq_region.gene)
+
+        return genes
+
+    def gene_affected(self, gene: str):
+        gene_present = self.all_genes_affected.get(gene, None)
+
+        if gene_present is None:
+            return ""
+        else:
+            return "; ".join(gene_present)

resfinder_parser-0.1.0/src/resfinder_parser/resfinder_result_parser.py

@@ -0,0 +1,422 @@
+from typing import Optional
+import pandas as pd
+import json
+import os
+import datetime
+import logging
+from typing import List
+from .data_classes import IsolatePhenotypes, Phenotype, IsolateSummary
+
+
+class ResfinderParser:
+    pointfinder_results_filename: str = "PointFinder_results.txt"
+    resfinder_results_filename = "ResFinder_results_tab.txt"
+    resfinder_results_suffix = ".json"
+    databases_to_exclude = []
+
+    def __init__(self, RESFINDER_dir, isolate_dir):
+        self.isolate_id = isolate_dir
+        
+        if os.path.isdir(os.path.join(RESFINDER_dir, isolate_dir, "resfinder_results")):
+            isolate_dir = os.path.join(isolate_dir, "resfinder_results")
+
+        self.pointfinder_results_filepath = os.path.join(
+            RESFINDER_dir, isolate_dir, self.pointfinder_results_filename
+        )
+
+        json_files = [
+            f
+            for f in os.listdir(os.path.join(RESFINDER_dir, isolate_dir))
+            if f.endswith(self.resfinder_results_suffix)
+        ]
+
+        if len(json_files) == 0:
+            logging.error(
+                f"No resfinder json files found for isolate {self.isolate_id}."
+            )
+            
+
+        if len(json_files) > 1:
+            logging.warning(
+                f"Multiple resfinder json files found for isolate {self.isolate_id}. Using {json_files[0]}"
+            )
+        
+
+
+        self.time_now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        self.has_data = len(json_files) > 0
+
+        if self.has_data:
+            self.resfinder_results_filepath = os.path.join(
+                RESFINDER_dir, isolate_dir, json_files[0]
+            )
+            self.passport = self.collect_summary()
+
+        else:
+            self.passport = self.empty_passport
+            self.resfinder_results_filepath = ""
+
+
+        self.has_pointfinder_data = (
+            os.path.isfile(self.pointfinder_results_filepath)
+            and os.path.getsize(self.pointfinder_results_filepath) > 0
+        )
+
+        self.phenotypes = IsolatePhenotypes(
+            self.isolate_id, self.passport.result_summary
+        )
+
+    def json_parse_antibiotics(self):
+        """Parse the resfinder json output into a pandas dataframe."""
+        content = self.read_json()
+        ## info to get:
+
+        for phenotype_str, data in content["phenotypes"].items():
+            antibiotic = Phenotype(phenotype_str)
+            antibiotic.feed_data(data)
+            self.phenotypes.add_phenotype(antibiotic)
+
+    def resfinder_json_summary(self, content) -> IsolateSummary:
+        """
+        Parse the resfinder json output into a IsolateSummary object."""
+        analysis_key = content["key"]
+        provided_species = content["provided_species"]
+        result_summary = content["result_summary"]
+        databases: dict = content["databases"]
+        databases = "; ".join(
+            [
+                f"{v['database_name']}-{v['database_version']}"
+                for k, v in databases.items()
+                if v["database_name"].lower() not in self.databases_to_exclude
+            ]
+        )
+        return IsolateSummary(analysis_key, provided_species, result_summary, databases)
+
+    @property
+    def empty_passport(self):
+        return IsolateSummary("", "", "No results found.", "")
+
+    def read_json(self):
+        with open(self.resfinder_results_filepath, "r") as f:
+            results = json.load(f)
+
+        return results
+
+    def collect_summary(self) -> IsolateSummary:
+        results = self.read_json()
+        return self.resfinder_json_summary(results)
+
+    def add_analyis_columns(self, df: pd.DataFrame):
+        df["isolate_id"] = self.isolate_id
+        df["analysis_date"] = self.time_now
+        df["version"] = self.passport.key
+
+        # place the isolate_id, analysis_date and resfinder version columns at the front
+        cols = df.columns.tolist()
+        cols = cols[-3:] + cols[:-3]
+        df = df[cols]
+
+        return df
+
+    def collect_pointfinder_results(self):
+        results = pd.read_csv(self.pointfinder_results_filepath, sep="\t")
+
+        results = self.add_analyis_columns(results)
+
+        return results
+
+    def collect_phenotype_results(self):
+        self.json_parse_antibiotics()
+        isolate_results = self.phenotypes.phenotype_dataframe()
+        isolate_results = self.add_analyis_columns(isolate_results)
+
+        return isolate_results
+
+    def seq_regions_parse(self):
+        results = self.read_json()
+
+        seq_reg = []
+        for reg, map in results["seq_regions"].items():
+
+            ## filter out if all databases are in the exclude list
+            databases = map["ref_database"]
+            databases_simple = [x.split("-")[0].lower() for x in databases]
+            if all(db in self.databases_to_exclude for db in databases_simple):
+                continue
+
+            for phenotype in map["phenotypes"]:
+                seq_reg.append([reg, phenotype, map["query_id"], map["identity"]])
+
+        seq_reg_df = pd.DataFrame(
+            seq_reg, columns=["seq_region", "antibiotic", "query_id", "identity"]
+        )
+
+        return seq_reg_df
+
+    def extend_resfinder_results(self, resfinder_df):
+
+        seq_reg_df = self.seq_regions_parse()
+
+        def contig_id_info(phenotype: pd.DataFrame):
+            pheno_df = seq_reg_df[seq_reg_df.antibiotic == phenotype]
+
+            if pheno_df.shape[0] == 0:
+                return pd.Series(["", 0])
+
+            output = pd.Series(
+                ["; ".join(pheno_df.query_id.values), pheno_df.identity.values[0]]
+            )
+
+            return output
+
+        resfinder_df[["contigs", "identity"]] = resfinder_df.antibiotic.apply(
+            contig_id_info
+        )
+
+        return resfinder_df
+
+    def isolate_summary(self):
+        """
+        Provide an overview of the isolate's results.
+        """
+        summary_df = pd.DataFrame(
+            [
+                [
+                    self.passport.databases,
+                    self.passport.provided_species,
+                    self.passport.result_summary,
+                ]
+            ],
+            columns=["databases", "provided_species", "result_summary"],
+        )
+
+        summary_df = self.add_analyis_columns(summary_df)
+
+        return summary_df
+
+    @property
+    def empty_isolate_summary(self):
+        return pd.DataFrame(
+            [
+                [
+                    self.isolate_id,
+                    self.time_now,
+                    self.passport.key,
+                    self.passport.databases,
+                    "",
+                    "No results found.",
+                ]
+            ],
+            columns=[
+                "isolate_id",
+                "analysis_date",
+                "version",
+                "databases",
+                "provided_species",
+                "result_summary",
+            ],
+        )
+
+
+class ResfinderCollector:
+    def __init__(self, RESFINDER_dir: str, output_dir: Optional[str] = None):
+        self.RESFINDER_dir = RESFINDER_dir
+        self.output_dir = output_dir
+        self.isolate_dirs = self.resfinder_dirs()
+        self.logger = logging.getLogger(__name__)
+        # set level to info to get the info messages
+        self.logger.setLevel(logging.INFO)
+        # log to console
+        self.logger.addHandler(logging.StreamHandler())
+        self.logger.info(
+            f"Found {len(self.isolate_dirs)} isolate directories in {self.RESFINDER_dir}"
+        )
+
+    def _is_isolate_dir(self, dirpath: str):
+        if dirpath.startswith("."):
+            return False
+
+        if os.path.isdir(os.path.join(self.RESFINDER_dir, dirpath)) is False:
+            return False
+
+        return True
+
+    def resfinder_dirs(self):
+        isolate_dirs = os.listdir(self.RESFINDER_dir)
+        isolate_dirs = [x for x in isolate_dirs if self._is_isolate_dir(x)]
+        return isolate_dirs
+
+    def genes_affected(self, isolate_phenotypes: List[IsolatePhenotypes]):
+        all_genes = [
+            gene for isolate in isolate_phenotypes for gene in isolate.all_genes()
+        ]
+        all_genes = list(set(all_genes))
+
+        data_to_keep = []
+
+        for isolate in isolate_phenotypes:
+            isolate_line = [isolate.isolate_id, isolate.result_summary]
+            isolate.collect_all_genes_affected()
+            for gene in all_genes:
+                isolate_line.append(isolate.gene_affected(gene))
+
+            data_to_keep.append(isolate_line)
+
+        df = pd.DataFrame(
+            data_to_keep, columns=["isolate_id", "result_summary"] + all_genes
+        )
+
+        return df
+
+    def pointfinder_summary(
+        self, pointfinder_results: pd.DataFrame
+    ) -> Optional[pd.DataFrame]:
+
+        if pointfinder_results.empty:
+            return None
+
+        isolate_ids = pointfinder_results["isolate_id"].unique()
+
+        pointfinder_known = pointfinder_results[
+            pointfinder_results["Resistance"] != "Unknown"
+        ]
+
+        groups = []
+        # for _, group in pointfinder_results.groupby("isolate_id"):
+        for isolate_id in isolate_ids:
+            group = pointfinder_known[pointfinder_known["isolate_id"] == isolate_id]
+
+            ## merge rows with the same mutation, but different resistance. concatenate the resistance
+            group = group.groupby(["isolate_id", "Mutation"]).agg(
+                {"Resistance": lambda x: "; ".join(x)}
+            )
+            group = group.reset_index()
+
+            matrix_df = group.pivot(
+                index="isolate_id", columns="Mutation", values="Resistance"
+            )
+
+            matrix_df = matrix_df.fillna("")
+            matrix_df = matrix_df.reset_index()
+
+            groups.append(matrix_df)
+
+        matrix_df = pd.concat(groups, axis=0)
+
+        return matrix_df
+
+    def collect_all_results(self):
+        pointfinder_results = []
+        resfinder_results = []
+        isolate_summaries = []
+        isolate_phenotypes = []
+
+        for isolate_dir in self.isolate_dirs:
+            if isolate_dir.startswith("."):
+                continue
+
+            if os.path.isdir(os.path.join(self.RESFINDER_dir, isolate_dir)) is False:
+                continue
+
+            isolate_parser = ResfinderParser(self.RESFINDER_dir, isolate_dir)
+
+            if isolate_parser.has_data is False:
+                self.logger.info(
+                    f"No results found for isolate {isolate_parser.isolate_id}"
+                )
+                isolate_summary = isolate_parser.empty_isolate_summary
+                isolate_summaries.append(isolate_summary)
+
+                continue
+
+            isolate_phenotype_results = isolate_parser.collect_phenotype_results()
+            isolate_phenotype_results = isolate_parser.extend_resfinder_results(
+                isolate_phenotype_results
+            )
+            isolate_summary = isolate_parser.isolate_summary()
+
+            if isolate_parser.has_pointfinder_data:
+
+                isolate_pointfinder_results = (
+                    isolate_parser.collect_pointfinder_results()
+                )
+                pointfinder_results.append(isolate_pointfinder_results)
+
+            resfinder_results.append(isolate_phenotype_results)
+            isolate_summaries.append(isolate_summary)
+            isolate_phenotypes.append(isolate_parser.phenotypes)
+
+        if len(isolate_phenotypes) == 0:
+            return None, None, None, None
+
+        resfinder_results = pd.concat(resfinder_results, axis=0)
+        isolate_summaries = pd.concat(isolate_summaries, axis=0)
+
+        genes_affected = self.genes_affected(isolate_phenotypes)
+        combined_presence_absence = genes_affected.copy()
+
+        if len(pointfinder_results) > 0:
+            pointfinder_results = pd.concat(pointfinder_results, axis=0)
+
+            pointfinder_results_summary = self.pointfinder_summary(pointfinder_results)
+
+            combined_presence_absence = pd.merge(
+                genes_affected,
+                pointfinder_results_summary,
+                on="isolate_id",
+                how="outer",
+            )
+        else:
+            pointfinder_results = pd.DataFrame()
+
+        return (
+            pointfinder_results,
+            resfinder_results,
+            isolate_summaries,
+            combined_presence_absence,
+        )
+
+    def collect(self):
+        self.logger.info(f"Collecting results from {len(self.isolate_dirs)} isolates..")
+
+        if self.output_dir is None:
+            self.output_dir = self.RESFINDER_dir
+        else:
+            if os.path.isdir(self.output_dir) is False:
+                os.mkdir(self.output_dir)
+
+        (
+            pointfinder_results,
+            resfinder_results,
+            isolate_summaries,
+            combinbined_presence_absence,
+        ) = self.collect_all_results()
+
+        if pointfinder_results is None:
+            self.logger.info("No results found.")
+            return
+
+        pointfinder_results.to_csv(
+            os.path.join(self.output_dir, "pointfinder_results.tsv"),
+            sep="\t",
+            index=False,
+        )
+        resfinder_results.to_csv(
+            os.path.join(self.output_dir, "resfinder_results.tsv"),
+            sep="\t",
+            index=False,
+        )
+        isolate_summaries.to_csv(
+            os.path.join(self.output_dir, "isolate_summaries.tsv"),
+            sep="\t",
+            index=False,
+        )
+
+        combinbined_presence_absence.to_csv(
+            os.path.join(self.output_dir, "combined_presence_absence.tsv"),
+            sep="\t",
+            index=False,
+        )
+
+        self.logger.info(f"Results written to {self.output_dir}")