Almost every “AMASS won’t run” problem is one of a small number of simple causes — not a broken program. Before anything else, prove that AMASS itself works on your computer by running it with the example data set that comes inside your AMASS folder. If the example works and your own data doesn’t, the problem is in your files, not in AMASS.

If the example data set does not produce a report, the problem is your computer set-up. Check these:

• You are using an old version. Open AMR_surveillance_report.pdf from the example and check the cover shows version 4.0, build 4028 or newer. If it shows build 4021/4022/4024, download the latest version (see 1.7).
• Regional setting. A very common cause of the example failing is the computer’s region. AMASS reads dates and numbers using your Windows region format, so if your computer is set to a region other than the United States or the United Kingdom, change it to either US or UK before running (Windows Settings → Time & language → Region), then run again.
• The files weren’t copied to the right place. The data and dictionary files must sit in the same folder as AMASS.bat, not in a sub-folder.
• The folder is blocked or read-only. AMASS needs to write new files. Avoid running from inside a zip file, a network drive with restricted permissions, or a protected system folder. Unzip the download fully and run from a normal folder (for example your Desktop or Documents).

If you have checked all of the above and still cannot run AMASS, send us the log files and we will help — see 8.6.

When AMASS runs to the end but you don’t get AMR_surveillance_report.pdf, the run stopped before the report was written. The cause is almost always in the input files or dictionaries.

A missing cover page usually means AMASS hit a problem while assembling the report — often a dictionary value it could not process. Real examples we have seen and fixed:

Good — that tells us AMASS and your computer are fine, so we only have to fix your files. Compare your set-up with the example, which is already correct, and check these in order:

1. File names match exactly, with no extra spaces or characters (2.3).
2. File format is .xlsx or .csv, and each Excel file has only the one data sheet (2.2, 2.5).
3. Dictionaries are the version-4.0 (build 4028) templates, with your column names and values mapped in (3.2).
4. HN format and dates are consistent across your files (6.5, 6.6).

A practical tip: start from the example dictionaries and replace the example values with yours, rather than starting from a blank or an old dictionary.

Don’t worry about the exact wording of the error — the log files tell us where it happened. Two patterns cover most cases:

Open any AMR_surveillance_report.pdf you have generated and look at the cover page. It states the version and build, e.g. version 4.0, build 4028. Many problems — missing Annex E and F, missing organisms, old dictionary behaviour — are simply because an older build was used.

AMASS uses up to three data files from your hospital, each paired with a dictionary that tells AMASS how to read it:

• microbiology_data + dictionary_for_microbiology_data — required. This is the minimum AMASS needs to make a basic AMR report.
• hospital_admission_data + dictionary_for_hospital_admission_data — optional, but needed to split infections into community- vs hospital-origin, to count patient-days, and for mortality.
• drug_data + dictionary_for_drug_data — optional, needed for Annex D (antimicrobial use).
• dictionary_for_wards — maps your wards/departments; used by several annexes (including cluster signals and antimicrobial use by ward type).

If admission or drug data are not available, AMASS still generates a basic report from the microbiology data alone. The exact list of essential variables for each file is in the user manual.

File names must match the AMASS standard exactly. This is one of the most frequent reasons a run fails, so check it carefully.

• Use the exact names: microbiology_data, hospital_admission_data, drug_data and the matching dictionary_for_… files.
• No extra spaces before, inside, or after the name (e.g.  hospital_admission_data.xlsx with a leading space will not be found).
• No special characters and no version suffixes like microbiology_data(2).xlsx.
• Names and the program file AMASS.bat are case-sensitive.
• The correct extension is .xlsx or .csv — not .xls.

If a log file reports that, say, hospital_admission_data.xlsx or drug_data.xlsx cannot be found, the file is either not in the right place or not named exactly right.

A few words are reserved inside the AMASS program and cannot be used as column names in your data. Known examples are return_drug and prescribe_dept. If one of these appears as a column — especially an empty one — the run can stop.

AMASS reserves a set of column (variable) names inside its three data files — microbiology_data.xlsx, hospital_admission_data.xlsx and drug_data.xlsx. If one of your own columns is named the same as a reserved word, the program can behave unexpectedly.

The reserved names are:

