Documenting 2D vs 3D

[AnneCarpenter]

At the end of the module's introductory help text, RelateObjects has this line:
This module supports 2D and 3D objects.

Have we added this to all other modules that need it? I've not seen any other modules so far.

[bethac07]

I haven't checked it exhaustively but it should be in most of the modules that support 3D, I held up lots of people's PRs until they added it to the module docs :)

[AnneCarpenter]

Hm, a search for "This module supports 2D and 3D objects." only comes up w RelateObjects. I spot checked a couple of modules (Watershed and smooth) and I don't see any such statement. Do you suppose it was different wording or something?

[bethac07]

The language likely was not consistent, esp WRT images/objects. Check out a bunch of the measures that support 3D, they should (mostly) have something in the top level docs.

…

On Thu, Sep 14, 2017 at 7:10 PM, Anne Carpenter ***@***.***> wrote: Hm, a search for "This module supports 2D and 3D objects." only comes up w RelateObjects. I spot checked a couple of modules (Watershed and smooth) and I don't see any such statement. Do you suppose it was different wording or something? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3156 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGaP64wMpNuEl7fn-sCWZGTuaBJIzbdbks5siV4dgaJpZM4PX4aK> .

-- Beth Cimini, PhD Computational Biologist, Imaging Platform Broad Institute 415 Main St Room 5011 Cambridge, MA 02142

[mcquin]

I noticed some say "volumetric" and others say "3D". We should make this consistent & put it in a consistent place. My vote is either at the very top or very bottom of the module documentation.

Would a table visualization be helpful/easy to use? E.g.,

Supports 2D?   Supports 3D?
    YES            NO

(^ but with table borders)

[AnneCarpenter]

Yeah, that sounds great!
Is it sensible to also include a column for 3D data loaded as 2D slices? I imagine the answer is always yes (when 2D is yes, that is). If so, we could just have that as a separate column or else change the heading to "Supports 2D (or 3D loaded as 2D slices)?"

[bethac07]

That column would indeed include every 2D or 2D+3D module, since any 2D module can handle 3D images loaded as slices (aka what people used to do with 3D data in 2.2 and before). Or do you mean modules that operate on volumetrically loaded images but do so in a planewise rather than volumetric fashion? Let's get super precise, then figure out a sensible standard thing we can add as a variable.

…

On Thu, Sep 14, 2017 at 11:17 PM, Anne Carpenter ***@***.***> wrote: Yeah, that sounds great! Is it sensible to also include a column for 3D data loaded as 2D slices? I imagine the answer is always yes (when 2D is yes, that is). If so, we could just have that as a separate column or else change the heading to "Supports 2D (or 3D loaded as 2D slices)?" — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3156 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGaP6zQeaWiwrf1dLS1ZByM7lIHR3sYzks5siZeUgaJpZM4PX4aK> .

-- Beth Cimini, PhD Computational Biologist, Imaging Platform Broad Institute 415 Main St Room 5011 Cambridge, MA 02142

[AnneCarpenter]

You just flew out of my league, so I'm no longer a valid discussant here :)

[bethac07]

No, we want you as a discussant, because it's precisely for someone who isn't totally clear on the terminology who we need to figure out how to make it clear for. 3 possible things can happen with a 3D image: - You don't tell CellProfiler it's a 3D image, so CP modules treat each slice as a separate image- this is what people used to do in 2.2, and it's what would happen now if you loaded a 3D image without checking the "Volumetric" box. It would work in any module that supports 2D images (all old modules) - You tell CP it's a 3D image (by checking the "Volumetric" box), and that module performs operations on the whole 3D stack at once- this is what most of our 3D modules do (Watershed, etc) - You tell CP it's a 3D image (by checking the "Volumetric" box), BUT that module performs operations on the individual Z slices one at a time- this is how some of our 3D image processing modules work. We've had discussions before on whether it's important to separate cases that follow the second vs third bullet point in the documentation; I think it ended with the jury out but leaning towards no. What I believe you were talking about is the first bullet point (please correct me if I'm wrong!); I don't see a compelling use case for it happening that often, so I don't think it's necessarily that important to discuss it in every module that only supports 2D (which will be the vast majority of the modules, at least for right now). That being said, I could be wrong, so let's keep the discussion going.

…

On Fri, Sep 15, 2017 at 1:39 AM, Anne Carpenter ***@***.***> wrote: You just flew out of my league, so I'm no longer a valid discussant here :) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3156 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGaP62Ktqbh3rE7TdS0ZUUVLGteLEFCgks5sibkWgaJpZM4PX4aK> .

-- Beth Cimini, PhD Computational Biologist, Imaging Platform Broad Institute 415 Main St Room 5011 Cambridge, MA 02142

[mcquin]

