diff --git a/Cargo.lock b/Cargo.lock index c08a286..d4f2aee 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -633,7 +633,7 @@ dependencies = [ [[package]] name = "plate-tool-lib" -version = "0.4.0" +version = "0.4.1" dependencies = [ "csv", "getrandom", diff --git a/README.md b/README.md index adf02e4..687837d 100644 --- a/README.md +++ b/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) @@ -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. 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. - - ### 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. + +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 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. - - ### Importing and Exporting +### 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). - #### 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. +### 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. - #### 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) +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. - #### 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). +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. - _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). +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. - #### 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. +### 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. - 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. +If you no longer need a transfer, select it as above and then click the "Delete" button. + +### 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 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 - #### 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/), diff --git a/plate-tool-lib/Cargo.toml b/plate-tool-lib/Cargo.toml index 4b8b7af..4113486 100644 --- a/plate-tool-lib/Cargo.toml +++ b/plate-tool-lib/Cargo.toml @@ -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