PET tutorial

PET, start to finish.

Two PET scans in the two formats PET actually comes in, taken from a raw folder to a validated BIDS dataset. Both convert in seconds. What takes longer, and what this page is really about, is the metadata: PET asks for a great deal that no scanner writes down, and the two formats leave out different parts of it.

Get the data

The sample dataset.

Unzip it anywhere you like, for example your desktop or a scratch folder. You do not need to put it in any particular place, and you never point BIDS Manager at the zip itself. Inside are two folders, raw/ and extra_ecat/, and each becomes a project of its own. Both are phantoms of the same tracer, so the two runs are genuinely comparable.

What you downloaded

Every file, and what to do with it.

Eight things are in the zip. Two you point the application at, two you read while filling a form, two are licences, and two belong to the optional ECAT exercise at the end.

Where the data came from

The scan is one subject from the OpenNeuro PET brain phantoms (PublicnEUro PN000001, DOI 10.70883/RGN3768), a GE Advance FDG acquisition from the NIH Clinical Center, shared under CC BY 4.0. The blood curves come from the PET2BIDS project's own test data, under MIT. If you reuse either, the README in the download carries the credit you owe.

Before you start

PET arrives in two formats, and they are not equivalent.

Almost every other modality in this documentation has one shape. PET has two, and which one you are handed decides how much work the metadata step is going to be. That is why this page runs both from here on.

Step 1

Create two projects, then scan each one.

On the Home tab choose Create, give the dataset a folder and a name, for example pet_dicom. That folder becomes the BIDS dataset, and everything you do from now on is recorded into it. Then create a second one, pet_ecat.

In the Converter, press Scan and point the first project at the download's raw/ folder and the second at extra_ecat/. Point at the folder itself, not at PET/ and not at a single file. The scan walks down through everything below it.

What the scan does with PET

• The 35 DICOM files become one row. They are slices of a single acquisition, grouped by the series identifiers in their headers. The ECAT file becomes one row too, because it was one file to begin with.
• The blood files are not recordings, so they do not appear as rows. You attach them to the PET row in Step 5. Only the DICOM scan has them.
• Neither dose sheet is read here. A .csv is not a recording either. You read it yourself in Step 4.

What you should see now: one row in each project, no skips, a green status. The chips read one valid.

Step 2

Read both tables before you change anything.

One row each, and for these two datasets nothing in either needs correcting. Read them anyway: on your own data this is the step where mistakes are cheap to fix.

What the scan worked out but did not fill in

Vendors write the interesting PET fields as free text, in whatever spelling the console used. The scan reads them and derives what it can. This is the first place the two formats visibly differ.

From the DICOM it gets five values, all correct:

• tracer FDG, read out of FDG -- fluorodeoxyglucose
• radionuclide F18, read out of 18F. Other scanners write it as ^18^Fluorine, and that is understood too
• reconstruction method 2D Filtered Backprojection
• reconstruction filter rectangle 4.0 mm, from three separate values the header splits it across
• injected radioactivity 75.85 MBq, converted from the 75850000 becquerels the header stores

From the ECAT it gets one: F18. There is no tracer name, no reconstruction method and no usable dose in that header. Nothing has gone wrong; the format simply carries less.

None of these appear as columns. They are offered inside the fields they belong to, in the properties panel and the metadata form, with the value read from your own files at the top of the list. Nothing is filled in silently, because a vendor writes these as free text and a wrong tracer is worse than a blank one.

The same panel carries a DOSE FILE section, inside the PET block and directly above blood sampling. Importing a dose file there fills the fields below it, which is the point of putting it in the same panel: you see what the file answered, on the recording it answered it for, without opening anything else.

Step 3

What each conversion answers by itself.

Before you type anything, it is worth knowing how much you will not have to, and it is not the same for the two formats. Converting the DICOM scan writes 33 fields into the sidecar, straight from the headers. Converting the ECAT writes 50, because pet2bids reads that format's header differently and fills more of the frame of the sidecar. Neither number is the interesting one; what matters is which fields.

Nine representative fields from the DICOM conversion:

Two of those are worth pausing on, because they are often assumed to be your job. TimeZero is the instant every frame time and every blood sample is measured against, and InjectedRadioactivity is the dose. This scanner wrote both, so you do not have to. Many do not, and the ECAT in this download is one of them.

Where the two formats part company

