AMR/articles/AMR_for_Python.md

AMR for Python

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.

This Python package is a wrapper around the AMR R package. It uses the rpy2 package internally. Despite the need to have R installed, Python users can now easily work with AMR data directly through Python code.

Prerequisites

This package was only tested with a virtual environment (venv). You can set up such an environment by running:

# linux and macOS:
python -m venv /path/to/new/virtual/environment

# Windows:
python -m venv C:\path\to\new\virtual\environment

Then you can activate the environment, after which the venv is ready to work with.

Install AMR

1. Since the Python package is available on the official Python Package Index, you can just run:

   pip install AMR
   

2. Make sure you have R installed. There is no need to install the AMR R package, as it will be installed automatically.

   For Linux:

   # Ubuntu / Debian
   sudo apt install r-base
   # Fedora:
   sudo dnf install R
   # CentOS/RHEL
   sudo yum install R
   

   For macOS (using Homebrew):

   brew install r
   

   For Windows, visit the CRAN download page to download and install R.

Examples of Usage

Cleaning Taxonomy

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

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”.

Calculating AMR

import AMR
import pandas as pd

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

[0.59555556]

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:

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)

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.

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, antimicrobials, clinical_breakpoints, and example_isolates, are now available as regular Python data frames:

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

AMR.antimicrobials

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 Channels

Stable Release (CRAN)

The default AMR Python package uses the latest stable version of the AMR R package, published on CRAN. After running pip install AMR, import it as usual:

import AMR

AMR.example_isolates

Development Version (GitHub)

To use the latest development version of the AMR R package (sourced directly from GitHub), import the beta sub-package and alias it as AMR:

import AMR.beta as AMR

AMR.example_isolates

Aliasing with as AMR keeps all downstream code identical to the stable import. Switching between the stable release and the development version requires changing only the import line — nothing else in your script needs to change.

SIR Classification with as_sir()

Using enforce_method

The as_sir() function in R uses S3 method dispatch to select the correct calculation method based on the input class: <mic> for MIC values and <disk> for disk diffusion values. Because Python objects do not carry R class attributes through the rpy2 bridge, this automatic dispatch may not resolve correctly.

To explicitly specify the input type, use the enforce_method argument:

# Treat the column as MIC values — maps to R's as.sir.mic()
AMR.as_sir(df["MIC_col"], mo="E. coli", ab="AMX", guideline="EUCAST", enforce_method="mic")

# Treat the column as disk diffusion values — maps to R's as.sir.disk()
AMR.as_sir(df["disk_col"], mo="E. coli", ab="AMX", guideline="EUCAST", enforce_method="disk")

Without enforce_method, R falls back to class-based dispatch on the raw Python input, which may fail or return unexpected results. Always supply enforce_method when calling as_sir() from Python.

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 just running import AMR, users can seamlessly integrate the robust features of the R AMR package into 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.