filetypes

This section describes the different file format and name conventions used in Picasso.

Movie Files

Picasso accepts several types of raw movie files: TIFF-family stacks (“.tif”/“.tiff”/“.ome.tif”/BigTIFF/Zeiss “.lsm”), raw binary data (file extension “.raw”), the Nikon format “.nd2”, MetaMorph “.stk”, Imaris “.ims” (Windows only), and — with the optional czi/lif extras (Python ≥ 3.12) — Zeiss “.czi” and Leica “.lif”.

When loading raw binary files, the user will be prompted for movie metadata such as the number of frames, number of pixels, etc. Alternatively, this metadata can be supplied by an accompanying metadata file with the same filename as the raw binary file, but with the extension .yaml. See YAML Metadata Files for more details.

For TIFF-family, “.nd2” and “.stk” movies the metadata is normally read directly from the file. If this metadata cannot be parsed, Picasso: Localize falls back to prompting the user to enter the required information (Frames, Width, Height and Pixelsize) manually; the field of view dimensions are pre-filled from the file when they can be read. As with raw files, the entered metadata can optionally be saved to an accompanying “.yaml” file so it is reused the next time the movie is opened.

HDF5 Files

HDF5 is a generic and efficient binary file format for storing data. In Picasso, HDF5 files are used for storing tabular data of localizations with the file extension .hdf5. Furthermore, Picasso saves the statistical properties of groups of localizations in an HDF5 file.

Generally, several datasets can be stored within an HDF5 file. These datasets are accessible by specifying a path within the HDF5 file, similar to a path of an operating system. When saving localizations, Picasso stores tabular data under the path /locs. When saving statistical properties of groups of localizations, Picasso saves the table under the path /groups. Since v0.11, Picasso also embeds the metadata directly in the HDF5 file under the path /metadata (see “Metadata” below), so that the file is self-contained.

An HDF5 file can be opened with various software packages. In Picasso, we use pandas for this purpose. For example, to open localizations, pandas.read_hdf(PATH_TO_LOCALIZATIONS, key="locs") is used. The key argument can be adjusted for other datasets. The available keys can be verified using pandas.HDFStore(PATH_TO_FILE).keys().

Note: Picasso HDF5 files store their metadata both in the embedded /metadata dataset and (by default) in an accompanying YAML metadata file, which are read together using locs, info = picasso.io.load_locs. See sections “Localization HDF5 Files”, “Metadata” and “YAML Metadata Files” below for more details on the minimum requirements to process HDF5 files in Picasso.

Importing HDF5 files in MATLAB and Origin

In MATLAB, execute the command locs = h5read(filename, dataset). Replace dataset with /locs for localization files and with /groups for pick property files.

In Origin, select File > Import > HDF5 or drag and drop the file into the main window.

Localization HDF5 Files

Picasso’s localization HDF5 files carry their metadata in two places: embedded in the HDF5 file itself under the path /metadata, and (by default) in a YAML metadata file with the same filename, but with the extension .yaml. See Metadata and YAML Metadata Files below for more details. locs, info = picasso.io.load_locs is used to read both the HDF5 file and the metadata. The localization table is stored as a dataset of the HDF5 file in the path /locs. This table can be explored by opening the HDF5 file with Picasso: Filter. The localization table can have an unlimited number of columns. Table 1 explains the main column names in Picasso.

