TITLE: Planktoscope protocol for plankton imaging
AUTHORS: Lombard  Fabien

[DESCRIPTION]
this protocol is for using planktoscope and collect usable result for quantitative imaging of plankton
see also https://www.planktoscope.org/

[BEFORE_START]
-Test the protocol before acquisition of your first sample
-Calibrate your instruments to ensure coherent measures
-Create an Ecotaxa account and request the right to create project way before 
-Collect a plankton sample using a net

[GUIDELINES]
Planktoscope is an optical instrument. As it optical elements (camera, lenses, flowcell) are highly sensible to dust and dirt. we recommend that you never touch any of those component with fingers and store the planktoscope in a dust free and humidity free area (or in a box when not used)
complete manual of assembly and software could be found at https://planktonscope.readthedocs.io/en/latest/

[STEPS]
SECTION: Get your sample
4. Use a net to collect plankton
 

SECTION: Get your sample
4.1. Get the content of the collector. 
SECTION: Get your sample
4.2. 

Pass the volume through a 200µm sieve
 

  
  
SECTION: Get your sample
4.3. Rinse the sieve using seawater and a squeezing bottle (helps to pass small objects)
SECTION: Get your sample
4.4. Recover the fluid / measure its volume/ record it on logsheets (will be entered latter as "concentrated sample volume")
 
  
SECTION: first use and basic check
1.  Make sure the different lenses are in place (tube lens on the camera side is a 25mm/ objective lens on the light side is a 16mm one). Insert the Ibidi flowcell on the flowcell stage. Assemble the fluidic part 
  
  
  
 
  
SECTION: first use and basic check
1.2. wait a few minutes and you should see a wifi appearing with the name "planktoscope_baba...."
Connect to it  (password "copepode")
 

SECTION: first use and basic check
1.3. connect to the planktoscope using the following webpage
https://planktoscope.local:1880/ui
alternative url http://192.168.4.1:1880/ui
 
alternative url to debug (no camera return) http://192.168.4.1:1880/ui/
SECTION: first use and basic check
1.4. Check that your planktoscope is properly operating: on the optic configuration page:
- turn the light on/off (you should see the light and the camera overview turning white)
- check that adjusting the focus makes the focus motor turn
- check that the pump motor is functioning by pumping a little
- check that changing ISO/ white balance/ shutter speed leads to changes on the camera
   
SECTION: Calibration
2. Pump calibration: 
 

SECTION: Calibration
3. Size calibration:
 

SECTION: Calibration
2.1. -prepare a large volume of tap water and put in in the syringe targeting a total volume of e.g. 20ml
-on the optic configuration tab: tell him that you want to pass 10ml and record the exact volume it finally ends to pass (eg. by looking on the graduation of the syringe) note X= final volume passed for a 10ml instruction 
  
SECTION: Calibration
2.2. -then on the hardware setting, note the “pump step per ml” parameter (old step)
-calculate the "calibrated" pump step per ml such as = 10*old step/ X
-replace the “pump step per ml” parameter with this value  
SECTION: Calibration
3.1. - tilt the planktoscope on the side (camera on the bottom)  
SECTION: Calibration
3.2. - remove the flowcell and place a micro metric ruler (or a millimetric one) on the sample stage such as the ruler is either vertical or horizontal but not in diagonal (using the 20mm/16mm combo of lenses the camera field of view should be about 3mm by 4mm). Make the focus on the scale  
  
SECTION: Calibration
3.3. -take few images (select the test or culture mode)  
  