• HN
• hospital_number
• specimen_collection_date
• specimen_type
• infection_origin
• date_of_admission
• date_of_discharge
• discharge_status
• discharge_type
• gender
• drug_name
• drug_start_date
• drug_stop_date
• return_drug
• route_of_administration
• ward_microbiology_data
• ward_admission_hospital_admission_data
• ward_discharge_hospital_admission_data
• ward_drug_data
• department_of_prescribing_doctors

Every hospital records data differently — different column names, different codes, different languages. A dictionary is a small spreadsheet that maps your local terms to the standard AMASS terms. For example, your microbiology file might call the organism column CORGANISM and record E. coli as ESCCOL; the dictionary tells AMASS that these mean the standard organism “Escherichia coli”.

There are four dictionaries — for microbiology, hospital admission, drug, and ward data. Each has two jobs: (1) map your column names to the variables AMASS expects, and (2) map your data values (organisms, antibiotics, specimens, discharge status, wards, routes, etc.) to the AMASS standard list.

Using the newest version-4.0 dictionaries matters: they come pre-filled with a large default list of organisms and antibiotics, so if your data has no unusual names you may barely need to add anything — and the new annexes (E and F) will appear correctly. You can find ready-made example dictionaries in the example folder (e.g. Example_dataset_5_AMU).

Don’t convert the old file in place — the structure changed too much (new columns, new rows, revised organism lists), so editing a v3.0 file to look like v4.0 is more likely to fail than to work.

This is a key difference between the dictionaries:

• In dictionary_for_microbiology_data, each antibiotic (and the HN field) must map to exactly one column in your data — a strict 1-to-1 match. You cannot add a second row for the same antibiotic.
• In dictionary_for_drug_data, you can add several rows for one antibiotic (for example to capture different spellings) — that’s allowed there.

In the microbiology and drug dictionaries (version 4.0), you can map values using wildcards, which saves time when your data has many spellings. The asterisk * stands for “any text”.

Before AMASS can map values, the dictionary must point at the right column names in your data. If the dictionary still names an example column that isn’t in your file, that whole field is ignored.

Hospitals do not record returns the same way, so tell AMASS which values mean “returned” by mapping them to return_drug_yes in dictionary_for_drug_data.xlsx. This field accepts several values and wildcards, so you rarely have to list every possibility by hand.

The variable-name mapping sections in the AMASS dictionaries must be filled in 1-to-1: one variable name maps to exactly one column. These are the sections whose heading contains “Variable names used for…” (or “Variable names used in AMASS”):

• Dictionary_for_microbiology_data.xlsx — [SECTION_01] Variable names used in AMASS; [SECTION_02] “antibiotics”; [SECTION_08] (optional, long-format data); [SECTION_10] (optional, “antifungal”).
• Dictionary_for_hospital_admission_data.xlsx — [SECTION_01] Variable names used in AMASS.
• Dictionary_for_drug_data.xlsx — [SECTION_01] Variable names used in AMASS.
• Dictionary_for_ward.xlsx — [SECTION_01] Variable names used in AMASS.

Tip: a peer hospital using the same type of Lab system may have solved this before, so it is worth asking them how they built the merged export column.

Annex C flags possible clusters (outbreaks) of drug-resistant, hospital-origin infection — times and wards where the resistant-infection rate rose significantly above the baseline. It uses the SaTScan statistical method (www.satscan.org) on two models: a blood-specimen model and an all-specimen model, for infections found more than 2 calendar days after admission (hospital-origin).

It reports clusters for the key resistant organisms, including MRSA, vancomycin-resistant E. faecalis and E. faecium (VREfs/VREfm), and carbapenem-resistant E. coli, K. pneumoniae, P. aeruginosa and A. baumannii (CREC/CRKP/CRPA/CRAB).

Annex D depends entirely on the drug data and its dictionary. Work down this list:

Annex F reports fungal bloodstream infections and antifungal use. If it’s absent, check these in order of likelihood:

DOT (days of therapy) appearing as 0 where you expect use usually points to a matching or mapping problem rather than genuinely zero use. Check:

“Unknown origin” means AMASS couldn’t match a positive culture to a hospital stay, so it couldn’t decide whether the infection was community- or hospital-origin. There are two common reasons:

Grey bars in Sections 2 and 3 are a warning that susceptibility (AST) results are too few or unreadable. Two separate situations cause this:

Use DDD as an independent yardstick for the DOT that AMASS reports. The idea is a sanity check, not an exact match — the two metrics are defined differently, so some difference is expected.

