AMR/vignettes/AMR_for_Python.Rmd

---
title: "AMR for Python"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{AMR for Python}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
  warning = FALSE,
  collapse = TRUE,
  comment = "#>",
  fig.width = 7.5,
  fig.height = 5
)
```

# Introduction

The `AMR` package for R is a powerful tool for antimicrobial resistance (AMR) analysis. It provides extensive features for handling microbial and antimicrobial data. However, for those who work primarily in Python, we now have a more intuitive option available: the `AMR` Python package, which uses `rpy2` internally. This package allows Python users to access all the functions from the R `AMR` package without the need to set up `rpy2` themselves. Since this Python package is not a true 'port' (which would require all R functions to be rewritten into Python), R and the AMR R package are still required to be installed. Yet, Python users can now easily work with AMR data directly through Python code.

In this document, we explain how this works and provide simple examples of using the `AMR` Python package.

## How It Works

The `AMR` Python package acts as a wrapper around the functions in the `AMR` R package. The package simplifies the process of calling R functions in Python, eliminating the need to manually manage the `rpy2` setup, which Python uses internally to be able to work with the R package. By just using `import AMR`, Python users can directly use the functions from the `AMR` R package as if they were native Python functions.

Internally, `rpy2` is still being used, but all complexity is hidden from the user. This approach keeps the Python code clean and Pythonic, while still leveraging the full power of the R `AMR` package.

## Example of Usage

Here’s an example that demonstrates how to clean microorganism and drug names using the `AMR` Python package:

```python
import pandas as pd
import AMR

# Sample data
data = {
    "MOs": ['E. coli', 'ESCCOL', 'esco', 'Esche coli'],
    "Drug": ['Cipro', 'CIP', 'J01MA02', 'Ciproxin']
}
df = pd.DataFrame(data)

# Use AMR functions to clean microorganism and drug names
df['MO_clean'] = AMR.mo_name(df['MOs'])
df['Drug_clean'] = AMR.ab_name(df['Drug'])

# Display the results
print(df)
```

| MOs         | Drug      | MO_clean           | Drug_clean    |
|-------------|-----------|--------------------|---------------|
| E. coli     | Cipro     | Escherichia coli   | Ciprofloxacin |
| ESCCOL      | CIP       | Escherichia coli   | Ciprofloxacin |
| esco        | J01MA02   | Escherichia coli   | Ciprofloxacin |
| Esche coli  | Ciproxin  | Escherichia coli   | Ciprofloxacin |

### Explanation

* **mo_name:** This function standardises microorganism names. Here, different variations of *Escherichia coli* (such as "E. coli", "ESCCOL", "esco", and "Esche coli") are all converted into the correct, standardised form, "Escherichia coli".

* **ab_name**: Similarly, this function standardises antimicrobial names. The different representations of ciprofloxacin (e.g., "Cipro", "CIP", "J01MA02", and "Ciproxin") are all converted to the standard name, "Ciprofloxacin".

### Taxonomic Data Sets Now in Python!

As a Python user, you might like that the most important data sets of the `AMR` R package, `microorganisms`, `antibiotics`, `clinical_breakpoints`, and `example_isolates`, are now available as regular Python data frames:

```python
AMR.microorganisms
```

| mo           | fullname                           | status   | kingdom  | gbif      | gbif_parent | gbif_renamed_to | prevalence |
|--------------|------------------------------------|----------|----------|-----------|-------------|-----------------|------------|
| B_GRAMN      | (unknown Gram-negatives)           | unknown  | Bacteria | None      | None        | None            | 2.0        |
| B_GRAMP      | (unknown Gram-positives)           | unknown  | Bacteria | None      | None        | None            | 2.0        |
| B_ANAER-NEG  | (unknown anaerobic Gram-negatives) | unknown  | Bacteria | None      | None        | None            | 2.0        |
| B_ANAER-POS  | (unknown anaerobic Gram-positives) | unknown  | Bacteria | None      | None        | None            | 2.0        |
| B_ANAER      | (unknown anaerobic bacteria)       | unknown  | Bacteria | None      | None        | None            | 2.0        |
| ...          | ...                                | ...      | ...      | ...       | ...         | ...             | ...        |
| B_ZYMMN_POMC | Zymomonas pomaceae                 | accepted | Bacteria | 10744418  | 3221412     | None            | 2.0        |
| B_ZYMPH      | Zymophilus                         | synonym  | Bacteria | None      | 9475166     | None            | 2.0        |
| B_ZYMPH_PCVR | Zymophilus paucivorans             | synonym  | Bacteria | None      | None        | None            | 2.0        |
| B_ZYMPH_RFFN | Zymophilus raffinosivorans         | synonym  | Bacteria | None      | None        | None            | 2.0        |
| F_ZYZYG      | Zyzygomyces                        | unknown  | Fungi    | None      | 7581        | None            | 2.0        |

```python
AMR.antibiotics
```

| ab  | cid         | name                 | group                      | oral_ddd | oral_units | iv_ddd | iv_units |
|-----|-------------|----------------------|----------------------------|----------|------------|--------|----------|
| AMA | 4649.0      | 4-aminosalicylic acid| Antimycobacterials         | 12.00    | g          | NaN    | None     |
| ACM | 6450012.0   | Acetylmidecamycin    | Macrolides/lincosamides    | NaN      | None       | NaN    | None     |
| ASP | 49787020.0  | Acetylspiramycin     | Macrolides/lincosamides    | NaN      | None       | NaN    | None     |
| ALS | 8954.0      | Aldesulfone sodium   | Other antibacterials       | 0.33     | g          | NaN    | None     |
| AMK | 37768.0     | Amikacin             | Aminoglycosides            | NaN      | None       | 1.0    | g        |
| ... | ...         | ...                  | ...                        | ...      | ...        | ...    | ...      |
| VIR | 11979535.0  | Virginiamycine       | Other antibacterials       | NaN      | None       | NaN    | None     |
| VOR | 71616.0     | Voriconazole         | Antifungals/antimycotics   | 0.40     | g          | 0.4    | g        |
| XBR | 72144.0     | Xibornol             | Other antibacterials       | NaN      | None       | NaN    | None     |
| ZID | 77846445.0  | Zidebactam           | Other antibacterials       | NaN      | None       | NaN    | None     |
| ZFD | NaN         | Zoliflodacin         | None                       | NaN      | None       | NaN    | None     |


# Installation

To be able to use the `AMR` Python package, it is required to install both R and the `AMR` R package.

### Preparation: Install R and `AMR` R package

For Linux and macOS, this is just:

```bash
# Ubuntu / Debian
sudo apt install r-base && Rscript -e 'install.packages("AMR")'
# Fedora:
sudo dnf install R && Rscript -e 'install.packages("AMR")'
# CentOS/RHEL
sudo yum install R && Rscript -e 'install.packages("AMR")'
# Arch Linux
sudo pacman -S r && Rscript -e 'install.packages("AMR")'
# macOS
brew install r && Rscript -e 'install.packages("AMR")'
```

For Windows, visit the [CRAN download page](https://cran.r-project.org) in install R, then afterwards install the 'AMR' package manually.

### Install `AMR` Python Package

Since the Python package is available on the official [Python Package Index](https://pypi.org/project/AMR/), you can just run:

```bash
pip install AMR
```

# Working with `AMR` in Python

Now that we have everything set up, let’s walk through some practical examples of using the `AMR` package within Python.

## Example 1: Calculating AMR

```python
import AMR
import pandas as pd