Table 1: Name, description and data type for the main columns used in Picasso.
Column Name	Description	C Data Type
frame	The frame in which the localization occurred, starting with zero for the first frame.	unsigned long
x	The subpixel x coordinate in camera pixels.	float
y	The subpixel y coordinate in camera pixels.	float
photons	The total number of detected photons from this event, not including background or camera offset.	float
sx	The Point Spread Function width in camera pixels.	float
sy	The Point Spread Function height in camera pixels.	float
angle	(Optional) The in-plane rotation angle of the elliptical Gaussian PSF, in degrees. Only available when fitting a rotated elliptical Gaussian. Used by the “gaussian” render blur to orient each localization’s precision ellipse.	float
bg	The number of background photons per pixel, not including the camera offset.	float
lpx	The localization precision in x direction, in camera pixels.	float
lpy	The localization precision in y direction, in camera pixels.	float
ellipticity	The ellipticity of the fitted PSF, defined as (a - b) / a, where a and b are the larger and the smaller of “sx” and “sy”. Not saved for the spherical (isotropic) Gaussian, where it is always zero.	float
net_gradient	The net gradient of this spot which is defined by the sum of gradient vector magnitudes within the fitting box, projected to the spot center.	float
z	(Optional) The z coordinate fitted in 3D in nm. Please note the units are different for x and y coordinates.	float
lpz	(Optional) The localization precision in z direction in nm.	float
d_zcalib	(Optional) The value of the D function used for z fitting with astigmatism, see the supplement to Huang et al. 2008.	float
log_likelihood	(Optional) The log-likelihood of the fit. Only available for MLE fitting. Before v0.11.0, this column might be “likelihood”.	float
iterations	(Optional) The number of iterations of the fit procedure. Only available for MLE fitting.	long
chi_square	(Optional) The chi-square of the fit, i.e. the sum of squared residuals between the spot and the fitted model at the fit optimum, in photons squared. Only available for least-squares fitting, where it is the counterpart of the “log_likelihood” column of MLE fits.	float
group	(Optional) An identifier to assign multiple localizations to groups, for example by picking regions of interest or clustering.	long
group_input	“(Optional) Assigned after clustering if the input localizations had a “group” column. This allows to trace back which input group a clustered group originated from.”	long
len	(Optional) The length of the event in frames, if localizations from consecutive frames have been linked.	long
n	(Optional) The number of localizations in this event, if localizations from consecutive frames have been linked, potentially diverging from the “len” column due to a transient dark time tolerance.	long
photon_rate	(Optional) The mean number of photons per frame, if localizations from consecutive frames have been linked. The total number of photons is set in the “photons” column.	float
x_pick_rot	(Optional) Projection of localizations onto the axis of the rectangular pick in camera pixels. Only available after saving rectangular pick(s).	float
y_pick_rot	(Optional) Projection of localizations against the axis of the rectangular pick in camera pixels. Can be used to plot profile along the pick. Only available after saving rectangular pick(s).	float
photons_unc	(Optional) The uncertainty of the photons estimation as estimated by the Cramer-Rao Lower Bound of the Maximum Likelihood fit.	float
bg_unc	(Optional) The uncertainty of the background estimation as estimated by the Cramer-Rao Lower Bound of the Maximum Likelihood fit.	float
sx_unc	(Optional) The uncertainty of the sx estimation (camera pixels) as estimated by the Cramer-Rao Lower Bound of the Maximum Likelihood fit.	float
sy_unc	(Optional) The uncertainty of the sy estimation (camera pixels) as estimated by the Cramer-Rao Lower Bound of the Maximum Likelihood fit.	float
angle_unc	(Optional) The uncertainty of the angle estimation (degrees) as estimated by the Cramer-Rao Lower Bound of the Maximum Likelihood fit. Only available when fitting a rotated elliptical Gaussian with MLE.	float
n_id	(Optional) The index of the pick or of the input localization that this spot was extracted from, when fitting picked spots (identifications generated from picks or from a localization file).	unsigned long
photons_ch<c>	(Optional) The number of detected photons in channel c (c = 0, 1, …), for a multichannel spline fit with photon counts not linked across channels. The “photons” column holds their sum.	float
bg_ch<c>	(Optional) The number of background photons per pixel in channel c (c = 0, 1, …), for a multichannel spline fit with photon counts not linked across channels. The “bg” column holds their sum.	float
rel_photons_ch<c>	(Optional) The share of the total photons emitted in channel c (c = 0, 1, …), for a multichannel spline fit with photon counts not linked across channels. The values sum to 1 per localization and provide the continuous ratiometric readout used for color assignment.	float

The minimum required columns are: x, y, frame, lpx and lpy. For 3D data, the column z is also required. Since v0.9.5, Picasso supports the lpz column but it is not necessary for rendering (although recommended for accurate rendering in 3D).

Molecular maps (cluster centers) HDF5 Files

Molecular maps generated with RESI or by single-protein resolution imaging (i.e., generated by SMLM clusterer or G5M) can be opened in Picasso: Render just like localizations. The column names change slightly to reflect the different data type. Table 2 explains the main column names in molecular maps.

Table 2: Name, description and data type for the main columns used in molecular maps in Picasso.
Column Name	Description	C Data Type
frame	Mean frame of the localizations around the molecule/cluster center.	float
std_frame	St. dev. of frames of the localizations around the molecule.	float
x/y/z	Spatial coordinates of the molecule/cluster center (camera pixels).	float
std_x/std_y/std_z	St. dev. of the localizations around the molecule/cluster center in respective directions (camera pixels).	float
photons	Mean number of photons per localization around the molecule/cluster center.	float
sx	Mean Point Spread Function width/height of localizations around the molecule/cluster center (camera pixels).	float
bg	Mean background photons per pixel per localization around the molecule/cluster center.	float
lpx/lpy/lpz	Molecule’s/cluster center’s position uncertainty in respective directions (camera pixels).	float
ellipticity	Mean ellipticity of localizations around the molecule/cluster center.	float
net_gradient	Mean net gradient of localizations around the molecule/cluster center.	float
n/n_locs	Number of localizations assigned to the molecule/cluster center. “n” is the old convention for DBSCAN, HDBSCAN and SMLM clusterer.	unsigned long
n_events	Number of binding events assigned to the molecule/cluster center.	unsigned long
group	Cluster ID assigned to the molecule/cluster center.	unsigned long
group_input	(Optional) Previous group ID of the localizations around the molecule/cluster center, if they had a ‘group’ column.	unsigned long
area/volume	(Non-G5M) Area (2D) or volume (3D) of the ellipse/ellipsoid defined by the radius = 2 * std_x/y/z.	float
convexhull	(Non-G5M) Area (2D) or volume (3D) of the convex hull of the localizations assigned to the molecule/cluster center.	float
fitted_sigma	(Only G5M, 2D) Fitted sigma of the Gaussian component representing the molecule (camera pixels).	float
fitted_sigma_x/y/z	(Only G5M, 3D) Fitted sigma of the Gaussian component representing the molecule in respective directions (camera pixels).	float
rel_sigma	(Only G5M, 2D) ‘fitted_sigma’ divided by the average localization precision around the molecule.	float
rel_sigma_x/y/z	(Only G5M, 3D) ‘fitted_sigma_x/y/z’ divided by the average localization precision in respective directions around the molecule.	float
p_val	(Only G5M) P-value of the molecule being a true positive detection according to the G5M model.	float
mol_log_likelihood	(Only G5M) Log-likelihood of the molecule according to the G5M model.	float
group_log_likelihood	(Only G5M) Log-likelihood of the GMM fitted to the preclustered localizations around the molecule.	float