The workbook compares the DOT from AMASS with your DDD-based consumption. It has four sheets and you only touch two of them:

Download the file at https://doi.org/10.6084/m9.figshare.32947019. It will also be posted on the Downloads page.

The ward dictionary maps each ward from your data to a ward ID, a ward name, and a ward type/department group. Build it from the unique ward list in your microbiology and admission data (a pivot table is an easy way to get the de-duplicated list).

AMASS uses three discharge outcomes: died, transferred to another facility, and discharged against advice. Mortality and several sections depend on these being mapped correctly in dictionary_for_hospital_admission_data.

DOT for parenteral antibiotics depends on the route being recognised. Drugs whose route can’t be mapped are recorded as unknown route and left out of the DOT calculation, which can change Annex D substantially.

AMASS links a patient’s microbiology, admission and drug records using the hospital number (HN). If the HN is written differently in different files, the records won’t link — which inflates “unknown origin” and zeroes out DOT.

Use a single, unambiguous date format in every data file: day, a three-letter English month abbreviation, and a four-digit CE (Christian-era) year — for example 12 Jan 2025. Written this way the system never has to guess whether a value is day-month-year or month-day-year.

AMASS uses both EUCAST and CLSI as reference standards for interpreting antimicrobial susceptibility testing (AST). It works from the final report given to the clinician, reading each result as an interpretive category rather than a raw measurement.

Before trusting the figures, confirm that AMASS read the expected date range and a sensible number of records from each data file. Two output files let you check this.

Use Table S1na in Data_verification_logfile_report.pdf to check that every organism is mapped. It lists organisms that appear in your LIS results (Microbiology_data.xlsx) but are not yet mapped in Dictionary_for_microbiology_data.xlsx.

Tables S1a and S1b list organisms that are mapped in Dictionary_for_microbiology_data.xlsx. Both tables show the number of specimens found in your LIS results (Microbiology_data.xlsx) — across all specimen types and specifically in blood specimens.

Table S2 shows how the specimens that appear in your LIS results (Microbiology_data.xlsx) are mapped to the various specimen types.

Table S3 maps the antibiotics used for susceptibility testing (SIR), as they appear in the column headers of your LIS results (Microbiology_data.xlsx), to the antibiotic names used in AMASS.

Table S6a shows how the Discharge status values in hospital_admission_data.xlsx are mapped to the values defined in Dictionary_for_hospital_admission_data.xlsx. Table S6b does the same for Discharge type.

AMASS is designed to run locally on your own computer. You download the program, place your data files in its folder, and it processes everything on that machine to produce the PDF reports. It does not require your patient-level data to be uploaded to MORU or anyone else.

If you are hospital staff analysing your own hospital’s data as part of your duties — for example to produce a cumulative antibiogram / AMR surveillance report for routine service — ethical clearance is usually not required. If you are unsure whether you’re permitted to analyse the data, check with your line manager. Anything beyond routine service use (such as research or publication) may need approval under your local rules.

After a successful run, version 4.0 organises outputs into two folders:

• ResultData — the AMR surveillance report, supplementary reports for Annexes B–D, and summary data files, without patient identifiers. Use/share these for further analysis internally or externally.
• Report_with_patient_identifiers — the processed (de-duplicated and merged) data files that do contain identifiers, kept so you can do your own further analysis. Keep these inside your hospital.

You’ll also see the verification reports and log_*.txt files in the main folder; these help you and the AMASS team diagnose any problems.

The report is built to support local and national decisions: tracking resistance over time, comparing community- vs hospital-origin infections (Section 3), spotting possible outbreaks (Annex C), reviewing antibiotic use (Annex D), and informing your antibiogram, IPC and antimicrobial-stewardship work.

Yes — and you should. Once your dictionaries work, save them. Next time you re-export your hospital data, AMASS can reuse the completed dictionaries automatically if they’re in the same folder, as long as your system’s column names and codes haven’t changed.

If you’re willing to share your completed dictionaries (especially for a common hospital or lab information system), the AMASS team would be glad to host them and credit you — it helps many other hospitals in low- and middle-income countries. Contact AMASS@tropmedres.ac.

Email the AMASS team at AMASS@tropmedres.ac, or post in the AMASS Google group.