Convert both, validate both without letting the metadata step write placeholders, and each reports required fields missing. The DICOM reports nine, the ECAT fourteen, and only six of them overlap:

Read the middle column and the right one together and you have the difference between the two formats in one line. The GE DICOM recorded what it injected, what it corrected for and what filter it reconstructed with, and left the reconstruction parameters unstated. The HRRT's ECAT header recorded none of the first group, down to which tracer it was. Six fields are missing from both, because they come from the radiochemistry lab and no scanner of either kind has ever seen them.

Neither format is worse. They were designed by different people for different purposes, decades apart, and BIDS asks for the union of what both leave out. That is the argument for a metadata step that reads the standard rather than one converter.

Those 33 land in sub-001_pet.json when you convert, in Step 6. You can see them before that, without converting anything: the metadata form in Step 4 folds them away under Already answered by the conversion, so the questions it puts to you are only the ones nothing could answer for you.

Step 4

Fill each template from its own dose sheet.

Each project has a dose sheet, and they are different files because the two formats leave out different things. Open the one that belongs to the project you are working on, in a spreadsheet or a text editor, and put it beside the application. This is the piece of paper a PET centre keeps by the scanner.

Neither list is an arbitrary selection. We converted each scan, asked the validator what was still missing, and wrote that down. The values are the ones published with the phantom datasets, not invented.

Three ways in, and when each is the right one

Typing the values into the form, which is what the rest of this step walks through, is one of three routes. They all end in the same place, so the choice is about where the numbers already live.

A flat JSON object applies to every PET run in the conversion. An object keyed by sub-<label> scopes it per subject, which is what a study with a different dose per participant needs:

// dose.json, scoped per subject
{
  "sub-001": {
    "TracerName": "FDG",
    "TracerRadionuclide": "F18",
    "InjectedRadioactivity": 75.85,
    "InjectedRadioactivityUnits": "MBq",
    "ModeOfAdministration": "bolus"
  },
  "sub-002": { "InjectedRadioactivity": 81.20 }
}

bidsmgr-convert inv.tsv /data/bids --pet-metadata dose.json

Keys BIDS does not define for a PET sidecar are reported and dropped, never written, so a file carrying a lab's own extra columns is safe to hand over as it is.

Open the form

Below the inventory table, press Dataset metadata. Scroll to the PET sections. A section covers every file of its kind at once, so an answer typed here is written into every PET scan in the study, not just this one. With a single scan the distinction does not bite, but it is the reason the form is organised this way.

The nine fields, one at a time

The same form, a different set of questions

Open the ECAT project's form and the layout is identical, because the form is built from the standard rather than from the file. What changes is which boxes are already filled. Under Already answered by the conversion you will find the ECAT's Units, TimeZero and frame timing; in the fields it is asking you for, you will find the dose and the reconstruction filter, which on the DICOM scan were answered for you.

Fields you can leave alone

The PET sections list far more than nine fields, and most of the rest are recommended rather than required: infusion speed, molar activity, the pharmaceutical dose regimen, the tracer's molecular weight. If your study did not record them, leave them empty. A blank recommended field is a warning you have read and decided about; a made-up value is worse than nothing.

Two are worth filling on real data even though they are only recommended: BodyPart and InstitutionalDepartmentName. Both are trivial to answer and both are the sort of thing a reader of your dataset will want.

When one scan differs from the rest

Everything above is a statement about every PET file in the study. If one session used a different tracer batch, or one run had its own injected dose, select that row and answer in the properties panel instead. A per-recording answer wins for that recording alone, and an inherited value is shown greyed with a tooltip naming where it came from, so you can always tell what you set from what you are inheriting.

Step 5

Attach the blood curves. DICOM project only.

Only the DICOM scan in this download has blood. Nothing about blood depends on the image format, though: the curves are separate files and would attach to an ECAT row in exactly the same way. Skip to Step 6 for the ECAT project.

Quantitative PET rests on knowing what the tracer was doing in the blood while the scanner counted it in tissue. BIDS has a place for that, and your lab probably has it as a PMOD export. In this download it is the two .bld files.

Select the PET row, then find BLOOD SAMPLING in the properties panel on the right. Three curves can be attached separately, and this dataset has two of them.

Why the method matters