df = AMR.example_isolates
result = AMR.resistance(df["AMX"])
print(result)
```

```
[0.59555556]
```

## Example 2: Generating Antibiograms

One of the core functions of the `AMR` package is generating an antibiogram, a table that summarises the antimicrobial susceptibility of bacterial isolates. Here’s how you can generate an antibiogram from Python:

```python
result2a = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]])
print(result2a)
```

| Pathogen        | Amoxicillin     | Ciprofloxacin   | Piperacillin/tazobactam  |
|-----------------|-----------------|-----------------|--------------------------|
| CoNS            | 7% (10/142)     | 73% (183/252)   | 30% (10/33)              |
| E. coli         | 50% (196/392)   | 88% (399/456)   | 94% (393/416)            |
| K. pneumoniae   | 0% (0/58)       | 96% (53/55)     | 89% (47/53)              |
| P. aeruginosa   | 0% (0/30)       | 100% (30/30)    | None                     |
| P. mirabilis    | None            | 94% (34/36)     | None                     |
| S. aureus       | 6% (8/131)      | 90% (171/191)   | None                     |
| S. epidermidis  | 1% (1/91)       | 64% (87/136)    | None                     |
| S. hominis      | None            | 80% (56/70)     | None                     |
| S. pneumoniae   | 100% (112/112)  | None            | 100% (112/112)           |


```python
result2b = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]], mo_transform = "gramstain")
print(result2b)
```

| Pathogen       | Amoxicillin     | Ciprofloxacin    | Piperacillin/tazobactam  |
|----------------|-----------------|------------------|--------------------------|
| Gram-negative  | 36% (226/631)   | 91% (621/684)    | 88% (565/641)            |
| Gram-positive  | 43% (305/703)   | 77% (560/724)    | 86% (296/345)            |


In this example, we generate an antibiogram by selecting various antibiotics.

# Conclusion

With the `AMR` Python package, Python users can now effortlessly call R functions from the `AMR` R package. This eliminates the need for complex `rpy2` configurations and provides a clean, easy-to-use interface for antimicrobial resistance analysis. The examples provided above demonstrate how this can be applied to typical workflows, such as standardising microorganism and antimicrobial names or calculating resistance.

By using `import AMR`, you can seamlessly integrate the robust features of the R `AMR` package into your Python workflows. Whether you're cleaning data or analysing resistance patterns, the `AMR` Python package makes it easy to work with AMR data in Python.