gpseq_fromfish run

• Important parameters
• If segmentation was previously run
• Additional parameters
• Advanced parameters

The most basic way of running gpseq_fromfish, which uses the default values of all optional parameters, requires only three informations mentioned in the input page. An example:

gpseq_fromfish /home/ggirelli/dot_coordinates_table.tsv /home/ggirelli/dna_staining_folder/ /home/ggirelli/output_folder/

Run gpseq_fromfish with no parameters for a brief recap of all the options. Run it with -h for a detailed parameter help page, and with -H for a readable pipeline description.

usage: gpseq_fromfish [-h] [-H] [-a Z Y X] [-d sep] [-D npx]
                      [--dist-type {center_max,center_percentile,diffusion}]
                      [-t nthreads] [-m folder] [-M prefix] [-2 MAN2DDIR]
                      [-P axis_fraction] [-C channel [channel ...]]
                      [--inreg INREG] [--nbins NBINS] [-u] [-y] [-0]
                      [--labeled] [--compressed] [--dots-assignment-only]
                      [--dilate-Z] [--noplot] [--no-compart-plot] [--version]
                      dotCoords imdir outdir

"gpseq_fromfish" can be used to calculate radial position of FISH signals (dots)
in nuclei. Dots coordinates are expected to be 1-indexed. If 0-indexed, use the
'-0' flag. The image dimensions are expected to be: Z (slices), Y (columns) and
X (rows).

Images are expected to follow DOTTER filename notation: "channel_series.tif".
Identified images are first re-scaled (if deconvolved with Huygens software),
then a global (Otsu) and local (median) thresholds are combined to binarize the
image in 3D. Holes are filled in 3D and a closing operation is performed
to remove small objects. Objects are filtered based on volume and Z size, and
those touching the XY contour of the image are discarded. If the --labeled
option is used, the generated images have identified objects labeled with
different intensity values. Both compressed and normal TIFF files are
compatible as input/output. To produce compressed TIFF files as output use the
--compressed option.

If you previously segmented your images (i.e., produced masks), provide the path
to the folder containing the masks using -m, and the prefix for the mask name
with -M. For example, with '-m /ex/mask_dir/ -M mask_', in the case of the image
file '1.tif', the script will look for the mask at "/ex/mask_dir/mask_1.tif".
If the mask can be found, it will be used, otherwise it will be generated and
then saved. This can be used also to export masks as tifs to the folder
specified with -m.

If needed, 2D masks can be 'enforced' to the 3D masks. This is performed by
applying a logical AND operation between each slice of the 3D mask and the 2D
mask. To achieve this, use the -2 option, specifying the path to a folder
containing the 2D mask tiff files (filename should match input image). The
enforcing is performed during the segmentation process. Thus, if segmentation is
skipped (e.g., if a mask is provided as input with -m), this is skipped too.

The G1 selection is actually a selection of the most represented cell sub-
-population based on flatten area and integral of DNA stain intensity. In other
words, it will selected the most represented cell cycle phase in your cell
population (generally, G1). Basically, the major peak is identified and its FWHM
is used as a range for the filter on both nuclear features.

Then, each dot is assigned to the poles (2), bottom center (1) or top center (0)
compartments. The pole compartments are defined as the 25%% of the whole volume,
by cutting perpendicularly to the major axis. Such definition can be changed
with the -P (--pole) option specifying a different axis fraction. Information on
goodnes of fit is reported and a plot is provided with each nucleus rotated and
centered.

Also, each dot is assigned an `Allele` label: -1 to dots from cells with more
than 2 dots in that channel, 0 to dots from cells with less than 2 dots in that
channel, and in the case of cells with exactly 2 dots in that channel the most
peripheral dot is labeled with 1, and the most central with 2. This is useful
when expecting 2 dots per cell-channel, i.e., in the case of one probe per
channel in a diploid cell line.

Plotting can be turned off generally with the --noplot flag, and specifically
with the --no-compartment-plot flag.

More details can be found in the online documentation, at:
https://github.com/ggirelli/pygpseq/wiki/

Important parameters

• -a to specify the voxel sides in Z/Y/X order (space-separated). This parameter is critical for proper isotropic distance calculations in 3D.
• -D to specify of how many pixels to dilate the nuclear masks.
• -C to specify channels that should be disregarded during the analysis.
• --dist-type to specify how to calculate the lamina distance. center_percentile (default) to define the nuclear center as the 1% voxels with the highest distance from the nuclear lamina (mask border). center_max regards only the top voxel(s) as center. diffusion simulates enzyme diffusion (assuming and homogeneously dense nucleus) with an iterative anisotropic Gaussian blurring and uses the time at which the enzyme reaches a voxel as proxy for the "distance" from lamina.
• --dilate-Z to dilate the nuclear masks also over Z, instead of the default which is only over XY. The dilation is isotropic, i.e., it takes into account the voxel side aspect provided with -a to proportionally dilate over the different dimensions.
• Use the -0 flag if the coordinates in the input table are 0-indexed instead of 1-indexed (default).

If segmentation was previously run

• -m to provide the path to a folder with the previously generated masks. The masks are generated and saved to the provided folder if not found.
• -M for the prefix of the masks.
• -2 for a folder containing (manual) 2D segmented images, that are enforced on the automatic 3D segmentation. Use --labeled if the 2D segmented images are labeled.
• --labeled whether to generate/expect binary or labeled masks.
• --compressed whether to generate masks in compressed tiff format. The compressed format is not comaptible with FIJI, use tiffcu to un/compress them if needed.

Additional parameters

• -P for nuclear compartment analysis details. It defines the "pole" compartment as those voxels at the extremities of the major axis. Specifically, the user should provide the fraction of semi-axis the will belong to the pole.
• --nbins to specify the number of bins from lamina to center for the density profile generation.
• --dots-assignment-only to use the dilated mask only to assign dots to cells, and the non-dilated (original) mask for lamina distance calculations.

Advanced parameters

• -d to specify a different column separator for the input dot coordinates table. Defaults to tabulation.
• -t to parallelize over multiple threads.
• --inreg to change the regular expression used to identify tiff images.
• -y to skip the settings confirmation prompt and proceed with the analysis directly. This is especially useful when running a number of analyses from a batch script.

• -u to trigger debugging mode, which saves a number of intermediate results.

• --noplot to disble all plots.
• --no-compart-plot to disable plots related to the nuclear compartment analysis.