MatchEngine

Welcome to the documentation for the matchengine! The Matchengine is a system designed to match cancer patients to genomically driven clinical trials using Clinical Trial Markup Language (CTML) and patient clinical and genomic data. It utilizes the the MatchminerAPI and MatchminerUI for displaying trial match information.

The matchengine can be used on local instances that provide access to private data. If you are interested in the development of new features, or in setting up a local instance of the MatchMiner system, please see the documentation, or contact matchminer@dfci.harvard.edu

Documentation

Gitbook documentation

Running Tests

Prerequisites

• MongoDB running locally
• SECRETS_JSON.json at the repo root with your connection details (see SECRETS_JSON.json for format)
• Python virtual environment set up at .venv/

uv venv
uv pip install -e ".[dev]"

Setting up MongoDB

Matchengine requires a running MongoDB instance. The easiest way is Docker — no separate docker pull needed, docker run will pull the image automatically if you don't have it yet.

Before you run the following command, ensure you copy the SECRETS_JSON.example.json to SECRETS_JSON.json and source it so you have access to all the environment variables:

$ cp SECRETS_JSON.example.json SECRETS_JSON.json
# add the appropriate variables - FOR DEV - you can leave it as is or add a fake username/pass like dane/1234
$ source SECRETS_JSON.example

Next, run the docker container.

docker run -d -p 27017:27017 --name=mongo mongo:8.3.2

I recommend using the Docker Desktop app if you want a visual way to see the containers you have deployed.

To stop/start it later:

docker stop mongo
docker start mongo

Once you have this setup, you can load in data and do a match:

python -m matchengine.main load -t matchengine/tests/data/integration_trials --trial-format json --db integration
python -m Matcher.main --config source/Matcher/config/config.json

Note: the matchengine program uses the contents of your SECRETS_JSON.json to connect to the mongo database 🙂

Integration Tests

Runs the full matching engine against pre-loaded test data in the integration MongoDB database. Requires the integration db to be populated (BSON files at matchengine/tests/data/integration_data/).

Make sure MONGO_DBNAME in your SECRETS_JSON.json is set to integration.

SECRETS_JSON=SECRETS_JSON.json .venv/bin/python -m pytest matchengine/tests/test_matchengine_integration.py -v

Run a single test:

SECRETS_JSON=SECRETS_JSON.json .venv/bin/python -m pytest matchengine/tests/test_matchengine_integration.py::IntegrationTestMatchengine::test_tmb -v

Demo Tests

Loads two realistic patients into a demo MongoDB database and runs the matching engine against a FLAURA-style trial (NCT02477839) with three arms to demonstrate the engine's precision:

• MRN 1035 — EGFR p.E746_A750del (In_Frame_Del, 5 genomic docs including EXA p.L211M which has no trial match)
• MRN 1036 — EGFR p.L858G (Missense, 1 genomic doc)
• ARM A: EGFR + In_Frame_Del → MRN 1035 only
• ARM B: EGFR + any Mutation → both patients
• ARM C: EGFR + exact p.L858R → neither patient (demonstrates exclusion precision)

The database is created fresh on each run — no prior setup required.

Mock data lives in matchengine/tests/data/mock/.

SECRETS_JSON=SECRETS_JSON.json .venv/bin/python -m pytest matchengine/tests/test_matchengine_demo.py -v

Run All Tests

SECRETS_JSON=SECRETS_JSON.json .venv/bin/python -m pytest matchengine/tests/ -v

Dev

To run new patient data and trials, do the following:

1. Place the data in the appropriate folder to match the data version: for example, v1_data/ (root level)
   1. The data for clinical, genomic, and trial should be split into the v1_data/clinical, v1_data/trials, and v1_data/genomic folders
2. Load the data
   1. SECRETS=SECRETS_JSON.json .venv/bin/python -m matchengine.main load -t v1_data/trials/ -c v1_data/clinical/ -g v1_data/genomic --trial-form json --patient-format json --db v1
3. Match the data
   1. python -m matchengine.main match

Important:

• This data gets stored in the mongodb database under the database named v1 (see the --db v1 option which overrode where to store the results)
• Use MongoDB Compass to look at the results

MongoDB Output

After loading and matching, the database will have four collections:

clinical — One document per patient. Contains demographic and diagnostic fields: SAMPLE_ID, ONCOTREE_PRIMARY_DIAGNOSIS_NAME, BIRTH_DATE, VITAL_STATUS, GENDER, TUMOR_MUTATIONAL_BURDEN_PER_MEGABASE, etc. This is the primary key table — everything else links back to SAMPLE_ID.

genomic — One document per genomic finding per patient. Each document has a SAMPLE_ID, CLINICAL_ID (ref to the clinical doc's _id), TRUE_HUGO_SYMBOL, VARIANT_CATEGORY (MUTATION, CNV, SV, SIGNATURE), and variant-specific fields like TRUE_PROTEIN_CHANGE, CNV_CALL, MMR_STATUS, etc. A single patient typically has many genomic documents.

trial — One document per clinical trial, loaded from your CTML YAML files. Contains the trial metadata and the match tree that the engine evaluates against patient data.

trial_match — One document per patient–trial match result. Contains sample_id, nct_id, protocol_no, match_level (arm vs. step), reason_type (genomic vs. clinical), trial_summary_status, and the specific genomic alteration that triggered the match. This is the collection you query to build reports.

Creating a clinical trial report

Once the trial matching has completed: export the data using matchengine-export --db <db> --output export/ --patient <SAMPLE_ID>.

Take the output from this and refer to the ctm-report-preview docs to make the PDF or live report.