OrgaMovie

This Fiji/ImageJ macro takes any number 4D (xyzt) image files and creates color-coded (for depth) time-lapse movies (see example below). It works on any filetypes that can be opened by your ImageJ installation. It is designed with microscopy movies of organoid nuclei in mind (hence the name), but can be used to depth code other 4D images.

Sample_Long_OrgaMovie.mp4

This macro is based on another macro previously created by Bas Ponsioen and René Overmeer, first published in Targeting mutant RAS in patient-derived colorectal cancer organoids by combinatorial drug screening, (eLife 2016;5:e18489 doi: 10.7554/eLife.18489).

How to install OrgaMovie

1. Download this repository by clicking on the link or on the green 'Code' button above and 'Download ZIP' and extract the zip file (or use git pull).

2. Start Fiji and go to Plugins>Install...
   

3. Select OrgaMovie_v3.ijm from the location you downloaded and unzipped to and save it into you .../fiji.app/plugins/Scripts/Image/Hyperstacks/ folder (or some other location you prefer)

4. Restart Fiji and it will show up in your Image>Hyperstacks menu (or whatever other location you chose)
   

External content required before you can run OrgaMovie

There is a bit of external content required which may or may not be present on your installation of Fiji. After installing any of these, you need to restart Fiji for it to actually work.

You can check which (if any) of these are already installed by hitting Ctrl+l or just l (= lowercase L) in Fiji to open the focus search bar and start typing the plugin/extension name. If it's installed, it will be listed in the Commands list on the left.

• There are a couple of color lookup tables (LUTs) that I find work well for the depth coding and maximum projection (see example movie above; these LUTS were originally developed for this paper). Although you can choose your favorite LUT in the settings, I have coded it in a way that it requires you to at least add the default ones to your LUT list. To add them:
  • You can copy them from your download location into your "...\Fiji.app\luts" folder.
  • If you can't find your Fiji location, just run the macro without doing this and it will open the folder for you. Don't forget to restart.
• There are 2 external plugins required for image registration (drift correction):
  • MultiStackReg can be downloaded from Brad Busse's website.
  • TurboReg can be downloaded from the EPFL's website or in Fiji by activating the BIG-EPFL update site (see here for an explanation on how to do this).
• The macro relies on a tiny bit of Python code for which it needs a plugin called Jython.jar. If this is not yet installed in your Fiji, it will automatically ask if you want to install it. Just click OK.

Remember that you will need to restart Fiji after installing any of these for it to work.

Running OrgaMovie

1. Put all the raw data you want to process into your input folder (images can be any size and any format that Fiji can handle).
2. Start Fiji and make sure you have no unsaved stuff open, as all images/results/ROIs/Logs/etc will be closed or overwritten without saving.
3. Select OrgaMovie_v3 from wherever you installed it (or create a shortcut for it).
4. Choose your settings (see below for explanation), hit OK.
   • If you have the macro recorder open, an error message might pop up at this point. You can safely ignore this error and the macro will run just fine, or you can close the recorder to avoid the error appearing.
5. Choose your input folder, hit Select.
6. Depending on the size of the files, the macro can take a while to run. At some stages it might seem like nothing is happening, but you can usually see whether it is still running by checking the log window (which states what is currently happening) and/or the status bar of Fiji (i.e. below the clickable icons). To get a better idea of whether it's stuck or not. Also consider turning on "Print progress duration" in the Settings to get more frequent updates of what is going on behind the scenes.
7. Your movies (and a log file) will be saved into a subfolder of your input folder called _OrgaMovies.
8. You know the macro has finished running when the last line in the log window states "Run finished".

OrgaMovie Settings

Your settings are recorded at the beginning of each experiment log, so you can always check/recreate the settings you used in any run.

Input/output settings

• Input filetype: write the extension of the filetype you want to use (so that all files in the input folder with a different extension are ignored).
• Input channel: set the channel to use in terms of channel order (so N^th channel).
  • Can be ignored if single-channel (i.e. single-color) data is used.
• Time interval: set the interval (in minutes) between consecutive frames. This is used for the time-stamp of the movie.
• Time-lapse epochs: in case you have used different time intervals throughout the time lapse, you can set the number of epochs (sequence with a certain time interval) here.
  • Example: you imaged overnight every 3 min intervals, then for 24h at 10 min intervals, then the last hour at 3 min intervals again. The number of epochs in this case is 3.
  • If epochs is set larger than 1, then another dialog will show after this one to set the details.
• Z-step: set the axial step size (in microns). This is used for the color-bar legend.
• Output format: choose whether output videos should be in between *.avi or *.tif or both.
  • TIFs are easier to use for downstream analysis in ImageJ but require significantly more diskspace than AVIs (~25-50x larger files).
• Save separate projections: if this is checked, then the depth and max projections are also saved as separate *.tifs without any legend, etc (for easy editing in Fiji)

Movie settings

• Frame rate: the frame rate of the output movie (for *.avi). Set how many seconds each frame stays in view when playing the movie.
• Apply drift correction: untick this if you do not want to correct for drift (or jitter) of your movies.
• Depth coding: select look up table (LUT) for depth coding.
• Projection LUT: select look up table (LUT) for the max projection.
• Pixel saturation: sets % of saturated pixels in output. Larger number gives brighter image with a larger proportion of saturated pixels.
• Min intensity factor: multiplication factor for background intensity. Larger number gives brighter image with more dim signals cut off.
• Crop boundary: the macro automatically detects the main signal region. This settings allows you to increase (in each direction) the cropped region surrounding this.
• Scalebar target width: select the ideal width of the scale bar in proportion to the image width. The true width of the scale bar will depend on a round number of microns that gives a scale bar of similar width to this target.

ImageJ settings

• Reduce RAM usage: the macro automatically detects how much RAM is available to Fiji and adjusts the maximum filesize based on this. This should work fine most of the time. Just in case you are having memory issues (or are using a lot of other heavy programs), tick this to halve the RAM used by this macro. If this is still too much, then either close some programs or adjust the memory available to ImageJ in the "Edit>Options>Memory & Threads..." menu. (If ImageJ exceeds the available memory, it usually (but not always) gives a warning that this is the case).
• Print progress duration: if checked, the log will output which process of the macro took how long. This can be useful when working with large files if you want to know whether the macro is stuck or not.
• Save these settings for next time: if checked, the current settings will be stored and automatically loaded next time you run the macro.
  • Remember that your previous settings will be stored in the log from that run so that you don't loose them.
• Load defaults: if checked, the default settings (as in image above) are reloaded. After hitting OK, the dialog window will re-appear and you can still make changes.
  • Note that this will override the 'save settings' from above.

Epoch Settings

• Time interval X: set the interval (in minutes) between consecutive frames for epoch X.
• Duration X: set the duration (in number of frames) of this epoch.
  • Take care to check exact number of frames used by the microscope as opposed to just calculating the number of frames based on the interval. For example, 18 hours at 3 minute intervals could either mean 360 frames (18 hours * 20 frames/hour) or 361 frames depending on your system.
  • You can set 0 if it is the last epoch of the series and it will use this interval until the end of the movie. (If the duration for any epoch is set to 0, other epochs down the list are ignored).