Marking a curve manual or automatic is not a description you can skip. Hand-drawn samples and an autosampler have different time resolution, so the standard keeps them in separate files, distinguished by an entity in the filename. Set these two to manual and the conversion writes sub-001_recording-manual_blood.tsv. Had they come from an autosampler it would be recording-autosampler instead. The answer changes the output, not just the description inside it.

What comes out

The two curves are merged into one table, with the times converted from minutes to seconds, because that is what BIDS asks for:

time    plasma_radioactivity    whole_blood_radioactivity
25.2    0.000874                0.000885
43.2    0.00603                 0.0192
51.0    1.38                    0.92

Nineteen samples, one row each. The times were minutes in the .bld files and are seconds here, which is what BIDS asks for. They are written at full precision, so the second sample is really 43.199999999999996: that is the unit conversion showing its arithmetic, not anything being wrong.

Alongside it, sub-001_recording-manual_blood.json describes those columns and records which curves are present, through the WholeBloodAvail, PlasmaAvail and MetaboliteAvail flags. Those flags are set from the columns that actually exist, so they cannot claim a curve you did not supply.

Step 6

Convert both.

Open the BIDS preview in the bottom panel first. It shows the exact tree the conversion will write. You should see the image, its sidecar, and the two blood files:

pet_tutorial/
├── dataset_description.json
├── README
└── sub-001/
    └── pet/
        ├── sub-001_pet.nii.gz
        ├── sub-001_pet.json
        ├── sub-001_recording-manual_blood.tsv
        └── sub-001_recording-manual_blood.json

Then press Run conversion. The DICOM goes to dcm2niix; the blood curves go to pet2bids; and in the other project the ECAT goes to pet2bids as well. You never choose a backend: the content of each row decides, which is the same reason a renamed file still converts.

What happens after the files are written

Three things run automatically, in the staging folder, before anything is committed to your dataset.

• The DICOM keys are renamed to their BIDS names. dcm2niix writes some fields under the spelling the DICOM standard uses, which is not always the spelling BIDS uses.
• Types are repaired against the standard. Several PET fields are per-frame arrays even when there is one frame. A scalar where the schema declares a list is corrected.
• Patient identifiers are pruned. Name, identifier, birth date and referring physician are removed from the sidecar. The study and series identifiers stay, so an image can still be traced back to the series it came from.

Then the metadata step writes in the nine answers you gave, and marks anything still missing with a literal TODO so it cannot be quietly forgotten.

Step 7

Validate, and see the point of the exercise.

Switch to the Editor, open a dataset, and press Validate dataset. Here is the DICOM dataset validated twice, once with the dose sheet skipped and once with it filled in:

That gap is the argument for the whole metadata step. The conversion was never wrong: it wrote 33 fields correctly and could not have produced the other nine from anything in the files. Without somebody answering them, the dataset is incomplete in a way that only shows up when a validator, or a colleague, goes looking.

The ECAT project, for comparison

Validate the other one and the arc is the same shape with different numbers: 4 errors and 47 warnings before its dose sheet and 0 and 39 after, on a sidecar that grows from 55 fields to 59. It has no blood file, so nothing is left over at the end. Turn the placeholders off, as above, and the same two runs read 14 and 31 before and 0 and 29 after, on a sidecar that grows from 23 fields to 38: fifteen answers rather than the DICOM scan's nine, because that header left more out. Both datasets end at zero, which is the point. The format decided how much you had to type, not whether you could finish.

The one question the blood file asks back

One error is not about the scan at all. It sits on sub-001_recording-manual_blood.tsv and reads missing required field DispersionCorrected. BIDS requires every blood table to state whether the curve has been corrected for dispersion, the smearing a sample picks up on its way through the tubing. It is a yes or no, nobody but the person who drew the samples can answer it, and no converter should guess.

Press Fix on the finding. The Editor opens sub-001_recording-manual_blood.json and puts the cursor in that field. For hand-drawn samples like these the answer is false. Save, re-validate, and the dataset is clean.

Checks that only apply to PET

Beyond the standard's own rules, a few cross-field checks catch numbers that disagree with each other. They are warnings, never errors, because they are judgements rather than violations: a dose that looks like it was entered in the wrong unit, a specific activity that does not follow from the dose and the mass, frames that run backwards, a timing offset with no reference time to measure from.

Step 8

Look at what you made.

Click the image in the Editor's tree. It opens in the viewer: one plane at a time, or Multi-Planar for sagittal, coronal and axial sharing one crosshair. A phantom looks like what it is, a uniform cylinder, which makes it a good sanity check: the activity should be even, and anything obviously lopsided means something went wrong upstream.

