Deprecate "power" and move to "appmap"

[John-P]

• TIA Toolbox version: <=0.7.0
• Python version: any
• Operating System: any

Description

I would like to suggest changing the WSIReader option currently called "power" to "appmag" (or similar). The word "power" was a carry over from the openslide metadata referring to "objective power". However, this is (in most cases) actually referring to the total apparent magnification not the power of the objective lens alone. This small change would avoid confusion. We could keep "power" functioning as an alias with a deprecation notice at least until version 1.0 for backward compatibility.

[DavidBAEpstein]

@shaneahmed @simongraham @vqdang @John-P
Is the terminology used in tiatoolbox standard in the pathology community? Before we make any change such as John suggests, we should find out from pathologists (from more than one pathologist) what terminology they use. To see one view, Google "A level notes magnification resolution" and look at the top hit. You can also look at https://courses.lumenlearning.com/ap1x94x1/chapter/magnification-and-resolution/
But neither of these are for an audience of pathologists. For that audience, look at
https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3779393/
which is a scientific article trying to clarify issues (of the meaning of words) that arise when pathologists first meet digital pathology. You will see that there are many opportunities for confusion.

I think we should have a discussion with pathologists to make sure what words the pathology community uses and with what meaning, before undertaking a change in documentation that is likely to affect many files. If there are to be such changes, I would like to be sure that they are in line with the expectations of pathologists and are not open to misinterpretation by them.

[John-P]

Well the problem is that there is no clear standard terminology in the digital pathology space. Hence, how OpenSlide ended up using a term which is not accurate. There may also be the issue of terms from one field being use differently in another. For example, in physics (optics) the terms: objective lens, objective magnification, total magnification are all well-defined in the context of telescopes and microscopes (https://en.wikipedia.org/wiki/Magnification#Magnification_as_a_number_(optical_magnification)). You can see from the equations that 'magnification' or apparent (angular) magnification is a ratio of objective and eyepiece focal lengths. This could of course get complicated with multiple lenses, which many modern optical systems use to reduce distortion. Ultimately, why would you want to know just the objective magnification? Surely what is important is the overall magnification? You do not really need to know how many lenses or the magnification of each.

I believe that there may have been some mistranslation or misinterpretation of terms when moving from light microscopy to digital, with the added complexity of sensor size and resolution instead of a human eye at the end coming into play. Of course, if one prominent source uses a term e.g. OpenSlide then it can get repeated by others.

[DavidBAEpstein]

There's a misprint in the title of this issue #149: appmap -> appmag.
"app" sounds like a mobile phone app, so perhaps appt_mag would be preferable or apptMag.
@John-P : I would like to know what words are used by the various slide scanner manufacturers and those who work on the software, like Openslide. Would it make sense to stick to their usage, or to the most common usage, if there are several? I haven't tried to research this.

[John-P]

Yes a look into the manufacturer language is a good idea. I know that both Aperio (SVS) and Omnyx (JP2) use "AppMag" in their metadata. However, it is Python convention to use lowercase is string options i.e. "appmag" or "app_mag". I will have a look into some other sources to provide a more comprehensive list. Perhaps another option is to stick with "power" as this is sometimes used instead of apparent magnification (e.g. in that Wikipedia article). As long as it is explained in the documentation well.

[DavidBAEpstein]

I agree with moving to clearer terminology, with good documentation and definitions. Can we decide how it would look and what would need to be changed if we decide to use the terminology used by slide scanner manufacturers?---This could be awkward if different manufacturers use different terminology for the same concept, but then we could choose one of them. Such a move should be associated with documentation that also explains the terminologies used in different fields. We don't know where the users of TIAtoolbox will be coming from. We could also give a dictionary that explains the terminologies of the different manufacturers, where they differ from each other.