Troubleshooting¶
Opening data¶
- The Plate dialog shows my files but the grid is empty.
- PlatAnJr could not work out well positions from the file names. Click Auto to fill
the wells in list order, or drag files into place. The layout is saved to
INFO\PlateMap.csvand reused next time. - The wells are in the wrong positions.
- Use <<< and >>> to rotate the whole layout if everything is shifted by one; drag
individual files otherwise. Clicking OK rewrites
PlateMap.csvwith the corrected layout. - It opens with the old layout and ignores the file names.
- That is by design: an existing
PlateMap.csvwins over name decoding. Use Delete All and lay it out again, or deleteINFO\PlateMap.csvto go back to automatic decoding. - Loading is very slow, or memory runs out.
- Reduce the parameter list with Select Parameters, and use Preview mode while you set the analysis up. A plate is held in memory in full. See Memory and event counts.
- A folder opens with no dialog at all.
- That happens when the folder was passed on the command line. Open it from the toolbar instead to get the dialog.
Plots¶
- The plot is empty.
- Check, in order: is a dataset loaded (the toolbar shows the folder and event count)? Are X and Y set to parameters that exist? Is the node fed by a gate that contains no events - look at the % parent column upstream?
- Everything is crushed against one axis.
- The scale is wrong for that parameter. Double-click the chart and pick BiExp or Hyperlog for fluorescence, Linear for scatter. See Parameters and scales.
- The axis keeps jumping as I change gates.
- Autoscale is refitting to each new population. Either turn autoscale off with the fit button on the node's floating toolbar, or turn on X SuperMax / Y SuperMax in the chart editor so the window only ever widens.
- My gate disappeared from the plot.
- The chart's axes were changed. The gate still exists and still works - click its row in the gate grid to bring its parameters back onto the axes.
- Two obvious populations are drawn as one blob.
- Turn Equalize off. It flattens the peaks along with the background, which is exactly what hides the valley between two populations.
- I cannot finish a polygon gate.
- Click the first vertex again - it only becomes a closing target once you have more than three vertices - or right-click anywhere to finish.
Gating¶
- Dragging a pin onto a node does nothing.
- Either that gate already feeds the node, or the link would create a loop. Follow the wires: somewhere downstream, the target is already an ancestor of the node you are dragging from.
- A new gate has an odd name.
- New gates are named from where they lie on the axes. Click the name in the gate grid to change it - see Gate names.
- Autogate produces nothing.
- Every population large enough has already been gated. Anything holding less than about 1% of the events is treated as a tail, not a population.
- Autogate drew one gate over two clearly separate clusters.
- Check that Equalize is off for judging, and that the plot is not zoomed so far in that the valley between them is off screen. Autogating already disables equalization internally for the search itself.
- Quadrants are in the wrong place.
- They are built to span the currently visible window. Set the zoom first, delete them and create them again.
- Percentages do not add up.
- Check whether you are reading % (of the whole dataset) or % parent (of the population feeding the node). Gates on the same node can overlap, so their percentages need not sum to 100.
Compensation and unmixing¶
- Compensation makes everything worse.
- Check the diagonal of the matrix. If it is not 1, clear Normalize so each row is rescaled by its own diagonal, and apply again.
- Straiten says "Straightened Already".
- The linearity correction can only be applied once per loaded dataset. Re-open the plate to do it again.
- Unmixing leaves large negatives.
- Try Non Negative LSM, or add Ridge regularisation. Check first whether the negative control assigned to the affected dye is the right one - a wrong background is a more common cause than a wrong solver.
- Two dyes will not separate no matter what I do.
- Look at Cosine / Angle in the matrix window. If their spectra are nearly parallel, no solver can separate them - it is a panel design problem.
- Unmixing is very slow.
- Make sure Fast Poisson / NB solver is ticked. It optimises the same objective orders of magnitude faster.
- Get From DB says the collection has no spectra for my data.
- It offers only spectra recorded on the data's device - and, with Match S/N ticked, on that very instrument - by an assay that measured every parameter being unmixed. The message says which of these it looked for; see When nothing is listed.
Projects¶
- I loaded a project and the nodes are empty.
- Either the data is not loaded yet, or the parameter names do not match. Projects refer to parameters by name. Check Options ▸ Parameter Scales for the names in the current dataset.
- A phenotyping or SSM node stays empty after loading a project.
- Its parameters are not in the data yet - unmixed parameters, typically, in a project opened before the unmixing. Run Add Unmixed Parameters: the node finds them and fills in by itself, with its saved settings.
- A project that plots my derived parameters comes back broken.
- Derived parameters are not stored in the project - they belong to the loaded dataset. Recreate them before loading the project.
- I erased a project by accident.
- Click Load last saved protocol. It restores the automatic backup taken just before the erase. It goes back one step only.
- PlatAnJr does not ask whether to save.
- Annoying Mode on the MoreOptions page is off - it is off whenever PlatAnJr starts. Turn it on for the session, or save as you go.
Numbers¶
- Counts look far too low.
- Preview mode is probably still on. Release the toolbar button and re-open the plate.
- CVs are higher than I expect.
- On skewed populations use MedianCV in the Gates table rather than CV - it is built from the median and MAD and is far less sensitive to outliers.
- My SSM values do not match the ones from another program.
- PlatAnJr uses a unitless SSM definition, deliberately different from the standard formulation. The values are internally consistent and comparable between detectors, but not against a published SSM computed the other way. See the definition used here.
Getting help¶
When reporting a problem, include:
- the version from the Copyright info tab,
- what was loaded (number of wells, number of parameters, preview on or off),
- whether a project was loaded, and from where,
- the exact text of any message.