HDF5 Pick Property Files

When selecting File > Save pick properties in Picasso: Render, the properties of picked regions are stored in an HDF5 file. Within the HDF5 file, the data table is stored in the path /groups. Each row in the “groups” table corresponds to one picked region. For each localization property (see Table 1), two columns are generated in the groups table: the mean and standard deviation of the respective column over the localizations in a pick region. For example, if the localization table contains a column len, the “groups” table will contain a column len_mean and len_std.

Furthermore, the following columns are included:

group: the group identifier;
n_events: the number of binding events in the region;
n_units: the number of units from a qPAINT measurement;
len_cdf and dark_cdf: estimates of mean bright and dark times, respectively, obtained by fitting the distributions to the CDF of the exponential distribution. Units: frames;
locs: the number of localizations in the region;
len_mean and dark_mean: mean bright and dark times, respectively, obtained by averaging over all binding events, rather than fitting to the CDF. Units: frames;
len_std and dark_std: standard deviation of bright and dark times,respectively;

Metadata

Metadata describes a localization (or identification) dataset: the size of the field of view, the number of frames, the pixel size, the processing history, etc. In Picasso, metadata is represented internally as a list of dictionaries (info) where each step of analysis appends a new dictionary to the list.

Since v0.11, Picasso embeds this metadata directly inside the HDF5 file as a JSON string in the dataset /metadata. This makes the HDF5 file self-contained, so the metadata is preserved even if the file is moved or renamed without its accompanying YAML file.

For convenience and backward compatibility, the metadata is, by default, also written to a separate YAML file (see “YAML Metadata Files” below). Whether this YAML copy is written is controlled by the user setting Save metadata in .yaml in ~/.picasso/settings.yaml (default: True). Picasso settings are also available under Files > Picasso settings in any module. Set Save metadata in .yaml to False to save only the embedded /metadata dataset.

Movies acquired with MicroManager carry a large block of microscope properties, which Picasso reads from the movie (as Micro-Manager Metadata) and copies into the metadata of the localizations fitted from it. Set the user setting Save Micro-Manager metadata to false in ~/.picasso/settings.yaml to leave it out (default: true, i.e., the block is kept). This applies when localizing only - the block is dropped as the movie metadata is carried over into the localizations (and identifications/spots).

When loading metadata (picasso.io.load_info, used by load_locs), Picasso looks for the metadata in the following order:

The accompanying .yaml file (preferred, as it is easy to inspect and hand-edit);
The embedded /metadata dataset in the HDF5 file;
Otherwise, a NoMetadataFileError is raised.

YAML Metadata Files

YAML files are document-oriented text files that can be opened and changed with any text editor. In Picasso, YAML files are used to store metadata of movie or localization files. By default, each localization HDF5 file is accompanied by a YAML file of the same filename, except for the extension, which is .yaml. Since v0.11 the metadata is also embedded in the HDF5 file itself (see “Metadata” above), so deleting the YAML file no longer breaks loading as long as the HDF5 file contains the embedded /metadata dataset. For older Picasso files (or movie files such as .raw) that have no embedded metadata, deleting the YAML metadata file will result in an error.

The metadata file must contain the keys: Width, Height (size of the field of view in camera pixels), Frames (number of frames in the movie), and Pixelsize (effective camera pixel size after magnification in nm). Example files can be found here

Raw binary files (i.e., with extension .raw) may be accompanied by a YAML metadata file to store data about the movie dimensions, etc. While the metadata file, in this case, is not required, it reduces the effort of typing in this metadata each time the movie is loaded with Picasso: Localize. To generate such a YAML metadata file, load the raw movie into Picasso: Localize, then enter all required information in the appearing dialog. Check the checkbox Save info to yaml file and click ok. The movie will be loaded and the metadata saved in a YAML file. This file will be detected the next time this raw movie is loaded, and the metadata does not need to be entered again.