Code Monkey home page Code Monkey logo

Comments (7)

mkcor avatar mkcor commented on September 10, 2024

Dear @drcandacemakedamoore,

Thank you for sharing your feedback. I'm interested in your perspective, because we also use 'trivial' variable names (image, images, image_sequence) extensively in the scikit-image gallery of examples.

I'm curious what your suggestions will be!

but it happens during several of the lessons, not just this one.

Can you please specify which other lessons?

Thanks again,
Marianne

from image-processing.

drcandacemakedamoore avatar drcandacemakedamoore commented on September 10, 2024

@mkcor I made a PR where I changed this in episodes 2 and 3. It happens in several other episodes as well, however I or someone else will need to create a PR to resolve this. I hope I will send such a PR soon if no one else does.

from image-processing.

uschille avatar uschille commented on September 10, 2024

Thank you @drcandacemakedamoore for bringing this issue up! It is a very valid point and the maintainer team would like to weigh the pros and cons for 'trivial' variable names. The following list is what came up so far and is an incomplete list:

Cons:

  • using 'image' as variable name can lead to name clashes with submodules named image in image processing libraries
  • generic variable names make no connection to the image content, which can make complex code more difficult & confusing to read

Pros:

  • generic variable names are in line with examples on popular websites, e.g., scikit-image gallery
  • it becomes easier to wrap code in functions, where generic variable names are more appropriate
  • it becomes easier to copy&paste code snippets between examples

We would like to invite other community members to contribute to the discussion.

Thanks again for starting this discussion!

from image-processing.

mkcor avatar mkcor commented on September 10, 2024

Thank you, @drcandacemakedamoore!

It happens in several other episodes as well

Ok, so you meant other episodes. 👍

I can see the value of using more descriptive variable names, but generic variable names are convenient: Thanks for summing up the pros and cons, @uschille!

generic variable names are in line with examples on popular websites, e.g., scikit-image gallery

Oops, I've started some circular reasoning here: https://github.com/scikit-image/scikit-image/pull/6853/files#r1149112707

I tend to view this choice as follows:

  • A generic name makes sense in an educational setting, where concepts and methods are taught in order to be transferred and applied elsewhere (the application is a 'pretext' for teaching/learning);
  • In the scikit-image gallery, image, img, or image_sequence are typically used when loading the 'raw' image, and subsequent processing steps are reflected in the variables names, which helps follow the workflow (e.g., https://scikit-image.org/docs/stable/auto_examples/applications/plot_solidification_tracking.html);
  • A descriptive/specific name is more critical in real-world applications, where you maintain production code, and you certainly don't want to mix up images!
  • I know that we don't want to hide the real world from the learners, quite the contrary, but that's where I'm at...

from image-processing.

bobturneruk avatar bobturneruk commented on September 10, 2024

Thanks for all the input on this. It's clearly not an obvious call. If we were to go down this route of having variable names specific to the subject of each image, we should make sure that the file type from which the image was read is not part of the name i.e. eight or image_eight would be preferable to eight_tiff. This is because the representation in-memory is (as far as I know) no longer anything to do with the the file on disk.

The other thing is we're not entirely consistent in our current version with how we do this e.g. these two lines:

image = iio.imread(uri="data/eight.tif")
zero = iio.imread(uri="data/eight.tif")

There may be others. We should take this opportunity to try and be more consistent.

I think in practise, if one is writing a notebook that reads several specific images, then specific names are good practise, often the variable name is the only way to carry critical metadata through the analysis, but if one is writing code for a Python package containing image analysis functions / code that iterates over multiple images then image is often going to be an appropriately specific name. I don't feel this distinction is within the scope of this course, though. Overall, my opinion is that it's very slightly better, here to go with the scikit-image convention, and perhaps explain our reasoning in the instructor notes?

from image-processing.

uschille avatar uschille commented on September 10, 2024

A generic name makes sense in an educational setting, where concepts and methods are taught in order to be transferred and applied elsewhere (the application is a 'pretext' for teaching/learning);

I tend to agree with @mkcor. My feeling is that learners would understand intuitively that the variable image can contain different images. Working through the exercises will be easier if they can re-use code snippets between different examples without having to think about variable (re-)naming. That may be less cognitive load than having to translate the variable names for each example.

I also agree with @bobturneruk that consistency matters, so if we change the naming convention in the first few episodes, we should check the remaining episodes for consistency.

from image-processing.

tobyhodges avatar tobyhodges commented on September 10, 2024

Working through the exercises will be easier if they can re-use code snippets between different examples without having to think about variable (re-)naming. That may be less cognitive load than having to translate the variable names for each example.

I mostly agree. However, given that we have designed the curriculum with the intention that it is taught in Jupyter, I think one risk is that (due to the not-necessarily-linear execution order of code cells in a Notebook) learners might re-run an earlier code cell and unintentionally operate on another variable called image that has been created further down the document.

If we stick with image as the generic name for a variable containing image data loaded from a file, I think we should do two things:

  1. add an Instructor note, recommending that Instructors guide learners to create a new Jupyter Notebook for each episode.
  2. enforce an "only one variable named image per episode" policy: if any episodes contain multiple "different" image variables (i.e. where multiple files are loaded at different points in the episode), those variables should be named differently.

from image-processing.

Related Issues (20)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.