fix: docs typos

Author: plasma-blue

.gitignore

@@ -73,3 +73,4 @@ docs/_build/
 
 test_data/
 notebooks
+data

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "mikan-rs"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "A medical image kit for segmentation metrics evaluation, native Rust support, and Python bindings for cross-language performance."

Cargo.toml

@@ -1,12 +1,12 @@
-# mikan-rs
+# mikan-rs 🍊
 
 A **m**edical **i**mage **k**it for segment**a**tion metrics evaluatio**n**, native Rust support, and Python bindings for cross-language performance.
 
 ## 🎨 Features
 
-- 🚀 **Blazingly Fast**: Written in Rust with high parallelization; speeds are 10-200x faster than medpy (depends on the number of cores in your CPU), especially for Hausdorff distance calculations.
+- 🚀 **Blazingly Fast**: Written in Rust with high parallelization; speeds are 10-100x faster than medpy (depends on the number of cores in your CPU), especially for Hausdorff distance calculations.
 
-- 🎯 **Simple**: The API is so intuitive that you can start using it immediately while reading the [documentation](examples/tutorial.ipynb) in just one minute!
+- 🎯 **Simple**: The API is so intuitive that you can start using it immediately while reading the [documentation](https://github.com/Plasma-Blue/mikan-rs/blob/master/examples/tutorial.ipynb) in just one minute!
 
 - 🧮 **Comprehensive Metrics**: Easily to compute almost all of segmentation metrics:
 
@@ -49,11 +49,22 @@ e = mikan.Evaluator(gt, pred)
 e.labels(1).metrics("dice")
 ```
 
-For details, please refer to the [python examples](examples/tutorial.ipynb) and [rust examples](examples/tutorial.rs).
+For details, please refer to the [python examples](https://github.com/Plasma-Blue/mikan-rs/blob/master/examples/tutorial.ipynb) and [rust examples](https://github.com/Plasma-Blue/mikan-rs/blob/master/examples/tutorial.rs).
+
+## 🎄 Related Projects
+
+- [medpy](https://github.com/loli/medpy): A well-known package for calculating segmentation metrics, with excellent documentation and implementation.
+- [miseval](https://github.com/frankkramer-lab/miseval): A framework capable of calculating a large number of segmentation metrics.
+- [seg_metrics](https://github.com/Jingnan-Jia/segmentation_metrics): A package for segmentation metrics that supports batch data calculation and CSV output, making it very convenient.
+- [MetricsReloaded](https://github.com/Project-MONAI/MetricsReloaded): A new recommendation framework for biomedical image analysis validation, published in Nature Methods.
+
+## 📃 Citation
+
+If you use this software, we would appreciate it if you could include an mikan emoji 🍊 in your paper.
 
 ## 🍚 Q&A
 
-Q: Why are my results different from seg_metrics/miseval/Metrics Reloaded?
+Q: Why are my results different from seg_metrics/miseval/MetricsReloaded?
 
 A: They are wrong. Of course, we might be wrong too. PRs to fix issues are welcome!
 

README.md

@@ -2,66 +2,174 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "id": "8ma4uIoIZjC1"
+   },
+   "source": [
+    "# benchmark: medpy vs. mikan-rs 🍊"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "L5D9-i91eYUY"
+   },
    "source": [
-    "## Benchmark"
+    "Please note that **Colab only provides dual-core CPUs**, so the speedup is limited. You can test on a server with more CPUs to observe mikan's blazingly fast performance."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 1,
-   "metadata": {},
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "y_qn133LaML8",
+    "outputId": "618ac8ca-5e1f-4519-ee9f-343ca1a64ccc"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Requirement already satisfied: SimpleITK in /usr/local/lib/python3.11/dist-packages (2.4.1)\n",
+      "Requirement already satisfied: medpy in /usr/local/lib/python3.11/dist-packages (0.5.2)\n",
+      "Requirement already satisfied: mikan-rs in /usr/local/lib/python3.11/dist-packages (0.1.2)\n",
+      "Requirement already satisfied: scipy>=1.10 in /usr/local/lib/python3.11/dist-packages (from medpy) (1.13.1)\n",
+      "Requirement already satisfied: numpy>=1.24 in /usr/local/lib/python3.11/dist-packages (from medpy) (1.26.4)\n"
+     ]
+    }
+   ],
+   "source": [
+    "!pip install SimpleITK medpy mikan-rs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 181
+    },
+    "id": "a_RYW5sPX6mY",
+    "outputId": "2a3fec85-5b1c-4b4b-82d7-d4cb961d7354"
+   },
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Downloading...\n",
+      "From: https://drive.google.com/uc?id=1R6rph1_Wc2HfLhzvGkcNt7hgbQiHWZBY\n",
+      "To: /content/patients_26_ground_truth.nii.gz\n",
+      "100%|██████████| 1.17M/1.17M [00:00<00:00, 70.3MB/s]\n",
+      "Downloading...\n",
+      "From: https://drive.google.com/uc?id=1cShgX96WgK_j4EbfR4wN2RLgcyVR4ca0\n",
+      "To: /content/patients_26_segmentation.nii.gz\n",
+      "100%|██████████| 5.05M/5.05M [00:00<00:00, 28.3MB/s]\n"
+     ]
+    },
+    {
+     "data": {
+      "application/vnd.google.colaboratory.intrinsic+json": {
+       "type": "string"
+      },
+      "text/plain": [
+       "'patients_26_segmentation.nii.gz'"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import gdown\n",
+    "\n",
+    "# We use datasets from seg_metrics\n",
+    "\n",
+    "gdth_url_id = \"1R6rph1_Wc2HfLhzvGkcNt7hgbQiHWZBY\"\n",
+    "pred_url_id = \"1cShgX96WgK_j4EbfR4wN2RLgcyVR4ca0\"\n",
+    "gdth_fpath = \"patients_26_ground_truth.nii.gz\"\n",
+    "pred_fpath = \"patients_26_segmentation.nii.gz\"\n",
+    "\n",
+    "gdown.download(id=gdth_url_id, output=gdth_fpath, quiet=False)\n",
+    "gdown.download(id=pred_url_id, output=pred_fpath, quiet=False)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "id": "cxVnoqqEYd6F"
+   },
    "outputs": [],
    "source": [
+    "import time\n",
     "import mikan\n",
     "import numpy as np\n",
     "import SimpleITK as sitk\n",
-    "import time\n",
     "from medpy.metric import dc, hd, hd95, assd"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "id": "Lmzfs9DaZyaD"
+   },
    "source": [
-    "## Load Data"
+    "## Load datas"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
+   "execution_count": 4,
+   "metadata": {
+    "id": "E3lZFPFNYiSK"
+   },
    "outputs": [],
    "source": [
-    "gt = sitk.ReadImage(rf\"..\\data\\patients_26_ground_truth.nii.gz\", sitk.sitkUInt8)\n",
-    "pred = sitk.ReadImage(rf\"..\\data\\patients_26_segmentation.nii.gz\", sitk.sitkUInt8)\n",
+    "gt = sitk.ReadImage(\"patients_26_ground_truth.nii.gz\", sitk.sitkUInt8)\n",
+    "pred = sitk.ReadImage(\"patients_26_segmentation.nii.gz\", sitk.sitkUInt8)\n",
     "\n",
     "gt_arr = sitk.GetArrayFromImage(gt)\n",
     "pred_arr = sitk.GetArrayFromImage(pred)\n",
     "\n",
     "# Downsample for faster\n",
-    "# If you're patient, you can comment out here and wait for the medpy to run for 30 minutes 😆\n",
+    "# If you're patient, you can comment out here and wait for medpy to run for 30 minutes 😆\n",
     "gt_arr = np.array(gt_arr[::2, ::2, ::2])\n",
-    "pred_arr =  np.array(pred_arr[::2, ::2, ::2])"
+    "pred_arr = np.array(pred_arr[::2, ::2, ::2])"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "id": "m9vGRSY8Z2v9"
+   },
    "source": [
-    "### DSC"
+    "## Dice"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
-   "metadata": {},
+   "execution_count": 8,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "nMxlyYl3YpDO",
+    "outputId": "c87b5310-88ba-4381-8115-13a7187c3af6"
+   },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "DSC: 15.09x faster\n"
+      "Mikan cost 0.12 s.\n",
+      "medpy costs 0.19 s.\n",
+      "DSC: 1.54x faster\n"
      ]
     }
    ],
@@ -71,35 +179,44 @@
     "evaluator = mikan.ArrayEvaluator(gt_arr, pred_arr, spacing=gt.GetSpacing())\n",
     "dsc = evaluator.labels([1,2,3,4,5]).metrics(\"dsc\")\n",
     "mikan_costs = time.time() - t\n",
+    "print(f\"Mikan cost {mikan_costs:.2f} s.\")\n",
     "\n",
     "# medpy: DSC\n",
     "t = time.time()\n",
     "for i in (1,2,3,4,5):\n",
     "    dsc = dc(pred_arr == i, gt_arr == i)\n",
     "medpy_costs = time.time() - t\n",
-    "\n",
+    "print(f\"medpy costs {time.time() - t:.2f} s.\")\n",
     "print(f\"DSC: {medpy_costs / mikan_costs :.2f}x faster\")\n"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "id": "YX0b4t2XZ4z8"
+   },
    "source": [
-    "### HD"
+    "## HD"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
-   "metadata": {},
+   "execution_count": 9,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "hrU3grdDdrCn",
+    "outputId": "bc289aa3-2001-4455-b7b6-2f6242640b7e"
+   },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Mikan has calculated Hausdorff distance and cost 0.78 s.\n",
+      "Mikan has calculated Hausdorff distance and cost 4.47 s.\n",
       "Let's waiting for medpy, be patient for a while...\n",
-      "HD: 68.78x faster\n"
+      "HD: 11.14x faster\n"
      ]
     }
    ],
@@ -123,25 +240,33 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "id": "vC0KgPIlZ6LU"
+   },
    "source": [
-    "### HD/HD95/ASSD"
+    "## All Distances"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
-   "metadata": {},
+   "execution_count": 10,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "3weKKOcMZeLC",
+    "outputId": "4c87051f-9d4c-4e79-a192-ae8a26ccb68a"
+   },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
       "{'1': {'hd': 3.8066790103912354, 'hd95': 0.7410011291503906, 'assd': 0.24823972582817078}, '2': {'hd': 5.875893592834473, 'hd95': 0.8939142823219299, 'assd': 0.30189621448516846}, '3': {'hd': 7.1895952224731445, 'hd95': 0.7410049438476562, 'assd': 0.29092279076576233}, '4': {'hd': 55.0378303527832, 'hd95': 0.7410011291503906, 'assd': 0.2536499500274658}, '5': {'hd': 46.238975524902344, 'hd95': 0.7410125732421875, 'assd': 0.27448806166648865}}\n",
-      "Mikan has calculated distance and cost 0.85 s.\n",
+      "Mikan has calculated distance and cost 3.80 s.\n",
       "Let's waiting for medpy, be patient for a while...\n",
       "{1: {'hd': 3.8066796490554484, 'hd95': 0.7409999966621399, 'assd': 0.24827345569665876}, 2: {'hd': 5.875891921349948, 'hd95': 0.893913303991663, 'assd': 0.3018870383121832}, 3: {'hd': 7.18959419428273, 'hd95': 0.7409999966621399, 'assd': 0.2909637348388582}, 4: {'hd': 55.03783156368531, 'hd95': 0.7409999966621399, 'assd': 0.25367831066385055}, 5: {'hd': 46.23897571237574, 'hd95': 0.7409999966621399, 'assd': 0.2745253765803193}}\n",
-      "Distances: 190.71x faster\n"
+      "Distances: 39.67x faster\n"
      ]
     }
    ],
@@ -174,24 +299,18 @@
   }
  ],
  "metadata": {
+  "colab": {
+   "provenance": []
+  },
   "kernelspec": {
    "display_name": "Python 3",
-   "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.3"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 0
 }

data/patients_26_ground_truth.nii.gz

@@ -12,7 +12,7 @@
     "\n",
     "Main features of mikan:\n",
     "\n",
-    "- Rust-driven, highly parallelized, and extremely fast, 10 to 50 times faster than existing tools (such as medpy)\n",
+    "- Rust-driven, highly parallelized, and extremely fast, 10 to 100 times faster than existing tools (such as medpy)\n",
     "- Supports the calculation of almost all segmentation metrics\n",
     "- Carefully designed simple, flexible, and intuitive interface, you can master mikan and fall in love with it in just one minute!\n"
    ]

data/patients_26_segmentation.nii.gz

@@ -11,7 +11,7 @@
     "mikan 是一个医学图像分割指标计算工具。此文档介绍了 mikan 的使用方法，简单对比了其与 medpy 的性能和结果。\n",
     "\n",
     "mikan 的主要特点：\n",
-    "- rust 驱动，高度并行化，非常快，比现有工具 (medpy 等) 快 10 ~ 50x\n",
+    "- rust 驱动，高度并行化，非常快，比现有工具 (medpy 等) 快 10 ~ 100x\n",
     "- 几乎支持全部的分割指标的计算\n",
     "- 精心设计的简单、灵活、符合直觉的接口，你一分钟就可以精通 mikan 并喜欢上它！"
    ]