Click the sidecar and you get the schema-aware form, where the nine fields you typed now appear alongside the 33 the conversion read. This is also where you would fix anything the validator flagged, with the finding's own fix button taking you straight to the field.

Dynamic scans, and why the axis is in seconds

This sample is a single frame, so it has no time course. On a dynamic run the viewer's Graph button becomes available, and its x axis is real seconds taken from FrameTimesStart, not a frame index.

That matters more than it sounds. PET frames are not evenly spaced: ten seconds early in a scan while the tracer arrives, five minutes late on. Plotted against a frame index, the early kinetics, which is the part worth looking at, are compressed into the left edge and the long late frames are stretched out. On a real seconds axis the curve has the shape it actually has.

Beyond the walkthrough

Two more PET situations.

You have now converted both PET formats. Two other things you will meet on real PET data are worth knowing about, and neither is in the download.

Hybrid PET/CT and PET/MR studies

A PET/CT study converts its PET half and sets the CT aside with the reason shown: BIDS has no place for CT in a raw dataset. A PET/MR study converts both halves in one pass, the MR arriving as ordinary anatomical and functional data. You do not run anything twice, and you do not separate the study by hand first.

A dose spreadsheet instead of typing

Both dose sheets in this download are meant to be read and typed in, because that is how you learn what the fields are. On real data, if your radiochemistry already exists as a spreadsheet, point bidsmgr-convert --pet-spreadsheet at it instead. Column names are matched loosely, so Injected Dose and injected_radioactivity both work; the values are read strictly.

The same thing, scripted

From the command line.

The command line drives the same engine, and both scans work through it. Note that the two sequences below are identical apart from the folder: nothing in the commands says which format is which, because nothing needs to. The answers you gave in the GUI live in files rather than in the interface, so they are equally available to a script:

• the nine template fields go under sequence_templates["pet/pet"] in <inventory>.recording_meta.json, which the scan writes beside the inventory and the conversion picks up on its own. They are keyed by their BIDS names, so the file reads the way the standard does. The ECAT project has its own copy of the same file, holding its own fifteen
• the blood links go in the inventory's companion_files column, as a JSON list of {"suffix": "blood:plasma:manual", "path": "..."} entries

"sequence_templates": {
  "pet/pet": {
    "InjectedMass": 181149988.37,
    "InjectedMassUnits": "ug",
    "SpecificRadioactivity": 418713.8,
    "SpecificRadioactivityUnits": "Bq/g",
    "ModeOfAdministration": "infusion",
    "AcquisitionMode": "list mode",
    "ReconMethodParameterLabels": ["none"],
    "ReconMethodParameterUnits": ["none"],
    "ReconMethodParameterValues": [0]
  }
}

Note the shapes. Three of the nine are lists and one of those is a list of numbers, which is why ReconMethodParameterValues reads [0] and not ["0"]. The form handles that for you; a hand-edited file has to get it right itself.

# --- the DICOM scan -------------------------------------------------
bidsmgr-create ~/bids/pet_dicom --name "PET tutorial, DICOM"

bidsmgr-scan ~/BIDS_Manager_PET_sample/raw \
    --project ~/bids/pet_dicom --probe-convert

bidsmgr-convert --project ~/bids/pet_dicom \
    --raw-root ~/BIDS_Manager_PET_sample/raw

bidsmgr-metadata --project ~/bids/pet_dicom --fill-todos
bidsmgr-validate ~/bids/pet_dicom

# --- the ECAT scan, identical commands, different folder ------------
bidsmgr-create ~/bids/pet_ecat --name "PET tutorial, ECAT"

bidsmgr-scan ~/BIDS_Manager_PET_sample/extra_ecat \
    --project ~/bids/pet_ecat --probe-convert

bidsmgr-convert --project ~/bids/pet_ecat \
    --raw-root ~/BIDS_Manager_PET_sample/extra_ecat

bidsmgr-metadata --project ~/bids/pet_ecat --fill-todos
bidsmgr-validate ~/bids/pet_ecat

Every flag is documented in the CLI reference.

Troubleshooting

What usually goes wrong with PET.

Next

The multimodal tutorial shows PET converting in the same pass as MRI, EEG and MEG. The MRI tutorial covers the modality where the header answers the most.

The full GUI walkthrough → CLI reference