• You tell CP it's a 3D image (by checking the "Volumetric" box), BUT that module performs operations on the individual Z slices one at a time- this is how some of our 3D image processing modules work.

I think that's worth highlighting (in some cases) in individual module documentation. For example, the morphology modules (which now live in Advanced), can operate on the whole volume with a 3D structuring element, or plane-wise on a whole volume with a 2D structuring element. This, however, is not normal. And, since these modules live in the Advanced category, it's not worth adding a field to indicate this behavior in all modules.

What about:

    2D images or slices   3D images (whole volume)
            YES                  YES

[bethac07]

I quite like that!

[AnneCarpenter]

Ah, I see - it's indeed your third point I had no idea existed.

I think it'd be great when telling people which modules work on 2D vs 3D which of these flavors is possible for a given module. I think I'd need an example of the 3rd point to know whether the distinction vs 2nd is crucial to describe or not.

[AnneCarpenter]

I think it may be that @bethac07 and @mcquin are the only humans who would know the right answers for all the modules, and maybe not even them! As a shortcut, should we use the Y/N labeling in either of our internal spreadsheets?

• https://docs.google.com/spreadsheets/d/1x-trx9QuF9hthy5Risrbqyt4Rlp3MEuW1yvvwwRSRZQ/edit#gid=0 (Modules tab)
• https://docs.google.com/spreadsheets/d/1UhBJj7y0U7ubP-VlZR-kWkuxZ91G4o27RFuTbkQow1A/edit

If that info is sufficiently accurate, then @N3llz could add "This module supports 2D and 3D objects." (or "images") to all those modules and call this 'good enough'. I'm afraid it won't get done at all otherwise.

[mcquin]

@AnneCarpenter @N3llz the first linked spreadsheet is up to date with the current modules supporting 3D. I have not been managing the second spreadsheet, I'm not as confident about its status.

(One thing to note is Images/Metadata/NamesAndTypes/Groups probably should not have this tag added to them, IMO.)

[AnneCarpenter]

So, if Y on the first spreadsheet, then:
"This module supports 2D and 3D objects." (or "images")

If N on the spreadsheet, then:
"This module does not support 3D objects." (or "images")

[N3llz]

Have we decided on "images" vs. "objects"?

[bethac07]

Images vs Objects depends on the particular module, and sometimes it's both. We can either spell out the variables for all 6 cases (OBJECT_3D, IMAGE_OBJECT_3D, etc) or just have 2 (SUPPORTS_2D, SUPPORTS_3D) and live with having an "images and/or objects" in the setting. Though i did like Claire's chart idea upthread! I think you could do it as a list table (see Morph for an example) quite easily, then call the table as a variable.

…

On Wed, Sep 20, 2017 at 8:05 PM, Jeanelle ***@***.***> wrote: Have we decided on "images" vs. "objects"? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3156 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGaP62bd3i7uDzHRfvmlbkLwEwq457CRks5skVPcgaJpZM4PX4aK> .

-- Beth Cimini, PhD Computational Biologist, Imaging Platform Broad Institute 415 Main St Room 5011 Cambridge, MA 02142

[AnneCarpenter]

It's a good point that perhaps we could just live without the specificity of images vs objects if we use a table instead of narrative text.

To keep it simple, I'd propose Jeanelle just add this if it's a module w N:

Supports 2D?   Supports 3D?
    YES            NO

And this if it's a module that is Y:

Supports 2D?   Supports 3D?
    YES            YES

[N3llz]

Do we like this?

============ ============
Supports 2D? Supports 3D?
============ ============
YES          YES
============ ============

[N3llz]

And in cases where there is a "Measurements made by this module" section, I'll put it immediately above that. LMK if this is good.

[mcquin]

Nice work on the table!

Do you think it would make sense to do something like:

ModuleName
==========

============ ============
Supports 2D? Supports 3D?
============ ============
YES          YES
============ ============

**ModuleName** does some stuff. It's cool and you should try it.

Then the information is always easy to find and in a consistent place?

[AnneCarpenter]

I like the positioning in Jeanelle's screenshot at the end of the modules' intro help. I can't tell, @mcquin , are you proposing it go elsewhere, like right after the module name and before the one-liner description of the module?

[mcquin]

@AnneCarpenter Yes. Below the title but before any text.

[N3llz]

I agree, it needs to be consistent. Do we want it to be the first thing people see and read though? It seems like it would still be nice to have the description first.

[AnneCarpenter]

^^^ Agreed with the woman in the sunglasses. The typical user isn't doing 3D so this isn't the MOST important thing on their mind.

[mcquin]

Sounds good. So, below the module description but before the first subheading?

[AnneCarpenter]

Right. I will edit the order in our other issue about ordering: #3177

[N3llz]

Resolved by #3282
@0x00b1 OK to close this issue