0.4.1 docs update (#59)

Lots of fixes and cleanup

.gitignore

@@ -1,3 +1,6 @@
 .DS_Store
 
+.vscode/*
+!.vscode/settings.json
+
 _build/**

docs/intro/formats.md

@@ -25,6 +25,8 @@ Both libraries have their own distinct advantages:
 
 Bio-Formats supports most images that can be read by OpenSlide, but not all - and therefore QuPath continues to include both libraries.
 
+However, file formats are tricky and tend to have lots of variants. Just because a format is listed as being supported by Bio-Formats or OpenSlide doesn't mean files in that format will always open (properly) in QuPath. The following sections contain some extra details and caveats, partly based on user feedback about what does and doesn't work.
+
 :::{important}
 If you're using a QuPath build for **Apple silicon** (i.e. a recent Mac with M1/M2 processor), then you might not have OpenSlide available by default.
 Check out <https://github.com/petebankhead/homebrew-qupath> for instructions how to install this.

docs/intro/versions.md

@@ -60,21 +60,6 @@ In return, **you can help** in a few ways:
 - Please report bugs and weirdness that you find on the [forum] -- *after* checking [GitHub Issues] to see if it has already been reported or fixed. If you find the issue already exists, but hasn't been resolved, feel free to join in the discussion.
 - Do keep in mind that QuPath is developed by researchers, and our time is very limited. If you want a grand new feature, we probably can't spend weeks developing it for you for free... even if we want to. But we're open to discussing ways to collaborate. Talk to us -- the earlier the better.
 
-:::{admonition} What was with all the milestone versions?
-A lot happened between v0.1.2 and v0.2.0.
-This included a year without any QuPath development at all, while the creator of the software moved jobs twice and country once.
-
-As QuPath's open source development restarted, big chunks of it were entirely rewritten.
-*Milestone* releases were made along the way to enable enthusiastic (brave) users to try things out and give feedback.
-These can be thought of as work-in-progress preview versions, which are identifiable with names like v0.2.0-m2.
-In the end, there were 12 milestones... considerably more than had been originally anticipated.
-
-One memorable characteristic of those times is that *so much* was being rewritten that things tended to break between milestones.
-It was all rather disruptive, although the user feedback was invaluable in shaping the software and giving a more solid basis for the future.
-
-Having got through that period, the release schedule outlined above is intended to avoid a return to the dark days of many milestones -- making things more structured and predictable for users and developers alike.
-:::
-
 [changelog]: https://github.com/qupath/qupath/blob/master/CHANGELOG.md
 [forum]: http://forum.image.sc/tag/qupath
 [github issues]: http://forum.image.sc/tag/qupath

docs/reference/shortcuts.md

@@ -34,7 +34,7 @@ These shortcuts only work whenever the viewer is 'in focus', i.e. it is the last
 ```
 
 :::{sidebar} Note for Linux users
-Replace {kbd}`Alt` with {kbd}`Alt + Super` (thanks to [Philipp Tschandl for this](https://groups.google.com/d/msg/qupath-users/QB03tHjRrZs/od-nL_9SBQAJ)).
+You may need to replace {kbd}Alt with {kbd}Alt + Super.
 :::
 
 ### The {kbd}`Alt` key

docs/starting/essential_tips.md

@@ -27,13 +27,13 @@ You can then run the command in one of two ways:
 1. Using the mouse, by double-clicking
 2. Use the keyboard, selecting the command with the arrow keys before pressing {kbd}`Enter`
 
-Starting with v0.2.0, the *Command List* also includes a brief help text description for most commands.
+The *Command List* also now includes a brief help text description for most commands.
 
 :::{tip}
 If you find yourself wanting to run the same command repeatedly, uncheck the {guilabel}`Auto close` box to keep the command list open.
 :::
 
-:::{figure} images/command_list.jpg
+:::{figure} images/tips_command.jpg
 :align: center
 :class: shadow-image
 

docs/starting/first_steps.md

@@ -4,6 +4,7 @@
 The following tutorial will guide you through your first steps with QuPath, and introduce you to the main features, buttons and concepts you need to get started.
 You will see how to:
 
+- QuPath Welcome window
 - Open a whole slide image
 - View image properties
 - Navigate around images
@@ -19,6 +20,23 @@ You will see how to:
 If you do not have a whole slide image handy, see {doc}`here <../intro/acknowledgements>` for examples.
 :::
 
+### Running QuPath
+Running QuPath for the first time will present you with the welcome window. This contains useful links should you have an issue or want to learn more. 
+
+For those that like working on software in dark mode (or want to use their own creative themes) it's possible to change that here. Additionally updates to QuPath or extensions can be checked for ensuring you have access to the latest features. 
+
+:::{figure} images/steps_welcome.jpg
+:align: center
+:class: shadow-image
+:width: 75%
+
+QuPath welcome window.
+:::
+
+:::{Tip}
+Should you no longer want to see this pop-up, it can be de-selected at the lower right corner and will remain hidden until reactivated in settings under {menuselection}`Edit --> Preferences --> general --> Show welcome message when QuPath starts`.
+:::
+
 ### Opening an image
 
 You can open an image with {menuselection}`File --> Open...`, but that quickly becomes tiresome.
@@ -34,6 +52,28 @@ This works for most other file types that QuPath can handle - not only images.
 A whole slide image (*CMU-1.svs*) opened within QuPath.
 :::
 
+### Setting the image type
+
+One of the most important properties is the **Image type**, which can impact the behavior of some QuPath commands. When opening an image in QuPath you will be presented with a window allowing you to choose the image type. To find out more about what this means, check out the {guilabel}`Show details` section. 
+You should choose the closest match for the image, e.g. *Brightfield*, *Fluorescence*.
+
+:::{figure} images/steps_image_type.jpg
+:align: center
+:class: shadow-image
+:width: 75%
+
+Option window for setting the image type in QuPath.
+:::
+
+:::{important}
+QuPath can automatically estimate the image type for you, if you choose this option for *Set image type* under {menuselection}`Edit --> Preferences...` {{ icon_cog }}.
+However, sometimes the automatic estimate is wrong - so it's important to be aware of this, and to know how you can fix the estimate if needed.
+:::
+
+:::{tip}
+Should you need to change the image type later, it's possible to do so in the **Image** tab within the **Analysis panel** mentioned below by double clicking on the image type that is currently set.
+:::
+
 ### Seeing the image properties
 
 Usually, there's a panel on the left of the QuPath window: the **Analysis panel**.
@@ -42,15 +82,12 @@ If not, click the **Analysis panel** button on the toolbar to open it {{ icon_me
 There are a few tabs here that you will meet later.
 For now, click the **Image** tab to get a table of properties related to your image.
 
-### Setting the image type
-
-One of the most important properties is the **Image type**, which can impact the behavior of some QuPath commands.
-You should choose the closest match for the image, e.g. *Brightfield*, *Fluorescence*.
-You can also double-click the entry in the table to set it from a drop-down menu.
+:::{figure} images/steps_image_tab.jpg
+:align: center
+:class: shadow-image
+:width: 75%
 
-:::{important}
-QuPath can automatically estimate the image type for you, if you choose this option for *Set image type* in under {menuselection}`Edit --> Preferences...` {{ icon_cog }}.
-However, in case the estimate is wrong you should be aware the option exists - and should always be checked.
+Image tab showing the image properties in QuPath.
 :::
 
 ### Setting the pixel size
@@ -76,16 +113,16 @@ To **zoom in and out** of an image within QuPath, use the **scroll wheel** of yo
 You can also jump to a specific magnification if you:
 
 - *Right-click* on the image, and choose one of the zoom options e.g. {menuselection}`Display --> 100%`, or
-- *Double-click* on the little magnification box on the toolbar, and enter a value there.
+- *Double-click* on the little magnification value on the toolbar, and enter a value there.
 
 :::{figure} images/steps_mag.jpg
 :align: center
 :class: shadow-image
 
-The *Magnification box*
+The *Magnification box*.
 :::
 
-Double-clicking on the magnification box on the toolbar (here, the bit that shows 10.0x) opens an input dialog to enter a specific magnification.
+Double-clicking on the magnification value in the toolbar (here, the bit that shows 10.0x) opens an input dialog to enter a specific magnification.
 
 ### Panning
 
@@ -140,9 +177,9 @@ Most of QuPath's drawing tools work similarly (i.e. select the tool, click on th
 Double-click to set the final point.
 
 :::{note}
-By default, QuPath will switch back to the **Move tool** {{ icon_move }} after you've drawn an annotation with any tool except the **Brush**.
+By default, QuPath will switch back to the **Move tool** {{ icon_move }} after you've drawn an annotation with any tool except the **Brush**.  
 This is to avoid accidentally drawing new annotations when you really just wanted to move around in the image or do something with an existing annotation.
-The **Brush** is different, because it's commonly used to paint or edit multiple regions at a time, and it can be annoying to have to switch it back on regularly.
+The **Brush** is different, because it's commonly used to paint or edit multiple regions at a time, and it can be annoying to have to switch it back on regularly. 
 
 If you don't like the default behavior, it can be changed with the *Return to Move Tool automatically* option in the **Preferences** {{ icon_cog }}.
 

docs/starting/help.md

@@ -6,18 +6,21 @@ Here are the main sources of help with QuPath questions:
 - The {doc}`Command List <essential_tips>` & its built-in help
 - [forum.image.sc](https://forum.image.sc/tags/qupath) - **main user forum**, shared with other open source projects
 - [Issues on GitHub](https://github.com/qupath/qupath/issues) - bug reports, *not* general questions
-- [YouTube channel](http://youtube.com/c/qupath) - includes **video tutorials** (still mostly for v0.1.2) and **webinars**
+- [YouTube channel](http://youtube.com/c/qupath) - includes **video tutorials** and **webinars**
 - [Twitter](https://twitter.com/QuPath) - most things will be **announced here first**
 
 :::{tip}
-There's also a fantastic forum post introducing QuPath from a user's perspective [here](https://forum.image.sc/t/qupath-intro-choose-your-own-analysis-adventure/27906).
+There's also a fantastic forum post introducing QuPath from a user's perspective [here](https://forum.image.sc/t/qupath-intro-choose-your-own-analysis-adventure/27906). Please note this post refers to verison 0.2.0 and there has been a few updates since then!
 :::
 
 If your needs for instruction are more modest, it's always worthwhile to try hovering your mouse over nearby buttons or input controls - there's a good chance that an explanation will pop up to explain what the control does.
 
-## Help for v0.1.2
+## Help for pre 0.4.0 versions
+Documentation for previous versions can be accessed within Read The Docs via the versioning in the lower left corner of any page. 
 
-The following resources relate to QuPath v0.1.2.
+## Help for  version 0.1.2
+
+The following resources relate to QuPath v0.1.2 (from December 2018).
 They are no longer actively maintained, and some information may not apply to v0.2.0.
 
 - [Original GitHub wiki](https://github.com/qupath/qupath/wiki)

docs/tutorials/cell_classification.md

@@ -1,10 +1,5 @@
 # Cell classification
 
-:::{warning}
-This replaces the -- now deprecated -- detection classifier that was previously available in QuPath, and described [here](https://github.com/qupath/qupath/wiki/Classifying-objects).
-It is recommended to limit the use of the old detection classifier because it will be removed in future versions.
-:::
-
 {doc}`cell_detection` looked at computing Ki67 labelling indices by counting positive and negative cells within user-defined regions of interest.
 These regions had to be drawn very carefully to try to ensure that they only included tumor cells, and excluded other cell types that should not contribute to conventional scoring of Ki67.
 

docs/tutorials/density_maps.md

@@ -1,8 +1,6 @@
 # Density maps
 
-**Density maps** are a new concept introduced in QuPath v0.3.0.
-
-They were originally created to help find 'hotspots' for specific applications in pathology (e.g. tumor budding, Ki67 scoring).
+Density maps were introduced in QuPath v0.3.0. They were originally created to help find 'hotspots' for specific applications in pathology (e.g. tumor budding, Ki67 scoring).
 However, their implementation in QuPath is designed to be much more flexible than that.
 
 In some cases, density maps can even be a replacement for {doc}`pixel_classification` or {doc}`superpixels`.

docs/tutorials/exporting_measurements.md

@@ -45,14 +45,14 @@ If your analysis involves combining measurements from different images, it is re
 
 The cleanest way to export different types of measurements in QuPath across multiple images is with the **Measurement Exporter**.
 
-Provided that your images are stored in a {doc}`project <../tutorials/projects>`, you can access it through {menuselection}`Measure --> Export measurements` (as well as {{ icon_table }} --> Export measurements).
+Provided that your images are stored in a {doc}`project <../tutorials/projects>`, you can access it through {menuselection}`Measure --> Export measurements`.
 
-:::{figure} images/measurement_exporter.png
+:::{figure} images/exporting_measurements.png
 :align: center
 :class: shadow-image
 :width: 70%
 
-The Measurement Exporter
+The Measurement Exporter.
 :::
 
 From there, you can decide from which image(s) the measurements will the be exported (similar to the {doc}`Run for project <../scripting/workflows_to_scripts>` command in the script editor).

docs/tutorials/multiplex_analysis.md

@@ -1,11 +1,6 @@
 # Multiplexed analysis
 
-:::{warning}
-This tutorial describes an entirely new approach for multiplexed analysis within QuPath, added in v0.2.0-m9.
-It remains a work-in-progress, subject to change.
-:::
-
-This tutorial outlines the basics of how multiplexed images can be analyzed in QuPath v0.2.0, using the sample {doc}`LuCa-7color_[13860,52919]_1x1component_data <../intro/acknowledgements>`.
+This tutorial outlines the basics of how multiplexed images can be analyzed in QuPath using the sample {doc}`LuCa-7color_[13860,52919]_1x1component_data <../intro/acknowledgements>`.
 
 :::{figure} ../intro/images/LuCa-7color_[13860,52919]_1x1component_data.jpg
 :align: center
@@ -145,7 +140,7 @@ Because these measurements are based on the channel names, it is important to ha
 
 The next step involves finding a way to identify whether cells are positive or negative *for each marker independently* based upon the detections and measurements made during the previous step.
 
-QuPath v0.2.0 supports two different ways to do this:
+Since QuPath v0.2.0 there are two different ways to do this:
 
 1. Threshold a single measurement (e.g. mean nucleus intensity)
 2. Train a machine learning classifier to decide based upon multiple measurements
@@ -155,7 +150,7 @@ You do not have to choose the same method for every marker, but can switch betwe
 
 #### Option #1. Simple thresholding
 
-QuPath v0.2.0 introduces a new command, {menuselection}`Classify --> Object classification --> Create single measurement classifier`.
+QuPath v0.2.0 introduced a new command, {menuselection}`Classify --> Object classification --> Create single measurement classifier`.
 This gives us a quick way to classify based on the value of one measurement.
 
 As usual, you can consider the options in the dialog box in order from top to bottom, and hover the cursor over each for a short description of what it means.
@@ -202,14 +197,18 @@ This process is a bit more involved, but the effort is often worth it.
 It is very difficult and confusing to try to train multiple classifiers by annotating the same image.
 
 The process is made easier by creating duplicate images within the project for each channel that needs a classifier.
-To do this, choose {menuselection}`Classify --> Extras --> Duplicate channel training images`.
+To do this, choose {menuselection}`Classify --> Training Images --> Create duplicate channel training images`.
 
 :::{figure} images/multiplex_duplicating.jpg
 :align: center
 :class: shadow-image
 :width: 90%
 :::
 
+:::{Note}
+It's useful to run cell detection **before** duplicating the images so the detections match!
+:::
+
 :::{tip}
 It is a good idea to turn the **Initialize Points annotation** option *on*... it might help us later.
 :::
@@ -323,7 +322,7 @@ Amidst a blaze of color, it can rapidly become difficult to interpret images.
 A few things can help:
 
 - The box in the bottom right corner of the viewer now shows not only the mouse location, but also the classification of the object under the cursor.
-- {menuselection}`View --> Mini viewers --> Show channel viewer` makes it possible to see all channels side-by-side. Right-click on the channel viewer to customize its display.
+- {menuselection}`View --> Show channel viewer` makes it possible to see all channels side-by-side. Right-click on the channel viewer to customize its display.
 - Right-clicking on the *Classifications* list under the *Annotations* tab, you can now use {menuselection}`Populate from existing objects --> All classes` to create a list of all classifications present within the image. The filter box below this list enables quickly finding classifications including specific text. You can then select these, and toggle their visibility by right-clicking or pressing the {kbd}`spacebar`.
 - Right-click on the image and choose {menuselection}`Cells --> Centroids only` to have another view of the classified cells. Now, the shape drawn for each cell relates to the 'number of components' of its classification, while its color continues to depict the specific class. This makes similar-but-not-the-same classifications to be spotted more easily than using (often subtle) color differences alone.
 

docs/tutorials/thresholding.md

@@ -34,7 +34,7 @@ A *thresholder* in QuPath is something that can apply a threshold to an image wh
 
 ### Thresholds in action
 
-You can create a thresholder using the *Create thresholder* command.
+You can create a thresholder using the {menuselection}`Classify --> Pixel classification --> Create thresholder` command.
 
 There are three main purposes for this: to create objects (usually annotations), to add measurements to objects (can be anything), and to classify objects (only detections).