AMASS content is © MORU and may be used under the Creative Commons Attribution Non-Commercial Licence — free to use, share and adapt for non-commercial purposes, provided the original work is properly cited.

Open AMR_surveillance_report.pdf (in the ResultData folder for version 4.0). The report is organised into numbered Sections and lettered Annexes:

Full guide: for a step-by-step walkthrough of turning these results into local and national action, see the open-access paper Chamawan & Limmathurotsakul, How to utilize routine antimicrobial resistance surveillance data for local and national actions in an LMIC (JAC-Antimicrob Resist. 2025;7(6):dlaf225) — free full text: PMC12669895.

Use isolate-based figures (resistance %) for treatment guidance, and sample-based figures (incidence/burden) for tracking the problem over time and comparing periods.

Sections 3 and 5 split infections by where they most likely started:

• Hospital-origin (HO): the positive specimen was collected more than 2 calendar days after admission — the infection most likely developed during the hospital stay.
• Community-origin (CO): the specimen was collected at or around admission — the patient most likely arrived with the infection.

This split needs hospital_admission_data; without it, infections show as “unknown origin” (see 5.4). The distinction matters: hospital-origin resistant infections point to in-hospital transmission (an IPC priority), while community-origin patterns inform empirical treatment choices.

Annex D summarises inpatient antibiotic and antifungal use from drug_data, broken down by month, route (IV/IM/IP/oral), drug and ward type. The key measures:

• DOT (Days of Therapy): the number of days a patient received a given antibiotic (one drug for 5 days = 5 DOT). It’s the main use metric, usually shown as a rate per 1000 patient-days.
• LOT (Length of Therapy): the number of days a patient was on any antibiotic, regardless of how many drugs at once. DOT divided by LOT hints at how many antibiotics patients receive at a time.
• AWaRe: the WHO Access / Watch / Reserve classification. A high share of Watch and Reserve use is a common stewardship target.

Section 6 compares deaths in patients with resistant versus susceptible infections (it needs admission data with discharge status — see 6.2). Annex E ranks the bloodstream pathogens (the most common organisms), splits community- versus hospital-acquired, and shows the percentage and the associated mortality for each.

Together they show both how common and how serious resistant bloodstream infections are at your hospital — useful for prioritising which pathogens to tackle first.

Annex A lists notifiable bacterial infections (in version 4.0, based on both the microbiology data and hospital-admission information) — helpful for mandatory disease reporting to public-health authorities.

Annex B is your data-quality check: it reports the proportion of likely contaminants and the proportion of discordant AST results (susceptibility patterns that look inconsistent). Read Annex B — and the separate data-verification report — before you trust the main numbers. A high contaminant rate or many discordant results means the data should be cleaned first.

A cluster signal means resistant, hospital-origin infections rose above the expected baseline in a particular ward and time window. It is a prompt to investigate, not proof of an outbreak.

See 4.3 for exactly which organisms and models Annex C covers.

Common, practical uses:

• Antibiogram & empirical therapy: use the isolate-based resistance percentages (Sections 2–3) to build or refresh your cumulative antibiogram and guideline.
• Antimicrobial stewardship: use Annex D to spot high Watch/Reserve use or specific wards to target.
• Infection prevention & control: focus where hospital-origin resistant infections and Annex C clusters concentrate.
• National reporting: share the de-identified ResultData summaries with provincial/national AMR dashboards.

Most hospitals run AMASS once a year on a full calendar year (1 January–31 December), with all three data files covering the same complete period (see 6.6). You can run more often — for example quarterly — for timelier feedback, but shorter periods produce smaller numbers and noisier rates.

Yes — but only when the inputs are comparable. Before comparing, check:

• Data completeness — was a month or a data source missing in one period?
• AST coverage — the grey-bar / under-70% warning (see 5.6) means a denominator is incomplete.
• Same pathogens and denominators — compare like with like.
• Unknown-origin and referral testing — large differences here distort comparisons (see 5.4).

Sample-based rates (Sections 4–5) are generally better than raw isolate counts for comparing burden. For multi-hospital or national comparison, the standardised ResultData outputs are designed to be combined across hospitals.

A return drug is medicine that was dispensed but then returned, so it was not actually used by the patient. In Annex D (antimicrobial use) these records should not be counted. AMASS finds them by reading the return_drug column in your drug data and comparing each value with the list you map to return_drug_yes in dictionary_for_drug_data.xlsx.