Big-FISH

Getting started

To avoid dependency conflicts, we recommend the use of a dedicated virtual or conda environment. In a terminal run the command:

$ conda create -n bigfish_env python=X.Y
$ source activate bigfish_env

With X.Y a valid Python version greater or equal than 3.6. Note that Big-FISH is tested only for Python 3.6, 3.7, 3.8 and 3.9.

We then recommend two options to install Big-FISH in your virtual environment: from PyPi or GitHub.

Download the package from PyPi

Use the package manager pip to install Big-FISH. In a terminal run the command:

$ pip install big-fish

Clone package from GitHub

Clone the project’s GitHub repository and install it manually with the following commands:

$ git clone git@github.com:fish-quant/big-fish.git
$ cd big-fish
$ pip install .

---

Examples

Several examples are available as Jupyter notebooks:

1. Read and write images.

2. Normalize and filter images.

3. Project in two dimensions.

4. Segment nuclei and cells.

5. Detect spots.

6. Extract cell level results.

7. Analyze coordinates.

To run these notebooks, you will need to clone the notebook repository:

$ git clone git@github.com:fish-quant/big-fish-examples.git

Activate your environment and install Big-FISH and Jupyter notebook dependencies inside:

$ source activate bigfish_env
$ cd big-fish-examples
$ pip install .

Then launch the notebooks:

$ jupyter notebook

You can also run these example online with mybinder. The remote server can take a bit of time to start.

---

API reference

Preprocessing

• I/O operations
  • Read files
    • read_image()
    • read_dv()
    • read_array()
    • read_uncompressed()
    • read_cell_extracted()
    • read_array_from_csv()
    • read_dataframe_from_csv()
  • Write files
    • save_image()
    • save_array()
    • save_cell_extracted()
    • save_data_to_csv()
• Image preparation
  • Normalize images
    • rescale()
    • compute_image_standardization()
  • Format images
    • resize_image()
    • get_marge_padding()
  • Cast images
    • cast_img_uint8()
    • cast_img_uint16()
    • cast_img_float32()
    • cast_img_float64()
  • Filter images
    • mean_filter()
    • median_filter()
    • gaussian_filter()
    • maximum_filter()
    • minimum_filter()
    • dilation_filter()
    • erosion_filter()
    • log_filter()
    • remove_background_mean()
    • remove_background_gaussian()
  • Project images in 2D
    • maximum_projection()
    • mean_projection()
    • median_projection()
  • Clean out-of-focus pixels
    • compute_focus()
    • in_focus_selection()
    • get_in_focus_indices()
    • focus_projection()
• Augmentation
  • augment_2d()
  • augment_2d_function()
  • augment_8_times()
  • augment_8_times_reversed()

---

Spot detection

• Automated spot detection
  • Detect spots
    • detect_spots()
    • local_maximum_detection()
    • spots_thresholding()
  • Find a threshold (automatically)
    • automated_threshold_setting()
    • get_breaking_point()
    • get_elbow_values()
  • Compute signal-to-noise ratio
    • compute_snr_spots()
• Dense regions decomposition
  • Decompose and simulate dense regions
    • decompose_dense()
    • get_dense_region()
    • simulate_gaussian_mixture()
  • Modelize a reference spot
    • build_reference_spot()
    • modelize_spot()
    • precompute_erf()
    • initialize_grid()
    • gaussian_2d()
    • gaussian_3d()
• Subpixel fitting
  • fit_subpixel()
• Cluster detection
  • detect_clusters()
• Colocalization
  • detect_spots_colocalization()
  • get_elbow_value_colocalized()

---

Segmentation

• Nucleus segmentation
  • Apply thresholding
    • thresholding()
  • Apply a Unet-based model (3-classes)
    • unet_3_classes_nuc()
    • apply_unet_3_classes()
    • from_3_classes_to_instances()
  • Remove segmented nuclei
    • remove_segmented_nuc()
• Cell segmentation
  • Apply watershed algorithm
    • cell_watershed()
    • get_watershed_relief()
    • apply_watershed()
  • Apply a Unet-based model (distance map)
    • unet_distance_edge_double()
    • apply_unet_distance_double()
    • from_distance_to_instances()
• Postprocessing
  • Label and clean instances
    • label_instances()
    • merge_labels()
    • clean_segmentation()
    • remove_disjoint()
  • Compute instance statistics
    • compute_mean_diameter()
    • compute_mean_convexity_ratio()
    • compute_surface_ratio()
    • count_instances()
  • Match cells and nuclei
    • match_nuc_cell()

---

Analysis

• Single-cell identification
  • Identify and remove transcription sites
    • remove_transcription_site()
    • identify_objects_in_region()
  • Define and export single-cell results
    • extract_cell()
    • extract_spots_from_frame()
    • summarize_extraction_results()
  • Manipulate surfaces, coordinates and boundaries
    • center_mask_coord()
    • from_boundaries_to_surface()
    • from_surface_to_boundaries()
    • from_binary_to_coord()
    • from_coord_to_frame()
    • from_coord_to_surface()
• Features engineering
  • Prepare input coordinates
    • prepare_extracted_data()
  • Compute features
    • compute_features()
    • get_features_name()
    • features_distance()
    • features_in_out_nucleus()
    • features_protrusion()
    • features_dispersion()
    • features_topography()
    • features_foci()
    • features_area()
    • features_centrosome()

---

Visualization

• Field of view plot
  • Plot images
    • plot_yx()
    • plot_images()
  • Plot quality measure of an image
    • plot_sharpness()
• Detection plot
  • plot_detection()
  • plot_reference_spot()
  • plot_elbow()
  • plot_elbow_colocalized()
• Segmentation plot
  • plot_segmentation()
  • plot_segmentation_boundary()
  • plot_segmentation_diff()
• Single-cell plot
  • plot_cell()
  • plot_cell_coordinates()

---

Utils

• Utility functions
  • Check input quality
    • check_array()
    • check_df()
    • check_parameter()
    • check_range_value()
  • Get constant values
    • get_margin_value()
    • get_eps_float32()
  • Load and check stored data
    • load_and_save_url()
    • check_hash()
    • compute_hash()
    • check_input_data()
  • Compute moving average
    • moving_average()
    • centered_moving_average()
  • Convert pixels and nanometers
    • convert_spot_coordinates()
    • get_object_radius_pixel()
    • get_object_radius_nm()
  • Extract a spot image
    • get_spot_volume()
    • get_spot_surface()
  • Format and save plots
    • save_plot()
    • get_minmax_values()
    • create_colormap()

---

Support

If you have any question relative to the package, please open an issue on Github.

---

Citation

If you exploit this package for your work, please cite:

Imbert A, Ouyang W, Safieddine A, Coleno E, Zimmer C, Bertrand E,
Walter T, Mueller F. FISH-quant v2: a scalable and modular tool for smFISH
image analysis. RNA (2022). doi: 10.1261/rna.079073.121.