Update documentation
This commit is contained in:
parent
ce6e88a347
commit
98d2d92b49
GPG Key ID:
7A3F8997BFE894E0
|
|
@ -633,7 +633,7 @@ dependencies = [
|
|||
|
||||
[[package]]
|
||||
name = "plate-tool-lib"
|
||||
version = "0.4.0"
|
||||
version = "0.4.1"
|
||||
dependencies = [
|
||||
"csv",
|
||||
"getrandom",
|
||||
|
|
|
|||
218
README.md
218
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# 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
|
||||
- [Usage](#Usage)
|
||||
|
|
@ -14,126 +14,144 @@ you'll be greeted by a message informing you that no plates are selected.
|
|||
|
||||
To add a new plate, click the "New Plate" button:
|
||||
|
||||
Once you've added at least one source plate and one destination plate,
|
||||
click one of each to select them.
|
||||
The right-most pane will now display these plates.
|
||||
Once you've added at least one source plate and one destination plate,
|
||||
click one of each to select them.
|
||||
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).
|
||||
### 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.
|
||||
### 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.
|
||||
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.
|
||||
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.
|
||||
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
|
||||
If you already saved a transfer and would like to change it,
|
||||
click on its entry in the list.
|
||||
Now change the properties of the transfer as you did during initial creation.
|
||||
When finished, click the "Save" button to commit these changes.
|
||||
### Modifying and deleting transfers
|
||||
If you already saved a transfer and would like to change it,
|
||||
click on its entry in the list.
|
||||
Now change the properties of the transfer as you did during initial creation.
|
||||
When finished, click the "Save" button to commit these changes.
|
||||
|
||||
If you no longer need a transfer, select it as above and then click the "Delete" button.
|
||||
If you no longer need a transfer, select it as above and then click the "Delete" button.
|
||||
|
||||
### Importing and Exporting
|
||||
### Importing and Exporting
|
||||
|
||||
#### Export as CSV
|
||||
Exporting the transfers we have created to a CSV format is the primary (if not sole) usage of Plate Tool.
|
||||
To do so, first note the "File" tab at the top-left of the screen (above the list pane).
|
||||
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 reminded that this is a one-way export (see JSON export/import below),
|
||||
and then prompted by your browser to select a location for your file.
|
||||
#### Export as CSV
|
||||
Exporting the transfers we have created to a CSV format is the primary (if not sole) usage of Plate Tool.
|
||||
To do so, first note the "File" tab at the top-left of the screen (above the list pane).
|
||||
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.
|
||||
|
||||
#### 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)
|
||||
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.
|
||||
|
||||
#### 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).
|
||||
#### 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)
|
||||
|
||||
_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.
|
||||
#### 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 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).
|
||||
_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.
|
||||
|
||||
#### 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.
|
||||
_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).
|
||||
|
||||
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.
|
||||
#### 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.
|
||||
|
||||
_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.
|
||||
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
|
||||
|
||||
#### Taking Pictures of Plates
|
||||
If you double click on a plate
|
||||
(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
|
||||
and deposit it in your clipboard for you.
|
||||
You can then paste this into PowerPoint, GIMP, or whereever else
|
||||
you want a pretty picture of a plate.
|
||||
#### Taking Pictures of Plates
|
||||
If you double click on a plate
|
||||
(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
|
||||
and deposit it in your clipboard for you.
|
||||
You can then paste this into PowerPoint, GIMP, or whereever else
|
||||
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;
|
||||
it relies on your browser thinking that you have plate-tool open
|
||||
in a "secure context" (localhost or https).
|
||||
_NOTE:_ I won't guarantee this feature will work in all contexts;
|
||||
it relies on your browser thinking that you have plate-tool open
|
||||
in a "secure context" (localhost or https).
|
||||
|
||||
#### Turn off the in-transfer hashes
|
||||
Have you noticed that when you select a transfer, the wells to
|
||||
be used in that transfer have little diagonal lines over them?
|
||||
Hopefully you have, because this is supposed to happen!
|
||||
However, if you want to take a Pretty Plate Picture (see above),
|
||||
you might want these indicators turned off.
|
||||
#### Turn off the in-transfer hashes
|
||||
Have you noticed that when you select a transfer, the wells to
|
||||
be used in that transfer have little diagonal lines over them?
|
||||
Hopefully you have, because this is supposed to happen!
|
||||
However, if you want to take a Pretty Plate Picture (see above),
|
||||
you might want these indicators turned off.
|
||||
|
||||
To disable the indicators, mouse over "Options" (top-left of screen), then "Styles",
|
||||
then click "Toggle transfer hashes".
|
||||
To turn them back on, do the exact same thing.
|
||||
To disable the indicators, mouse over "Options" (top-left of screen), then "Styles",
|
||||
then click "Toggle transfer hashes".
|
||||
To turn them back on, do the exact same thing.
|
||||
|
||||
|
||||
## 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.
|
||||
However, you're absolutely welcome to host your own instance (even locally).
|
||||
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. Installing `rustup` is the easiest way to do this. See [their website](https://rustup.rs/),
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[package]
|
||||
name = "plate-tool-lib"
|
||||
version = "0.4.0"
|
||||
version = "0.4.1"
|
||||
edition = "2021"
|
||||
|
||||
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
|
||||
|
|
|
|||
Loading…
Reference in New Issue