# Ariadne
🌱 is a small software package for analyzing images of _Arabidopsis thaliana_ roots.
📷 It features a GUI for semi-automated image segmentation
<img src="assets/color-final.gif" width="250" height="250">
⏰ with support for time-series GIFs
<img src="assets/early-final.gif" width="250" height="250">
☠️ that creates dynamic 2D skeleton graphs of the root system architecture (RSA).
🔍 It's designed specifically to handle complex, messy, and highly-branched root systems well — the same situations in which current methods fail.
📊 It also includes some (very cool) algorithms for analyzing those skeletons, which were mostly developed by other (very cool) people<sup id="a1">[1](#f1)</sup><sup>,</sup><sup id="a2">[2](#f2)</sup>. The focus is on measuring cost-performance trade-offs and Pareto optimality in RSA networks.
⚠️ This is very much a work-in-progress! These are custom scripts written for an ongoing research project — so all code is provided as-is.
🔨 That said, if you're interested in tinkering with the code, enjoy! PRs are always welcome. And please reach out with any comments, ideas, suggestions, or feedback.
## Installation
Ariadne is installed as a Python package called `ariadne-roots`. We recommend using a package manager and creating an isolated environment for `ariadne-roots` and its dependencies. Our recommended package manager is Mamba. Follow the instructions to install [Miniforge3](https://github.com/conda-forge/miniforge).
You can find the latest version of `ariadne-roots` on the [Releases](https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne/releases) page.
### Step-by-Step Installation
1. **Create an isolated environment:**
```sh
mamba create --name ariadne python=3.11
```
2. **Activate your environment:**
```sh
mamba activate ariadne
```
3. **Install `ariadne-roots` using pip:**
```sh
pip install ariadne-roots
```
## Usage
1. **Activate your environment:**
```sh
mamba activate ariadne
```
2. **Open the GUI:**
```sh
ariadne-trace
```
### Trace with Ariadne
1. **Click on “Trace”** to trace roots.
2. The following window should open:
<img src="assets/Trace_Menu.png" width="450" height="450">
3. **Click on “Import image file”** and select the image to trace the roots.
4. **Trace the first root:**
- Start tracing the entire primary root first (it should appear green).
- To save time, place a dot on each region where a lateral root is emitted.
5. **Save the traced root:**
- When the first root is fully traced, click on the “Save” button on the left-hand menu of Ariadne or press “g” on your keyboard.
- A new window will pop up asking for the plant ID. For the first plant, enter “A”.
- Each time you click on “Save”, a .json file will be saved in the folder at the location of Location_1 (see above).
6. **Trace additional roots:**
- When you are done tracing the first root, click on the “Change root” button on the left-hand menu of Ariadne.
- Select a new plant ID, like “B”, to trace the second root.
- Continue tracing each root on your image following these steps.
7. **Finish tracing:**
- When you have traced all roots on your image, click on “Change root” and repeat from “Step 3” above for any new images.
### Analyze with Ariadne
1. **Organize your files:**
- Gather all the .json files stored at the location where Ariadne has been installed into a new folder named “OUTPUT_JSON” (referred to as “location_1” later on).
- Create a folder named “RESULTS” (referred to as “location_2”).
- Create a new folder named “Output”.
2. **Prepare for analysis:**
- Close Ariadne but keep the terminal open.
- Follow the instructions in step 2 above to set up the terminal.
3. **Run the analysis:**
- Click on “Analyze” in Ariadne.
<img src="assets/Welcome.png" width="400" height="250">
- Select the .json files to analyze from “location_1”.
- Then select “location_2” for the output.
- The software will analyze all the selected .json files.
### Results
- In the “location_3” folder, you will find:
- A graph for each root showing the Pareto optimality.
- A .csv file storing all the RSA traits for each root.
The RSA traits included in the CSV are
- **Material cost:** Total root length
- **Wiring cost:** Sum of the length from the hypocotyl to each root tip (Pareto related trait)
- **Alpha:** Trade-off value between growth and transport efficiency (Pareto related trait)
- **Scaling distance from the front:** Pareto optimality value (Pareto related trait)
- **Material cost (random):** Random total root length
- **Wiring cost (random):** Random sum of the length from the hypocotyl to each root tip (Pareto related trait)
- **Alpha (random):** Random trade-off value between growth and transport efficiency (Pareto related trait)
- **Scaling distance from the front (random):** Random Pareto optimality value (Pareto related trait)
- **Mean LR lengths:** Average length of all lateral roots
- **Median LR lengths:** Median length of all lateral roots
- **Mean LR angles:** Average lateral root set point angles
- **Median LR angles:** Median lateral root set point angles
- **Mean LR minimal distances:** Average Euclidean distance between each lateral root tip and its insertion on the primary root for all lateral roots
- **Median LR minimal distances:** Median Euclidean distance between each lateral root tip and its insertion on the primary root for all lateral roots
- **Sum LR minimal distances:** Sum of the Euclidean distances between each lateral root tip and its insertion on the primary root for all lateral roots
- **PR minimal length:** Euclidean distance from the hypocotyl to the primary root tip
- **PR length:** Length of the primary root
- **LR count:** Number of lateral roots
- **LR lengths:** Length of each individual lateral root
- **LR angles:** Lateral root set point angle of each individual lateral root
- **LR minimal distance:** Euclidean distance between each lateral root tip and its insertion on the primary root for each lateral root
- **LR density:** Number of lateral roots divided by primary root length, multiplied by 100
- **Total minimal distance:** Sum of LR minimal distances plus PR minimal length
- **Tortuosity (Material/Total Distance Ratio):** Total root length divided by total minimal distance
##### Keybinds
* `Left-click`: place/select node. To pan, hold `Alt` or `Ctrl` and drag
* `t`: toggle skeleton visibility (default: on)
* `e`: next frame (GIFs only)
* `q`: previous frame (GIFs only)
* `r`: toggle proximity override. By default, clicking on or near an existing node will select it. When this override is on, a new node will be placed instead. Useful for finer control in crowded areas (default: off)
* `i`: toggle insertion mode. By default, new nodes extend a branch (i.e., have a degree of 1). Alternatively, use insertion mode to intercalate a new node between 2 existing ones. Useful for handling emering lateral roots in regions you have already segmented (default: off)
* `g`: Save output file
* `d`: Delete currently selected node(s)
* `c`: Erase the current tree and ask for a new plant ID
* `Ctrl-Z`: Undo last action
## Contributing
Follow these steps to set up your development environment and start making contributions to the project.
1. **Navigate to the desired directory:**
Change directories to where you would like the repository to be downloaded:
```sh
cd /path/on/computer/for/repos
```
2. **Clone the repository:**
```sh
git clone https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne.git
```
3. **Navigate to the root of the cloned repository:**
```sh
cd Ariadne
```
4. **Create a development environment:**
This will install the necessary dependencies and the `ariadne-roots` package in editable mode:
```sh
mamba env create -f environment.yaml
```
5. **Activate the development environment:**
```sh
mamba activate ariadne_dev
```
6. **Create a branch for your changes:**
Before making any changes, create a new branch:
```sh
git checkout -b your-branch-name
```
## Contributors
- Kian Faizi
- Matt Platre
- Elizabeth Berrigan
## Contact
For any questions or further information, please contact:
- **Matt Platre:** [mattplatre@gmail.com](mailto:mattplatre@gmail.com)
## References
<b id="f1">1.</b> Chandrasekhar, Arjun, and Navlakha, Saket. "Neural arbors are Pareto optimal." _Proceedings of the Royal Society B_ 286.1902 (2019): 20182727. https://doi.org/10.1098/rspb.2018.2727 [↩](#a1)
<b id="f2">2.</b> Conn, Adam, et al. "High-resolution laser scanning reveals plant architectures that reflect universal network design principles." _Cell Systems_ 5.1 (2017): 53-62. https://doi.org/10.1016/j.cels.2017.06.017 [↩](#a2)
Raw data
{
"_id": null,
"home_page": null,
"name": "ariadne-roots",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ariadne, plants, roots, phenotyping, pareto",
"author": null,
"author_email": "Matthieu Platre <mattplatre@gmail.com>, Kian Faizi <kian@caltech.edu>, Elizabeth Berrigan <eberrigan@salk.edu>",
"download_url": null,
"platform": null,
"description": "# Ariadne\n\ud83c\udf31 is a small software package for analyzing images of _Arabidopsis thaliana_ roots.\n\n\ud83d\udcf7 It features a GUI for semi-automated image segmentation\n\n<img src=\"assets/color-final.gif\" width=\"250\" height=\"250\">\n\n\u23f0 with support for time-series GIFs\n\n<img src=\"assets/early-final.gif\" width=\"250\" height=\"250\">\n\n\u2620\ufe0f that creates dynamic 2D skeleton graphs of the root system architecture (RSA).\n\n\ud83d\udd0d It's designed specifically to handle complex, messy, and highly-branched root systems well \u2014 the same situations in which current methods fail.\n\n\ud83d\udcca It also includes some (very cool) algorithms for analyzing those skeletons, which were mostly developed by other (very cool) people<sup id=\"a1\">[1](#f1)</sup><sup>,</sup><sup id=\"a2\">[2](#f2)</sup>. The focus is on measuring cost-performance trade-offs and Pareto optimality in RSA networks.\n\n\u26a0\ufe0f This is very much a work-in-progress! These are custom scripts written for an ongoing research project \u2014 so all code is provided as-is.\n\n\ud83d\udd28 That said, if you're interested in tinkering with the code, enjoy! PRs are always welcome. And please reach out with any comments, ideas, suggestions, or feedback.\n\n## Installation\n\nAriadne is installed as a Python package called `ariadne-roots`. We recommend using a package manager and creating an isolated environment for `ariadne-roots` and its dependencies. Our recommended package manager is Mamba. Follow the instructions to install [Miniforge3](https://github.com/conda-forge/miniforge).\n\nYou can find the latest version of `ariadne-roots` on the [Releases](https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne/releases) page.\n\n### Step-by-Step Installation\n\n1. **Create an isolated environment:**\n ```sh\n mamba create --name ariadne python=3.11\n ```\n\n2. **Activate your environment:**\n ```sh\n mamba activate ariadne\n ```\n\n3. **Install `ariadne-roots` using pip:**\n ```sh\n pip install ariadne-roots\n ```\n\n## Usage\n\n1. **Activate your environment:**\n ```sh\n mamba activate ariadne\n ```\n\n2. **Open the GUI:**\n ```sh\n ariadne-trace\n ```\n\n\n### Trace with Ariadne\n\n1. **Click on \u201cTrace\u201d** to trace roots.\n2. The following window should open:\n\n <img src=\"assets/Trace_Menu.png\" width=\"450\" height=\"450\">\n\n3. **Click on \u201cImport image file\u201d** and select the image to trace the roots.\n4. **Trace the first root:**\n - Start tracing the entire primary root first (it should appear green).\n - To save time, place a dot on each region where a lateral root is emitted.\n5. **Save the traced root:**\n - When the first root is fully traced, click on the \u201cSave\u201d button on the left-hand menu of Ariadne or press \u201cg\u201d on your keyboard.\n - A new window will pop up asking for the plant ID. For the first plant, enter \u201cA\u201d.\n - Each time you click on \u201cSave\u201d, a .json file will be saved in the folder at the location of Location_1 (see above).\n6. **Trace additional roots:**\n - When you are done tracing the first root, click on the \u201cChange root\u201d button on the left-hand menu of Ariadne.\n - Select a new plant ID, like \u201cB\u201d, to trace the second root.\n - Continue tracing each root on your image following these steps.\n7. **Finish tracing:**\n - When you have traced all roots on your image, click on \u201cChange root\u201d and repeat from \u201cStep 3\u201d above for any new images.\n\n### Analyze with Ariadne\n\n1. **Organize your files:**\n - Gather all the .json files stored at the location where Ariadne has been installed into a new folder named \u201cOUTPUT_JSON\u201d (referred to as \u201clocation_1\u201d later on).\n - Create a folder named \u201cRESULTS\u201d (referred to as \u201clocation_2\u201d).\n - Create a new folder named \u201cOutput\u201d.\n2. **Prepare for analysis:**\n - Close Ariadne but keep the terminal open.\n - Follow the instructions in step 2 above to set up the terminal.\n3. **Run the analysis:**\n - Click on \u201cAnalyze\u201d in Ariadne.\n\n <img src=\"assets/Welcome.png\" width=\"400\" height=\"250\">\n\n - Select the .json files to analyze from \u201clocation_1\u201d.\n - Then select \u201clocation_2\u201d for the output.\n - The software will analyze all the selected .json files.\n\n### Results\n\n- In the \u201clocation_3\u201d folder, you will find:\n - A graph for each root showing the Pareto optimality.\n - A .csv file storing all the RSA traits for each root.\n\nThe RSA traits included in the CSV are\n\n- **Material cost:** Total root length\n- **Wiring cost:** Sum of the length from the hypocotyl to each root tip (Pareto related trait)\n- **Alpha:** Trade-off value between growth and transport efficiency (Pareto related trait)\n- **Scaling distance from the front:** Pareto optimality value (Pareto related trait)\n- **Material cost (random):** Random total root length\n- **Wiring cost (random):** Random sum of the length from the hypocotyl to each root tip (Pareto related trait)\n- **Alpha (random):** Random trade-off value between growth and transport efficiency (Pareto related trait)\n- **Scaling distance from the front (random):** Random Pareto optimality value (Pareto related trait)\n- **Mean LR lengths:** Average length of all lateral roots\n- **Median LR lengths:** Median length of all lateral roots\n- **Mean LR angles:** Average lateral root set point angles\n- **Median LR angles:** Median lateral root set point angles\n- **Mean LR minimal distances:** Average Euclidean distance between each lateral root tip and its insertion on the primary root for all lateral roots\n- **Median LR minimal distances:** Median Euclidean distance between each lateral root tip and its insertion on the primary root for all lateral roots\n- **Sum LR minimal distances:** Sum of the Euclidean distances between each lateral root tip and its insertion on the primary root for all lateral roots\n- **PR minimal length:** Euclidean distance from the hypocotyl to the primary root tip\n- **PR length:** Length of the primary root\n- **LR count:** Number of lateral roots\n- **LR lengths:** Length of each individual lateral root\n- **LR angles:** Lateral root set point angle of each individual lateral root\n- **LR minimal distance:** Euclidean distance between each lateral root tip and its insertion on the primary root for each lateral root\n- **LR density:** Number of lateral roots divided by primary root length, multiplied by 100\n- **Total minimal distance:** Sum of LR minimal distances plus PR minimal length\n- **Tortuosity (Material/Total Distance Ratio):** Total root length divided by total minimal distance\n\n\n\n##### Keybinds\n* `Left-click`: place/select node. To pan, hold `Alt` or `Ctrl` and drag\n* `t`: toggle skeleton visibility (default: on)\n* `e`: next frame (GIFs only)\n* `q`: previous frame (GIFs only)\n* `r`: toggle proximity override. By default, clicking on or near an existing node will select it. When this override is on, a new node will be placed instead. Useful for finer control in crowded areas (default: off)\n* `i`: toggle insertion mode. By default, new nodes extend a branch (i.e., have a degree of 1). Alternatively, use insertion mode to intercalate a new node between 2 existing ones. Useful for handling emering lateral roots in regions you have already segmented (default: off)\n* `g`: Save output file\n* `d`: Delete currently selected node(s)\n* `c`: Erase the current tree and ask for a new plant ID\n* `Ctrl-Z`: Undo last action\n\n\n## Contributing\nFollow these steps to set up your development environment and start making contributions to the project.\n\n1. **Navigate to the desired directory:**\n Change directories to where you would like the repository to be downloaded:\n ```sh\n cd /path/on/computer/for/repos\n ```\n\n2. **Clone the repository:**\n ```sh\n git clone https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne.git\n ```\n\n3. **Navigate to the root of the cloned repository:**\n ```sh\n cd Ariadne\n ```\n\n4. **Create a development environment:**\n This will install the necessary dependencies and the `ariadne-roots` package in editable mode:\n ```sh\n mamba env create -f environment.yaml\n ```\n\n5. **Activate the development environment:**\n ```sh\n mamba activate ariadne_dev\n ```\n\n6. **Create a branch for your changes:**\n Before making any changes, create a new branch:\n ```sh\n git checkout -b your-branch-name\n ```\n\n\n## Contributors\n\n- Kian Faizi\n- Matt Platre\n- Elizabeth Berrigan\n\n## Contact\n\nFor any questions or further information, please contact:\n\n- **Matt Platre:** [mattplatre@gmail.com](mailto:mattplatre@gmail.com)\n\n\n## References\n<b id=\"f1\">1.</b> Chandrasekhar, Arjun, and Navlakha, Saket. \"Neural arbors are Pareto optimal.\" _Proceedings of the Royal Society B_ 286.1902 (2019): 20182727. https://doi.org/10.1098/rspb.2018.2727 [\u21a9](#a1)\n\n<b id=\"f2\">2.</b> Conn, Adam, et al. \"High-resolution laser scanning reveals plant architectures that reflect universal network design principles.\" _Cell Systems_ 5.1 (2017): 53-62. https://doi.org/10.1016/j.cels.2017.06.017 [\u21a9](#a2)\n",
"bugtrack_url": null,
"license": null,
"summary": "Ariadne root tracing GUI and trait calculator.",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne",
"Issues": "https://github.com/Salk-Harnessing-Plants-Initiative/Ariadne/issues"
},
"split_keywords": [
"ariadne",
" plants",
" roots",
" phenotyping",
" pareto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c842ae6486cae5fa82810aabbb67dd0b60cebf2b5b9c932e3afd58725300c57f",
"md5": "e19d86b526b4fb6dc4e5b19d1491e968",
"sha256": "556bbf0708020f2f3018d2f223c911b002a3098ff28190c2fe61c8aee78840ce"
},
"downloads": -1,
"filename": "ariadne_roots-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e19d86b526b4fb6dc4e5b19d1491e968",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37307,
"upload_time": "2024-07-22T23:35:24",
"upload_time_iso_8601": "2024-07-22T23:35:24.160629Z",
"url": "https://files.pythonhosted.org/packages/c8/42/ae6486cae5fa82810aabbb67dd0b60cebf2b5b9c932e3afd58725300c57f/ariadne_roots-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-22 23:35:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Salk-Harnessing-Plants-Initiative",
"github_project": "Ariadne",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ariadne-roots"
}
JSON
