emilia
/
plate-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation

This commit is contained in:
Emilia Allison 2024-08-09 19:39:41 -04:00
parent ce6e88a347
commit 98d2d92b49
Signed by: emilia
GPG Key ID: 7A3F8997BFE894E0
3 changed files with 130 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.lock generated
View File

@ -633,7 +633,7 @@ dependencies = [
[[package]] [[package]]
name = "plate-tool-lib" name = "plate-tool-lib"
version = "0.4.0" version = "0.4.1"
dependencies = [ dependencies = [
"csv", "csv",
"getrandom", "getrandom",

238
README.md
View File

@ -1,6 +1,6 @@
# plate-tool # plate-tool
A web-based tool for creating assays for your favorite (acoustic) liquid handler. A web-based tool for creating and visualizing picklists for your favorite (possibly acoustic) liquid handler.
## Table of Contents ## Table of Contents
- [Usage](#Usage) - [Usage](#Usage)
@ -13,127 +13,145 @@ When you open plate tool for the first time,
you'll be greeted by a message informing you that no plates are selected. you'll be greeted by a message informing you that no plates are selected.
To add a new plate, click the "New Plate" button: To add a new plate, click the "New Plate" button:
Once you've added at least one source plate and one destination plate, Once you've added at least one source plate and one destination plate,
click one of each to select them. click one of each to select them.
The right-most pane will now display these plates. The right-most pane will now display these plates.
### Modifying and deleting plates
Suppose you erroneously created a plate, or misspelled its name.
Double click on that plate in the list (top-left pane) and a new modal will open.
Here you can rename a plate or delete it.
You may also change the format of a plate
(note that this will not delete any data if you accidentally switch to a smaller format).
### Adding a transfer
Now that you have two plates selected,
it's time to add a transfer.
We can see all of the properties of our transfer in the bottom-left pane.
You should first name your transfer (this name is only used for your reference, and is not passed to the liquid handler).
You can enter your source and destination regions in their respective fields;
the accepted format should be familiar—capital letters for the row and arabic numerals for the column.
However, it is much easier to click-and-drag the desired region.
If we click and hold on a well (see right pane), that specifies our start well.
Then, we can drag and subsequently release on our desired end well.
Our selected wells will be highlighted in light blue for our source plate and light red for our destination plate.
You might also notice that some wells are hatched:
this indicates wells that will be used in the transfer.
Not all selected wells will necessarily be hatched,
depending on the transfer type and interleave settings.
When all of the settings are to your liking, click the "Save" button.
Note that it now appears in the "Transfers" section of the list pane.
### Modifying and deleting transfers ### Modifying and deleting plates
If you already saved a transfer and would like to change it, Suppose you erroneously created a plate, or misspelled its name.
click on its entry in the list. Double click on that plate in the list (top-left pane) and a new modal will open.
Now change the properties of the transfer as you did during initial creation. Here you can rename a plate or delete it.
When finished, click the "Save" button to commit these changes. You may also change the format of a plate
(note that this will not delete any data if you accidentally switch to a smaller format).
If you no longer need a transfer, select it as above and then click the "Delete" button.
### Importing and Exporting
#### Export as CSV ### Adding a transfer
Exporting the transfers we have created to a CSV format is the primary (if not sole) usage of Plate Tool. Now that you have two plates selected,
To do so, first note the "File" tab at the top-left of the screen (above the list pane). it's time to add a transfer.
Mouse over this tab, and a few more options will be revealed. We can see all of the properties of our transfer in the bottom-left pane.
We want to export: mouse over export and select "Export as CSV". You should first name your transfer (this name is only used for your reference, and is not passed to the liquid handler).
You will be reminded that this is a one-way export (see JSON export/import below), You can enter your source and destination regions in their respective fields;
and then prompted by your browser to select a location for your file. the accepted format should be familiar—capital letters for the row and arabic numerals for the column.
#### Export as JSON (Saving Your Work) However, it is much easier to click-and-drag the desired region.
Currently, it is not possible to export to a format produced by other similar software. If we click and hold on a well (see right pane), that specifies our start well.
However, you might reasonably want to save a copy of your work Then, we can drag and subsequently release on our desired end well.
either as a backup or to share.
Mouse over the "File" tab, then "Export" as above, then alternatively select "Export as JSON".
Your browser will then prompt you to pick a suitable location to save your work as a file.
(See note 1 below)
#### Import from JSON (Recovering Your Work) Our selected wells will be highlighted in light blue for our source plate and light red for our destination plate.
If we want to import one such file, mouse over the "File" tab as before You might also notice that some wells are hatched:
and select "Import", and finally click "Import from JSON". this indicates wells that will be used in the transfer.
This opens a modal where you are prompted to upload (see note 2) Not all selected wells will necessarily be hatched,
your file; it will then be processed and loaded. depending on the transfer type and interleave settings.
Keep in mind that this will overwrite any work you currently have open,
so you may wish to export first (see above).
_Note 1_: JSON files are plaintext! When all of the settings are to your liking, click the "Save" button.
By default there is little whitespace (this makes comprehending them a challenge) Note that it now appears in the "Transfers" section of the list pane.
but if we pass it through a "JSON Beautifier" (enter this into your search engine of choice)
it immediately becomes more readable.
It is encouraged (although by no means necessary) to take a look at your export;
you will see that the representation here very closely mirrors the representation presented
in Plate Tool.
_Note 2_: Use of the word "upload" might imply that your data is leaving your computer.
It does not.
You are welcome to verify (use your browser's developer tools, it should have a network tab)
that this application does not "phone home".
Your data is stored locally (unless you choose to export it and distribute it yourself).
#### Import Transfer from CSV (Using a picklist as a transfer) ### Modifying and deleting transfers
If you have a CSV generated by another tool (or plate-tool), If you already saved a transfer and would like to change it,
you can import it as a single transfer. click on its entry in the list.
To do so, mouse over the "File" tab, then "Import", and finally "Import Transfer from CSV". Now change the properties of the transfer as you did during initial creation.
When creating transfers via this method, the transfer cannot be edited. When finished, click the "Save" button to commit these changes.
This is useful if you have a pre-existing picklist that you would like to visualize in plate-tool.
You may either manually map plates in a picklist to plates you've already created, or click "Auto" to: If you no longer need a transfer, select it as above and then click the "Delete" button.
1. Generate all plates in the picklist
2. Generate transfers for all source:destination pairs. ### Importing and Exporting
_Note_: If you try to use this feature and no plates are available to select, #### Export as CSV
there was likely an issue parsing your picklist. Exporting the transfers we have created to a CSV format is the primary (if not sole) usage of Plate Tool.
Your browser's console may have guidance as to why parsing failed; To do so, first note the "File" tab at the top-left of the screen (above the list pane).
plate-tool was probably expecting a different name for a column than was in your file. Mouse over this tab, and a few more options will be revealed.
We want to export: mouse over export and select "Export as CSV".
You will be prompted by your browser to select a location for your file.
As of version `0.4.0`, it is possible to pick a CSV export format:
Mouse over options, then export, then click "Change CSV export type".
In the dialog that opens, select your desired export type.
Currently, plate-tool supports:
- Normal
- This format can be imported by Cellario's cherrypick hook.
- Echo Client
- This format is useful if you want to run a picklist directly from the
Echo Client software.
This will export just the transfers between the currently selected plates;
I assume you'd be using this feature in a non-automation context
and know to load your plates into your Echo yourself.
#### Export as JSON (Saving Your Work)
Currently, it is not possible to export to a format produced by other similar software.
However, you might reasonably want to save a copy of your work
either as a backup or to share.
Mouse over the "File" tab, then "Export" as above, then alternatively select "Export as JSON".
Your browser will then prompt you to pick a suitable location to save your work as a file.
(See note 1 below)
#### Import from JSON (Recovering Your Work)
If we want to import one such file, mouse over the "File" tab as before
and select "Import", and finally click "Import from JSON".
This opens a modal where you are prompted to upload (see note 2)
your file; it will then be processed and loaded.
Keep in mind that this will overwrite any work you currently have open,
so you may wish to export first (see above).
_Note 1_: JSON files are plaintext!
By default there is little whitespace (this makes comprehending them a challenge)
but if we pass it through a "JSON Beautifier" (enter this into your search engine of choice)
it immediately becomes more readable.
It is encouraged (although by no means necessary) to take a look at your export;
you will see that the representation here very closely mirrors the representation presented
in Plate Tool.
_Note 2_: Use of the word "upload" might imply that your data is leaving your computer.
It does not.
You are welcome to verify (use your browser's developer tools, it should have a network tab)
that this application does not "phone home".
Your data is stored locally (unless you choose to export it and distribute it yourself).
#### Import Transfer from CSV (Using a picklist as a transfer)
If you have a CSV generated by another tool (or plate-tool),
you can import it as a single transfer.
To do so, mouse over the "File" tab, then "Import", and finally "Import Transfer from CSV".
When creating transfers via this method, the transfer cannot be edited.
This is useful if you have a pre-existing picklist that you would like to visualize in plate-tool.
You may either manually map plates in a picklist to plates you've already created, or click "Auto" to:
1. Generate all plates in the picklist
2. Generate transfers for all source:destination pairs.
_Note_: If you try to use this feature and no plates are available to select,
there was likely an issue parsing your picklist.
Your browser's console may have guidance as to why parsing failed;
plate-tool was probably expecting a different name for a column than was in your file.
_Note_: If you find a picklist that Cellario *can* import that plate-tool cannot,
please email me!
Odds are your picklist contains a weird edge case I've not considered,
and I would like to fix that!
### Other Neat Features ### Other Neat Features
#### Taking Pictures of Plates #### Taking Pictures of Plates
If you double click on a plate If you double click on a plate
(try to avoid clicking a well since that will change your selection) (try to avoid clicking a well since that will change your selection)
plate-tool will do some magic to take a screenshot of your plate plate-tool will do some magic to take a screenshot of your plate
and deposit it in your clipboard for you. and deposit it in your clipboard for you.
You can then paste this into PowerPoint, GIMP, or whereever else You can then paste this into PowerPoint, GIMP, or whereever else
you want a pretty picture of a plate. you want a pretty picture of a plate.
I hope this is helpful for arts and crafts.
_NOTE:_ I won't guarantee this feature will work in all contexts; _NOTE:_ I won't guarantee this feature will work in all contexts;
it relies on your browser thinking that you have plate-tool open it relies on your browser thinking that you have plate-tool open
in a "secure context" (localhost or https). in a "secure context" (localhost or https).
#### Turn off the in-transfer hashes #### Turn off the in-transfer hashes
Have you noticed that when you select a transfer, the wells to Have you noticed that when you select a transfer, the wells to
be used in that transfer have little diagonal lines over them? be used in that transfer have little diagonal lines over them?
Hopefully you have, because this is supposed to happen! Hopefully you have, because this is supposed to happen!
However, if you want to take a Pretty Plate Picture (see above), However, if you want to take a Pretty Plate Picture (see above),
you might want these indicators turned off. you might want these indicators turned off.
To disable the indicators, mouse over "Options" (top-left of screen), then "Styles", To disable the indicators, mouse over "Options" (top-left of screen), then "Styles",
then click "Toggle transfer hashes". then click "Toggle transfer hashes".
To turn them back on, do the exact same thing. To turn them back on, do the exact same thing.
## Installation ## Installation
@ -141,7 +159,7 @@ To add a new plate, click the "New Plate" button:
Plate tool is hosted [here](https://ilia.moe/cool-stuff/plate-tool/) for your convenience. Plate tool is hosted [here](https://ilia.moe/cool-stuff/plate-tool/) for your convenience.
However, you're absolutely welcome to host your own instance (even locally). However, you're absolutely welcome to host your own instance (even locally).
Here's how: Here's how:
(_Note:_ ~~If you run Windows you're probably best off doing the following in WSL2~~ You're absolutely fine to install rustup in Powershell, and the subsequent steps should be very similar but likely with different filepaths.) (_Note:_ If you run Windows you're absolutely fine to install rustup in Powershell, and the subsequent steps should be very similar but likely with different filepaths. I haven't personally validated this. )
1. Make sure you have a working Rust toolchain 1. Make sure you have a working Rust toolchain
1. Installing `rustup` is the easiest way to do this. See [their website](https://rustup.rs/), 1. Installing `rustup` is the easiest way to do this. See [their website](https://rustup.rs/),

2
plate-tool-lib/Cargo.toml
View File

@ -1,6 +1,6 @@
[package] [package]
name = "plate-tool-lib" name = "plate-tool-lib"
version = "0.4.0" version = "0.4.1"
edition = "2021" edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html