{ "cells": [ { "cell_type": "markdown", "id": "cbe8880f-58c4-4d1c-b695-a3229b3b2f38", "metadata": { "tags": [] }, "source": [ "# API pyClesperanto V.S. Prototype\n", "\n", "This is a basic exploration of the API differences between `pyclesperanto` and the `prototype`. This is a crude comparison based on function name and localisation in the package, but it can quickly help you find possible differences and help you convert from one to an other. \n", "\n", "We are trying to minimise the effort require to switch from the `prototype` to `pyclesperanto` using aliases and overloading of functions. Some function might be renamed, have their parameters changed, or not be available anymore. This document is here to quickly help you identify big differences between the two.\n", "\n", "We value community feedback and communications, if you are facing issue with a function renamed or missing, please reach out to us!" ] }, { "cell_type": "code", "execution_count": 1, "id": "0d976d35-2d0c-46ae-81d5-c051a1859d13", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "pyclesperanto (0.16.0) v.s. pyclespernato_prototype (0.24.4)\n" ] } ], "source": [ "import pyclesperanto as cle\n", "import pyclesperanto_prototype as clep\n", "\n", "print(f\"pyclesperanto ({cle.__version__}) v.s. pyclespernato_prototype ({clep.__version__})\")" ] }, { "cell_type": "code", "execution_count": 2, "id": "e90f3315-c782-4cd2-b338-91eabc27a22b", "metadata": {}, "outputs": [], "source": [ "modules = [\"_core\", \"_array\", \"_memory\", \"_functionalities\", \"_utils\", \"_operators\", \"_interroperability\"]\n", "core_cle = {func for module in modules for func in dir(getattr(cle, module, [])) if not func.startswith(\"_\") and not func[0].isupper()}\n", "core_clep = {func for func in dir(getattr(clep, \"_tier0\", [])) if not func.startswith(\"_\") and not func[0].isupper()}" ] }, { "cell_type": "markdown", "id": "56301d53-7f02-4582-b852-4964726009f6", "metadata": { "tags": [] }, "source": [ "## Core functions\n", "\n", "We call __core functions__, the various operations requiered for the library usage such like memory copy or device selection. Several function have disapeared due to the fact that all heavy GPU functionnality and management are now dealt with in the [C++ code](https://github.com/clEsperanto/CLIc) of clEsperanto." ] }, { "cell_type": "code", "execution_count": 3, "id": "f049c842-3e13-41ec-9f51-4aee89f4aa0e", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1mFunctions available in both pyclesperanto and prototype (14):\u001b[0m\n", " - asarray\n", " - available_device_names\n", " - cl_info\n", " - create\n", " - create_like\n", " - execute\n", " - get_device\n", " - operation\n", " - operations\n", " - pull\n", " - push\n", " - search_operation_names\n", " - select_device\n", " - set_wait_for_kernel_finish\n", "\n", "\u001b[1mFunctions available only in pyclesperanto (26):\u001b[0m\n", " - affine_transform\n", " - cl_buffer_datatype_dict\n", " - default_initialisation\n", " - empty\n", " - empty_like\n", " - from_array\n", " - get\n", " - getmembers\n", " - imshow\n", " - info\n", " - is_image\n", " - isfunction\n", " - label\n", " - list_available_backends\n", " - list_available_devices\n", " - native_execute\n", " - np\n", " - path\n", " - reshape\n", " - select_backend\n", " - set\n", " - to_device\n", " - wait_for_kernel_to_finish\n", " - warnings\n", " - zeros\n", " - zeros_like\n", "\n", "\u001b[1mFunctions available only in prototype (30):\u001b[0m\n", " - categories\n", " - create_2d_xy\n", " - create_2d_xz\n", " - create_2d_yx\n", " - create_2d_yz\n", " - create_2d_zx\n", " - create_2d_zy\n", " - create_binary_like\n", " - create_from_pointlist\n", " - create_image\n", " - create_labels_like\n", " - create_matrix_from_pointlists\n", " - create_none\n", " - create_pointlist_from_labelmap\n", " - create_square_matrix_from_labelmap\n", " - create_square_matrix_from_pointlist\n", " - create_square_matrix_from_two_labelmaps\n", " - create_vector_from_labelmap\n", " - create_vector_from_square_matrix\n", " - create_zyx\n", " - empty_image\n", " - empty_image_like\n", " - nparray\n", " - platform\n", " - plugin_function\n", " - pull_zyx\n", " - push_zyx\n", " - radius_to_kernel_size\n", " - set_device_scoring_key\n", " - sigma_to_kernel_size\n" ] } ], "source": [ "both = sorted(core_cle.intersection(core_clep))\n", "new = sorted(core_cle.difference(core_clep))\n", "old = sorted(core_clep.difference(core_cle))\n", "\n", "print(f\"\\033[1mFunctions available in both pyclesperanto and prototype ({len(both)}):\\033[0m\")\n", "for func in both:\n", " print(f\" - {func}\")\n", "print()\n", "print(f\"\\033[1mFunctions available only in pyclesperanto ({len(new)}):\\033[0m\")\n", "for func in new:\n", " print(f\" - {func}\")\n", "print()\n", "print(f\"\\033[1mFunctions available only in prototype ({len(old)}):\\033[0m\")\n", "for func in old:\n", " print(f\" - {func}\")" ] }, { "cell_type": "markdown", "id": "35965b6d-823a-49c1-805c-f04e7d902caf", "metadata": {}, "source": [ "## Tiers functions" ] }, { "cell_type": "code", "execution_count": 4, "id": "852d922e-a351-4c2a-bec6-3685ce349361", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1m- Functions in both prototype and pyclesperanto (218):\u001b[0m\n", " - absolute\n", " - absolute_difference\n", " - add_image_and_scalar\n", " - add_images\n", " - add_images_weighted\n", " - affine_transform\n", " - append\n", " - array_equal\n", " - binary_and\n", " - binary_edge_detection\n", " - binary_not\n", " - binary_or\n", " - binary_subtract\n", " - binary_xor\n", " - block_enumerate\n", " - bottom_hat_box\n", " - bottom_hat_sphere\n", " - bounding_box\n", " - center_of_mass\n", " - centroids_of_labels\n", " - clear\n", " - clip\n", " - closing_box\n", " - closing_labels\n", " - closing_sphere\n", " - combine_labels\n", " - convolve\n", " - copy\n", " - copy_horizontal_slice\n", " - copy_slice\n", " - copy_vertical_slice\n", " - count\n", " - count_touching_neighbors\n", " - crop\n", " - crop_border\n", " - cubic_root\n", " - degrees_to_radians\n", " - detect_label_edges\n", " - detect_maxima_box\n", " - detect_minima_box\n", " - difference_of_gaussian\n", " - dilate_box\n", " - dilate_labels\n", " - dilate_sphere\n", " - divide_by_gaussian_background\n", " - divide_images\n", " - divide_scalar_by_image\n", " - equal\n", " - equal_constant\n", " - erode_box\n", " - erode_connected_labels\n", " - erode_labels\n", " - erode_sphere\n", " - eroded_otsu_labeling\n", " - exclude_labels\n", " - exclude_labels_on_edges\n", " - exclude_labels_outside_size_range\n", " - exclude_labels_with_map_values_out_of_range\n", " - exclude_labels_with_map_values_within_range\n", " - exclude_large_labels\n", " - exclude_small_labels\n", " - exponential\n", " - extend\n", " - extend_labeling_via_voronoi\n", " - extension_ratio_map\n", " - flag_existing_labels\n", " - flip\n", " - gamma_correction\n", " - gauss_otsu_labeling\n", " - gaussian_blur\n", " - generate_binary_overlap_matrix\n", " - generate_distance_matrix\n", " - generate_touch_matrix\n", " - gradient_x\n", " - gradient_y\n", " - gradient_z\n", " - greater\n", " - greater_constant\n", " - greater_or_equal\n", " - greater_or_equal_constant\n", " - hessian_eigenvalues\n", " - histogram\n", " - index\n", " - insert\n", " - invert\n", " - jaccard_index\n", " - label_pixel_count_map\n", " - label_spots\n", " - labelled_spots_to_pointlist\n", " - laplace_box\n", " - laplace_diamond\n", " - large_hessian_eigenvalue\n", " - local_cross_correlation\n", " - logarithm\n", " - mask\n", " - mask_label\n", " - masked_voronoi_labeling\n", " - maximum_box\n", " - maximum_image_and_scalar\n", " - maximum_images\n", " - maximum_of_all_pixels\n", " - maximum_position\n", " - maximum_sphere\n", " - maximum_x_projection\n", " - maximum_y_projection\n", " - maximum_z_projection\n", " - mean_box\n", " - mean_intensity_map\n", " - mean_of_all_pixels\n", " - mean_sphere\n", " - mean_squared_error\n", " - mean_x_projection\n", " - mean_y_projection\n", " - mean_z_projection\n", " - median_box\n", " - median_sphere\n", " - minimum_box\n", " - minimum_image_and_scalar\n", " - minimum_images\n", " - minimum_of_all_pixels\n", " - minimum_of_masked_pixels\n", " - minimum_position\n", " - minimum_sphere\n", " - minimum_x_projection\n", " - minimum_y_projection\n", " - minimum_z_projection\n", " - mode_box\n", " - mode_sphere\n", " - modulo_images\n", " - multiply_image_and_scalar\n", " - multiply_images\n", " - multiply_matrix\n", " - nan_to_num\n", " - nonzero_maximum_box\n", " - nonzero_maximum_diamond\n", " - nonzero_minimum_box\n", " - nonzero_minimum_diamond\n", " - not_equal\n", " - not_equal_constant\n", " - onlyzero_overwrite_maximum_box\n", " - onlyzero_overwrite_maximum_diamond\n", " - opening_box\n", " - opening_labels\n", " - opening_sphere\n", " - paste\n", " - pixel_count_map\n", " - pop\n", " - power\n", " - power_images\n", " - radians_to_degrees\n", " - range\n", " - reciprocal\n", " - reduce_stack\n", " - relabel_sequential\n", " - remove\n", " - replace_intensities\n", " - replace_intensity\n", " - reverse\n", " - rigid_transform\n", " - rotate\n", " - scale\n", " - set\n", " - set_column\n", " - set_image_borders\n", " - set_nonzero_pixels_to_pixelindex\n", " - set_plane\n", " - set_ramp_x\n", " - set_ramp_y\n", " - set_ramp_z\n", " - set_row\n", " - set_where_x_equals_y\n", " - set_where_x_greater_than_y\n", " - set_where_x_smaller_than_y\n", " - sign\n", " - small_hessian_eigenvalue\n", " - smaller\n", " - smaller_constant\n", " - smaller_or_equal\n", " - smaller_or_equal_constant\n", " - smooth_labels\n", " - sobel\n", " - sort\n", " - spots_to_pointlist\n", " - square\n", " - square_root\n", " - squared_difference\n", " - standard_deviation_box\n", " - standard_deviation_sphere\n", " - statistics_of_background_and_labelled_pixels\n", " - statistics_of_labelled_pixels\n", " - sub_stack\n", " - subtract_gaussian_background\n", " - subtract_image_from_scalar\n", " - subtract_images\n", " - sum_of_all_pixels\n", " - sum_reduction_x\n", " - sum_x_projection\n", " - sum_y_projection\n", " - sum_z_projection\n", " - threshold_otsu\n", " - top_hat_box\n", " - top_hat_sphere\n", " - translate\n", " - transpose_xy\n", " - transpose_xz\n", " - transpose_yz\n", " - undefined_to_zero\n", " - variance_box\n", " - variance_sphere\n", " - voronoi_labeling\n", " - voronoi_otsu_labeling\n", " - write_values_to_positions\n", " - x_position_of_maximum_x_projection\n", " - x_position_of_minimum_x_projection\n", " - y_position_of_maximum_y_projection\n", " - y_position_of_minimum_y_projection\n", " - z_position_of_maximum_z_projection\n", " - z_position_of_minimum_z_projection\n", "\n", "\u001b[1m- Functions in pyclesperanto not in prototype (56):\u001b[0m\n", " - binary_closing\n", " - binary_dilate\n", " - binary_erode\n", " - binary_infsup\n", " - binary_opening\n", " - binary_supinf\n", " - bottom_hat\n", " - clic\n", " - closing\n", " - concatenate_along_x\n", " - concatenate_along_y\n", " - concatenate_along_z\n", " - connected_component_labeling\n", " - connected_components_labeling\n", " - detect_maxima\n", " - detect_minima\n", " - dilation\n", " - erosion\n", " - filter_label_by_size\n", " - grayscale_closing\n", " - grayscale_dilate\n", " - grayscale_erode\n", " - grayscale_opening\n", " - importlib\n", " - label_bounding_box\n", " - laplace\n", " - maximum_filter\n", " - mean_filter\n", " - median\n", " - minimum_filter\n", " - mode\n", " - morphological_chan_vese\n", " - multiply_image_and_position\n", " - nonzero_maximum\n", " - nonzero_minimum\n", " - np\n", " - onlyzero_overwrite_maximum\n", " - opening\n", " - plugin_function\n", " - read_values_from_positions\n", " - reduce_labels_to_centroids\n", " - reduce_labels_to_label_edges\n", " - remove_labels\n", " - remove_labels_on_edges\n", " - remove_labels_with_map_values_out_of_range\n", " - remove_labels_with_map_values_within_range\n", " - remove_large_labels\n", " - remove_small_labels\n", " - replace_value\n", " - replace_values\n", " - smooth_connected_labels\n", " - standard_deviation\n", " - std_z_projection\n", " - top_hat\n", " - variance_filter\n", " - warnings\n", "\n", "\u001b[1m- Functions in prototype not in pyclesperanto (204):\u001b[0m\n", " - apply_vector_field\n", " - arg_maximum_x_projection\n", " - arg_maximum_y_projection\n", " - arg_maximum_z_projection\n", " - arg_minimum_x_projection\n", " - arg_minimum_y_projection\n", " - arg_minimum_z_projection\n", " - array_equiv\n", " - artificial_objects_2d\n", " - artificial_tissue_2d\n", " - average_distance_of_n_closest_neighbors_map\n", " - average_distance_of_n_closest_points\n", " - average_distance_of_n_far_off_distances\n", " - average_distance_of_n_far_off_points\n", " - average_distance_of_n_nearest_distances\n", " - average_distance_of_n_nearest_neighbors_map\n", " - average_distance_of_n_shortest_distances\n", " - average_distance_of_touching_neighbors\n", " - average_distance_to_n_nearest_other_labels_map\n", " - average_neighbor_distance_map\n", " - binary_intersection\n", " - binary_union\n", " - cbrt\n", " - centroids_of_background_and_labels\n", " - close_index_gaps_in_label_map\n", " - combine_horizontally\n", " - combine_vertically\n", " - concatenate_stacks\n", " - connected_components_labeling_box\n", " - connected_components_labeling_diamond\n", " - deskew_x\n", " - deskew_y\n", " - dilate_box_slice_by_slice\n", " - dilate_sphere_slice_by_slice\n", " - distance_matrix_to_mesh\n", " - downsample_slice_by_slice_half_median\n", " - downsample_xy_by_half_median\n", " - draw_angle_mesh_between_touching_labels\n", " - draw_box\n", " - draw_distance_mesh_between_n_nearest_labels\n", " - draw_distance_mesh_between_proximal_labels\n", " - draw_distance_mesh_between_touching_labels\n", " - draw_line\n", " - draw_mesh_between_labels_with_touch_portion_in_range\n", " - draw_mesh_between_n_closest_labels\n", " - draw_mesh_between_n_most_touching_labels\n", " - draw_mesh_between_proximal_labels\n", " - draw_mesh_between_touching_labels\n", " - draw_sphere\n", " - draw_touch_portion_mesh_between_touching_labels\n", " - draw_touch_portion_ratio_mesh_between_touching_labels\n", " - erode_box_slice_by_slice\n", " - erode_sphere_slice_by_slice\n", " - euclidean_distance_from_label_centroid_map\n", " - exclude_labels_out_of_size_range\n", " - exclude_labels_with_average_values_out_of_range\n", " - exclude_labels_with_average_values_within_range\n", " - exclude_labels_with_map_values_equal_to_constant\n", " - exclude_labels_with_map_values_not_equal_to_constant\n", " - exclude_labels_with_values_equal_to_constant\n", " - exclude_labels_with_values_not_equal_to_constant\n", " - exclude_labels_with_values_out_of_range\n", " - exclude_labels_with_values_within_range\n", " - execute_separable_kernel\n", " - exp\n", " - extend_labels_with_maximum_radius\n", " - extended_depth_of_focus_variance_projection\n", " - fabs\n", " - fill_diagonal\n", " - fill_zeros_inpainting\n", " - flag_existing_intensities\n", " - generate_angle_matrix\n", " - generate_distal_neighbors_matrix\n", " - generate_maximum_intensity_between_points_matrix\n", " - generate_mean_intensity_between_points_matrix\n", " - generate_minimum_intensity_between_points_matrix\n", " - generate_n_most_touching_neighbors_matrix\n", " - generate_n_nearest_neighbors_matrix\n", " - generate_proximal_neighbors_matrix\n", " - generate_should_touch_matrix\n", " - generate_standard_deviation_intensity_between_points_matrix\n", " - generate_touch_count_matrix\n", " - generate_touch_mean_intensity_matrix\n", " - generate_touch_mean_intensity_within_range_matrix\n", " - generate_touch_portion_matrix\n", " - generate_touch_portion_within_range_neighbors_matrix\n", " - imread\n", " - imshow\n", " - is_matrix_symmetric\n", " - label\n", " - label_centroids_to_pointlist\n", " - label_maximum_extension_map\n", " - label_maximum_extension_ratio_map\n", " - label_maximum_intensity_map\n", " - label_mean_extension_map\n", " - label_mean_intensity_map\n", " - label_minimum_intensity_map\n", " - label_nonzero_pixel_count_map\n", " - label_nonzero_pixel_count_ratio_map\n", " - label_overlap_count_map\n", " - label_standard_deviation_intensity_map\n", " - label_to_mask\n", " - local_maximum_touching_neighbor_count_map\n", " - local_mean_touching_neighbor_count_map\n", " - local_median_touching_neighbor_count_map\n", " - local_minimum_touching_neighbor_count_map\n", " - local_standard_deviation_touching_neighbor_count_map\n", " - log\n", " - logical_and\n", " - logical_not\n", " - logical_or\n", " - logical_xor\n", " - map_array\n", " - maximum\n", " - maximum_distance_of_n_closest_points\n", " - maximum_distance_of_n_shortest_distances\n", " - maximum_distance_of_touching_neighbors\n", " - maximum_extension_map\n", " - maximum_intensity_map\n", " - maximum_of_distal_neighbors_map\n", " - maximum_of_n_most_touching_neighbors_map\n", " - maximum_of_n_nearest_neighbors_map\n", " - maximum_of_proximal_neighbors_map\n", " - maximum_of_touch_portion_within_range_neighbors_map\n", " - maximum_of_touching_neighbors\n", " - maximum_of_touching_neighbors_map\n", " - mean_extension_map\n", " - mean_of_distal_neighbors_map\n", " - mean_of_n_most_touching_neighbors_map\n", " - mean_of_n_nearest_neighbors_map\n", " - mean_of_proximal_neighbors_map\n", " - mean_of_touch_portion_within_range_neighbors_map\n", " - mean_of_touching_neighbors\n", " - mean_of_touching_neighbors_map\n", " - median_of_touching_neighbors\n", " - merge_annotated_touching_labels\n", " - merge_labels_according_to_touch_matrix\n", " - merge_labels_with_border_intensity_within_range\n", " - merge_touching_labels\n", " - minimum\n", " - minimum_distance_of_touching_neighbors\n", " - minimum_intensity_map\n", " - minimum_of_distal_neighbors_map\n", " - minimum_of_n_most_touching_neighbors_map\n", " - minimum_of_n_nearest_neighbors_map\n", " - minimum_of_proximal_neighbors_map\n", " - minimum_of_touch_portion_within_range_neighbors_map\n", " - minimum_of_touching_neighbors\n", " - minimum_of_touching_neighbors_map\n", " - mod\n", " - mode_of_distal_neighbors_map\n", " - mode_of_n_most_touching_neighbors_map\n", " - mode_of_n_nearest_neighbors_map\n", " - mode_of_proximal_neighbors_map\n", " - mode_of_touch_portion_within_range_neighbors_map\n", " - mode_of_touching_neighbors\n", " - mode_of_touching_neighbors_map\n", " - multiply_image_and_coordinate\n", " - n_closest_points\n", " - neighbors_of_neighbors\n", " - point_index_list_to_mesh\n", " - point_index_list_to_touch_matrix\n", " - pointlist_to_labelled_spots\n", " - prefix_in_x\n", " - proximal_neighbor_count\n", " - proximal_neighbor_count_map\n", " - proximal_other_labels_count\n", " - proximal_other_labels_count_map\n", " - push_regionprops\n", " - push_regionprops_column\n", " - read_intensities_from_map\n", " - read_intensities_from_positions\n", " - regionprops\n", " - remainder\n", " - resample\n", " - set_non_zero_pixels_to_pixel_index\n", " - sorensen_dice_coefficient\n", " - sqrt\n", " - standard_deviation_intensity_map\n", " - standard_deviation_of_distal_neighbors_map\n", " - standard_deviation_of_n_most_touching_neighbors_map\n", " - standard_deviation_of_n_nearest_neighbors_map\n", " - standard_deviation_of_proximal_neighbors_map\n", " - standard_deviation_of_touch_portion_within_range_neighbors_map\n", " - standard_deviation_of_touching_neighbors\n", " - standard_deviation_of_touching_neighbors_map\n", " - standard_deviation_z_projection\n", " - statistics_of_image\n", " - statistics_of_labelled_neighbors\n", " - stitch_horizontally_linear_blending\n", " - stitch_vertically_linear_blending\n", " - subtract_labels\n", " - symmetric_maximum_matrix\n", " - symmetric_mean_matrix\n", " - symmetric_minimum_matrix\n", " - symmetric_sum_matrix\n", " - threshold\n", " - touch_matrix_to_adjacency_matrix\n", " - touch_matrix_to_mesh\n", " - touch_portion_within_range_neighbor_count\n", " - touch_portion_within_range_neighbor_count_map\n", " - touching_neighbor_count_map\n", " - z_position_projection\n", " - z_position_range_projection\n" ] } ], "source": [ "def compare_tiers(module1, module2, module1_name, module2_name):\n", " tiers = [\"_tier1\", \"_tier2\", \"_tier3\", \"_tier4\", \"_tier5\", \"_tier6\", \"_tier7\", \"_tier8\", \"_tier9\"]\n", " module1_tier_funcs = {func for module in tiers for func in dir(getattr(module1, module, [])) if not func.startswith(\"_\") and not func[0].isupper()} \n", " module2_tier_funcs = {func for module in tiers for func in dir(getattr(module2, module, [])) if not func.startswith(\"_\") and not func[0].isupper()} \n", "\n", " shared_in_both = module1_tier_funcs.intersection(module2_tier_funcs)\n", " missing_in_module1 = module2_tier_funcs.difference(module1_tier_funcs)\n", " missing_in_module2 = module1_tier_funcs.difference(module2_tier_funcs)\n", " \n", " print(f\"\\033[1m- Functions in both {module2_name} and {module1_name} ({len(shared_in_both)}):\\033[0m\")\n", " for func in sorted(shared_in_both):\n", " print(f\" - {func}\")\n", " print() \n", " print(f\"\\033[1m- Functions in {module1_name} not in {module2_name} ({len(missing_in_module2)}):\\033[0m\")\n", " for func in sorted(missing_in_module2):\n", " print(f\" - {func}\")\n", " print()\n", " print(f\"\\033[1m- Functions in {module2_name} not in {module1_name} ({len(missing_in_module1)}):\\033[0m\")\n", " for func in sorted(missing_in_module1):\n", " print(f\" - {func}\")\n", "\n", "compare_tiers(cle, clep, \"pyclesperanto\", \"prototype\")" ] }, { "cell_type": "code", "execution_count": null, "id": "ceb0edf1", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "skbe", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.7" } }, "nbformat": 4, "nbformat_minor": 5 }