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

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.

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:

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.

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.