SECTION: Calibration
3.4. -download images on a computer and measure how much pixels are needed to obtain the longest path possible on the image (e.g. using imageJ https://imagej.nih.gov/ij/index.html) (see section 7 for communicating with your planktoscope and downloading the raw images)  
  
SECTION: Calibration
3.5. -calculate how much microns are represented by each pixels (should not be strongly different from 1.01 which is the default value for 25/16mm lenses combo)
SECTION: first use and basic check
1.6. Locate how to shut down the planktoscope (main Planktoscope page)   
SECTION: Pass the sample on planktoscope
5. assemble and start the planktoscope (see         )

SECTION: first use and basic check
1.1. power you planktoscope by connecting the different cables if the usb-c cable powering the planktoscope has a switch, put it on.
   
SECTION: Pass the sample on planktoscope
5.1. check for lenses alignment : remove the objective lens, start the light and check if the light source is centred. 
- if yes place back the objective lens and flowcell
- if no adjust the position of the tube lens to center the light source (magnets allows for 1-2mm adjustments)
  
   
   
 
  
SECTION: Pass the sample on planktoscope
5.2. Go to optic configuration.
turn the light on
verify focus on dry slide (tip, if the slide is slightly wet, you can check for the focus simultaneously on the water traces on the two sides of the flowcell)
Add your sample in the syringe (and keep it suspended by agitating it manually regularly or by gently inserting an air bubbler with 1 bubble/second in it)
pump until you see your sample passing by and flowing through the peristaltic pump
Eventually get rid of air bubble by pinching the tubing half way between the flowcell and the pump while pumping (see also 5.7).
finely adjust the focus on the organisms passing by (tip: start using the "1mm" buttons, then the 100µm buttons and finish by typing 25 or 50µm adjustments in the middle box (and pressing external arrows of focus)
 

SECTION: Pass the sample on planktoscope
5.4. Go to "sample" page and fill metadata

This step is critical because those data are the ones that will make your sample usable or not
-fill the sample identification (project, name, boat used, your name and the station number)
  
-note how you sampled the plankton (recording mesh size with "minimal fraction size" (will be used afterwards in the segmentation process, objects smaller than this won't be segmented; "Maximal fraction size" is the size of the mesh used in step   ; Filtered volume is important if you recorded it but could be calculated from other parameters . Make sure to either have filled it or to have filled either min and max depth if using a vertical net; initial/final positions, speed and length (min) of deployment if using a horizontal towed net

in all cases the diameter of the net opening will be needed to calculate the filtered volume

Dilution factor  if a dilution has been done in   
   
Fill the net initial and final position (if towed horizontally) remember to validate both of them (readings disappear after validation, but are recorded)
  
SECTION: Pass the sample on planktoscope
5.5. Go to fluidic acquisition and set parameters
-number of images to acquire (to be chosen depending on the desired final object number and the observed concentration on images)
 
  
SECTION: Pass the sample on planktoscope
5.6. go to optic configuration and pump with high flow rate a good amount of water (goal: remove plankton that have sunk in the fluidic system)
  
SECTION: Pass the sample on planktoscope
5.7. Go to fluidic acquisition and start the acquisition.
Wait for the acquisition to be done
Results can be consulted by consulting the gallery 
 
  
SECTION: Pass the sample on planktoscope
5.3. adjust the concentration of the sample: ideally not more than 20-30 objects should be present per frame. If the sample is over-concentrated, dilute it by a factor 2 (add in a jar 1/2 of the sample -after agitating it- and 1/2 of seawater). Note dilution xxx in metadata in 5.4
 


SECTION: Segment the acquisition
6. Go on segmentation and clic on the "update acquisition's folder list"
Select the samples you wish to segment 
Setup the different options of the segmenter

Recursive folder means that it will segment all samples within a selected sample
Ecotaxa archive: it will create a zip file containing all files needed for a easy importation within ecotaxa
Force rework: if yes it will re-segment samples already segmented
Keep objects: it will keep the final segmented images visible in the planktoscope (that could be accessed by the gallery in the objects folder)

  
scroll down and clic on start segmentation
Wait for the segmenter status to turn to "done"
  

SECTION: Download the results
7. You will need a computer connected to the planktoscope together with free software FileZilla (https://filezilla-project.org/)

Open FileZilla
Either clic on the top right to create a new connection or use the quick-connection fields below
 
Enter the following informations: 
Host: sftp://planktoscope.local  (192.168.4.1 should also works)
Username: pi
Password: copepode
Port: 22
  
clic on connect
on the bottom panels you have (on the left) the access to what is in your computer and (on the right) the access to what is in the planktoscope (clic and slide to transfer data in between both)
  
Exports file for EcoTaxa  are in /home/pi/data/export/ecotaxa
Raw images files are in /home/pi/data/img
Different control files to check the segmentation process (images after background substraction, masks of the different objects etc) are in /home/pi/data/clean
Final vignettes are in /home/pi/data/objects
SECTION: first use and basic check
1.5. adjust manually the white balance in order that it looks similar to the automatic white balance (AWB) this latter should be desactivated once you obtain correct results (it will continue to correct depending on the images and may lead to incorrect results)
SECTION: Clean the planktoscope
8. Drain the sample out of the syringe
Disconnect the syringe and clean it with tap water (or even distilled water)
Pump (at high speed!) the full content of the fluidic system to remove any liquid
Reconnect the syringe
Fill it with tap water (or distilled water)
Pump (at high speed!) while regularly pinch the tubing to detach any plankton in the system (see   )
Drain again the syringe (repeat steps 7.2-7.7 at least 2 more times until no plankton is visible on the camera)
Finally drain the system
SECTION: Upload your images on EcoTaxa
9. At First connection:
Create an account on EcoTaxa  (https://ecotaxa.obs-vlfr.fr/) by clicking on the top right "log in/register"
    
Put your real name and a valid mail so that you can be contacted
  
SECTION: How to use efficiently ecotaxa
10. Configure your project efficiently:  in Project/project settings

Select a data sharing license (we recommend one of the CC-BY one or CC-0 if you want data to have a future use for science)
Define if the project is visible for visitors (only "validated" images will be visible)
Add a preset list of taxa for manual sorting (could be copied from any other project, or taxa added manually): those will be present in the taxonomic filter (see 10.1)
Add useful sorting variables : in "Fields available for sorting": add at least those parameters that are pretty useful and will be added to the Quickfilters (see 10.1)
area=area
meanhue=meanhue
meansaturation=meansaturation
meanvalue=meanvalue
  
Define a person of contact (mandatory)
Define what pre-trained Deep Learning features to use on your project (we recommend to use «flowcam » unless we start to have some trained on planktoscope image  
And invite people to manage the project with you (will have the same rights than you), to help you to annotate images (won't have options below "export" in the project see   ), or just view the project (both validated and non validated)
  

SECTION: Maintenance of your planktoscope
11. Clean tubing and flowcell from inside
imaging plankton will lead to have a lot of organic material and seawater in the fluidic system. Some may clog or accumulates in some parts of the fluidic system.
Don't let it dry and try to get rid of it as soon as possible (if its occurs during sample acquisition, even abort this latter, take care of the clog, maybe dilute the sample    and restart acquisition while noting that the sample got diluted in the metadata   )
Pump tap or distilled water with high pumping rates  helps to unclog the system. make sure no plankton organisms remain in the fluidic system and especially on the internal walls of the flowcell. If it is the case don't hesitate to pinch (during 1-2 second) and release the tubing between the flowcell and the pump while pumping to create a sudden variation of pressure (e.g.   )
Over time, wet conditions and organic matter may create favorable condition for the growth of a bacterial film. The flowcell and tubing will look dirty from the inside. You can avoid this by pumping diluted bleach sometimes, let it act for 1-2 hours and carefully rinse the whole system   
Water, bacteria, and bleach together may favour the apparition of a calcium carbonate film inside the tubing and flowcell. It may either appear as dispersed cristals attached inside the flowcell or a white coating inside the tubing. To remove and clean this, pump some acidic solution (vinegar, citrus juice or other kind of other acids), let it rest for a few hours and rinse the system   

Clean flowcell outside:
The flowcell is an optical critical component, keeping it clean is an absolute necessity. Don't touch it with fingers or other kind of dirty material. If dirty:
if only dry dusts are present, gently blow the flowcell (ideally with dry gas dispenser at a large distance - dry gas dispenser are also creating thermal chocs if used from too close, test it on other material before) 
if dirt in not only dry dusts it could be cleaned with optical paper and ethanol. DO NOT USE CLASSICAL WIPING PAPER which are usually enriched in silica fibers for solidity ... and may create scratches on the flowcell. (disposable nose tissue are better alternative if optical paper is not available)


Clean optical lenses
as for the flowcell, optical lenses are critical elements of your planktoscope and should be kept as clean as possible. It starts by never touching them with fingers  (cleaning those would requires a lot of patience, efforts and may even lead to unexpected disappointments)
dry dust: dry gas (with even more caution than previously
others: only used optical paper

clean the camera sensor
... critical part if any, NEVER touch it, only use dry gas

regularly calibrate the pump   
SECTION: To go further
12. 
SECTION: Upload your images on EcoTaxa
9.1. Once logged you can consult the project on which you are registered (e.g. your own projects + the ones you have been invited by the different data owners) by clicking onto "contribute to a project" on the main page
  
SECTION: Upload your images on EcoTaxa
9.2. Needs to be done only once: basic rights don't include the "create project". As a protection against bots,  To create a new project and upload images in it, please contact the user manager(s):
PlQv (piqv@imev-mer.fr)
The rights to create projects will be activated (by a human, please be patient few days) soon and you will see the following right appearing 
    
SECTION: Upload your images on EcoTaxa
9.4. upload the ecotaxa archives (see step 6-7) on the EcoTaxa ftp
using Filezilla (see   ) create a connection  by using the following informations:
Select File > Site Manager...

Create a New Site called : Ecotaxa_VLFR
In General tag :
Host : plankton.obs-vlfr.fr
Protocol : FTP – File Transfer Protocol
Encryption : Only use plain FTP (insecure)
Logon Type : Normal
User : ftp_plankton
Password : Pl@nkt0n4Ecotaxa


Once this is done you could use FileZilla to load the Zip files downloaded from the Planktoscope onto the EcoTaxa ftp server (e.g. /Ecotaxa_Data_to_import/PLANKTONSCOPE)

 

SECTION: Upload your images on EcoTaxa
9.3. You can now create your own project on which you will be able to import, visualise and classify images  
SECTION: Upload your images on EcoTaxa
9.5. In your project/ on your project options button, select import images and metadata  
SECTION: Upload your images on EcoTaxa
9.6. locate your file on the ecotaxa ftp folders and import it (only works for one zip file at a time for now)  
SECTION: How to use efficiently ecotaxa
10.2. The different validation "states" in ecotaxa and how to validate

image arrives in EcoTaxa with the status "unclassified" (grey surrounding of the image)
   
However they could be also set as "predicted" (blue surrounding; classified automatically by taking as example one pre-existing project), "validated" (green surrounding; checked and annotated by a human), or dubious (orange surrounding; checked and annotated as dubious by a human)
 
-validating consist in selecting one or several picture and attributing them a taxonomic or morphological identity by either displacing them in the list of taxa present in the « taxonomic filter » tab (in which you can force some categories to be present by using the « preset » in the project settings… or just by typing the name using the keyboard (which should use right away the research on top of the  »taxonomic filter ». Whatever happens you need to save (ctrl.S or save button at the bottom of the page) before your action gets finally implemented.

photo here to illustrate
        

-validation could be tedious and requires large taxonomic expertise, however there are plenty of tools to help you! Filters are one of those tools, but the more interesting one is to use previous project to « predict » some taxonomic identity on your new images, in best cases you will face thousands of rightly predicted images and will be able to validate thousands per minutes!

 
SECTION: External links
13. Planktoscope website
https://www.planktoscope.org/

Planktoscope github
https://github.com/PlanktonPlanet/PlanktoScope

Planktoscope complete assembly guide and complete documentations
https://planktonscope.readthedocs.io/en/latest/

Planktoscope Slack channel (to exchange ideas/protocols/solutions)
https://forms.gle/qvh5jwuMvmyBKMQC7

Plankton Planet website
https://planktonplanet.org/

EcoTaxa tutorials:
https://sites.google.com/view/piqv/ecotaxa?authuser=0
https://www.youtube.com/watch?v=PSO6ZS765tk
https://www.youtube.com/watch?v=RaWUqIoKk0E
SECTION: How to use efficiently ecotaxa
10.1. Use filters wisely

there are three layers of filters in EcoTaxa: the quick access filters (top bar)
  
The taxonomic filter tab (allows to filter by taxonomic groups) and the other filter tabs
   

Filters are additive, so you can add filters on geography, date, who validated them, taxonomic group and every numeric fields/ text fields entered in ecotaxa to search for specific things (and you can get rid of them easily too, see grey fields on to of the next image)
 
quickfilters are pretty useful since you can sort objects by specific values (eg. mean saturation below) to quickly observe objects that have here lots of chlorophyll (ps. you can revert the sorting order of those filters by ascending or descending order)
   
SECTION: How to use efficiently ecotaxa
10.3. Do not hesitate to "predict" your project right away (even with a project/instrument that has nothing to do)

-How to do prediction (and help you to boost your validation ability) :
In the project (or "Filtered", in this case only the filtered vignettes would be used), select "Train and Predict classifications"
   
You can select any of the pre-existing project (including your own project) as a template for image recognition. By experience, using another project is only a first-aid, but won't replace prediction on images that you acquired with the same instrument/ same location / same plankton communities
Note that currently, only few "sorted" planktoscope projects exist (especially acquired with the same segmentation procedure than here), we therefore strongly encourage you after a first trial of prediction to quickly validate to re-predict on your own project.
what could be used for first prediction : 
#4605 - Planktoscope NOAA WCOA21 rita-net (coastal US West coast from Vancouver to San Diego; Processed with current segmenter; Partly validated; Contains lots of artefacts due to lens mis-alignment see 5.1)

#4356 - Planktoscope Tara Microbiomes P2/miniHSN : Lorient > Punta Arenas V3 (Trans-atlantic transect from France to Ushuaia; Processed with other segmenter (works only with adding Deep Learning features into play); Fully validated)
  
Push the  button "select project below then click me. You then have the possibility to select what types of object to consider. It is recommended to try to avoid selecting too much objects to partly correct the usual strong imbalance between categories (here as an example limited to 100 example per group) (If you use project #4605 as an example, please remove artefacts)
   
click on "continue to the classifier option screen ". Activate the pre-trained Deep Learning features (if not available see step 10). Inactivate variables that are not relevant for prediction and relate to position of the vignette in the initial images (bx, by, depth min/max, label, local centroid col/row, x, y)
  
Once done, images are now "predicted" (blue) but still wait for validation. Note that while classifying the different objects, the classifier also gives a classification "score" which determine if the label is attributed with high or low confidence. Using this score as a quick-filter is usually a good idea to be able to validate quickly well recognised images (and quickly start new predictions)

 

Doing repeated predictions on your own samples is better than doing some global one on random example project

Quickly validate objects to start to predict on your own plankton composition: the classifier is quite efficient and starts to give reasonable results starting from 30-50 images as example. Ecotaxa is then optimised to operate regular prediction rounds which could be heavily guided by the human (e.g. by doing prediction only on selections, stopping to predict some organisms etc). 

-once fully validated, export your results (lots of different solutions exist, the easiest to understand being the summary export with count per sample)
     
SECTION: Calibration
3.6. Enter the calibrated pixel size value in the hardware setting (note here that the comma should be replaced by point at every restart of the system)