Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Computer Vision for the Humanities: An Introduction to Deep Learning for Image Classification, Part 2 #343

Closed
hawc2 opened this issue Jan 20, 2021 · 57 comments

Comments

@hawc2
Copy link
Collaborator

hawc2 commented Jan 20, 2021

The Programming Historian has received the following proposal for a lesson on 'Computer Vision for the Humanities: An Introduction to Deep Learning for Image Classification, Part 2” by @davanstrien. This lesson, which is in two separate parts, is now under review. This ticket is only for Part 2 which can be read here:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/computer-vision-deep-learning-pt2

@nabsiddiqui is reviewing Part I. This review of Part II will take into consideration the feedback provided on the Issue for Part I, available here: #342

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

I will act as editor for the review process. I will work with @nabsiddiqui, editor of Part I, to synchronize the review feedback for the two parts. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me.

Our dedicated Ombudsperson is (Ian Milligan - http://programminghistorian.org/en/project-team). Please feel free to contact him at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudsperson will have no impact on the outcome of any peer review.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. Thank you for helping us to create a safe space.

@davanstrien
Copy link
Contributor

@hawc2 thanks for editing this lesson 😀

Let me know if you or the reviewers need anything from me. The Kaggle notebooks are currently private but I can add anyone who needs access - I'd just need a username.

@hawc2
Copy link
Collaborator Author

hawc2 commented Mar 8, 2021

@davanstrien I’m providing preliminary feedback on Part 2 of your Computer Vision tutorial, in light of feedback @nabsiddiqui gave you in Issue #342 for Part I: https://programminghistorian.github.io/ph-submissions/lessons/computer-vision-deep-learning-pt1.

I agree with Nabeel, this is a solid tutorial, and your explanations of complex machine learning methods is quite excellent, usually very readable and clear. For doing revisions on your two part tutorial, you should start by integrating Nabeel’s feedback for Part 1 before turning to my comments for Part 2: https://programminghistorian.github.io/ph-submissions/lessons/computer-vision-deep-learning-pt2.

In line with what Nabeel says about Part 1’s introduction,my first thought is that during your overview of Part I’s structure you should foreshadow what Part 2 will do. A broader overview of the two parts and how they interconnect will help the reader walk through each part. Part 1 should overview it all, and Part 2 should briefly rehearse (and link to) what was discussed in Part 1, before outlining what will be covered in Part 2. Make sure to link Part 2 in the intro to Part 1, and again its conclusion. On this note, the conclusion to Part 1 could include a few more sentences clarifying the transition between the two parts. Part 2 provides a useful introduction reciting what was covered in Part 1; I don’t think the intro to Part 2 needs much more elaboration, but a little more of an explanation at the start of Part 2 explaining the basic terms established in Part 1 and describing why someone would do this very long tutorial and method would help situate it for the reader.

I would also say that what Nabeel suggests about explaining concepts before introducing relevant code throughout your tutorial applies equally well to Part 2, although maybe less often.

For Part 2, I have detailed my revision suggestions below by section and paragraph:

  • In the Looking at the Data section, the sentence “This step of trying to understand the data you will be working before training a model is often referred to as ‘exploratory data analysis’ (EDA)” needs a “with” between “working” and “before”. Ideally sentences like this (which appear in multiple places) would be reworked to not have dangling participles, in this way: “This step of trying to understand the data with which you will be working before training . . .”
    Also note, immediately after this sentence, you have a note to the reader that is separated into a different formatting - this separate formatting doesn’t seem necessary. The point you make could be integrated more normally into your discussion.
  • The section, Using a Model to Assign Labels, could be renamed to Comparing Classification versus Assigning Labels or something more apt to the lengthy discussion here. This discussion seems central to your lesson, but it could be clarified a bit. Perhaps you could explain a little more clearly why you decide to use a model to assign labels, and what advantages this offers over an unsupervised classification approach, if I am understanding this right? It would be helpful if the discussion here was more clearly referenced later in the lesson - with sign posts to when we will move on to a classification stage. I can’t quite say yet the best way to clarify this section, but it does strike me as needing more delineation in terms of classic terminologies around machine learning. Since this lesson is already too long, I’d say keeping it condensed will only help the reader follow along.
  • In paragraph 19, you state: “We will tell Matplotlib to use a different style using the style.use method.” Can you explain why you pick the “style” you pick, namely, “seaborn”?
  • Paragraph 20, you can simplify the first sentence to simply say: “Let’s now take a look at the dataframe.”
  • Paragraph 22: can you explain why the maximum size for training datasets is 2002?
  • Paragraph 22, minor syntax change, add a colon after “We can also see three columns”
  • Paragraph 26 - let’s start a new section before this paragraph, called something like “Wrangling the Data”. Your explanation of list comprehension is very good, but it would be helpful to delineate this as a separate step from “Looking at the Data”. You could use different size/levels of headings to delineate Wrangling the Data as a subsection.
  • Paragraph 29 - add a period to end of this sentence.
  • Paragraph 31 - would be useful to start a new subsection of Looking at the Data here focused on Counting the Labels, following the sentence “We now have a single list of individual labels.”
  • Paragraph 34 - make sure Python is capitalized everywhere. It isn’t in this sentence
  • Paragraph 34 - for the following chunk of code, is it possible to condense this code to include the titling in the definition of the plot function?
  • Paragraph 35 - again, it doesn’t seem necessary to format this note separately from the standard formatting for text explication
  • Paragraph 36 - the heading above this paragraph seems unnecessary.
  • Paragraph 45 - like the other notes you have warning the reader, I think this one could be integrated into the narrative to more clearly say what Metrics do for us. It’s not really necessary to say it doesn’t directly impact the training process, as in some sense it may impact the human’s choice on using a model or not. More generally, I would recommend integrating all such notes into your narrative discussion or cutting them.
  • Paragraph 48 - your diagrams are excellent. The start of this paragraph has fastai in lowercase. Could you start with another word so it looks like a grammatically correct sentence? If fastai is lowercase because it’s a package, it should be formatted as such.
  • The section on Image Augmentations is a little hard to understand. Can you try to explain in more colloquial terms what it means, or at least link to another resource with a more thorough explication? I found the following part clearest, but it wasn’t obvious if this was an actual definition of Image Augmentation: “Image transforms or augmentations are useful because they allow us to artificially increase the size of our training data.” Are image transforms and augmentations the same thing?
  • Paragraph 80 - you say “Again, we have seen this at a high level before, and most things will remain the same as in our previous advert example.” When are you referring to? Can you cite that instance more specifically? Especially since this is a two-part lesson, it might seem like you’re referring to Part 1. These lessons will be a lot for readers to take in, so being explicit with all internal citations is necessary.
  • Paragraph 82 - explain more what the differences and advantages are of different Imagenets
  • Paragraph 86 - remove the phrase “As a reminder”. Can you also explain “loss” more explicitly, or link to a secondary source?
  • Paragraph 88 - cite where numerically on the x-axis the loss shifts in significant ways, such as starts to go up radically
  • Paragraph 92 - be more explicit about the ‘ads’ example you’re citing, and since this is the first time you mention ImageNet, explain what it is and provide a link.
  • Paragraph 102 - the word “network” kinda comes out of nowhere here. I see you’ve used it a couple other places, but never in conjunction with ‘neural’ - its conceptual significance and definition should be made explicit for the reader. How is this different from, say, a network analyzed with a network analysis tool? What is a ‘neural network’/how does it relate to computer vision?
  • Paragraph 103 - looks like your wikipedia citation has some missing Markdown syntax.
  • Paragraph 105 - the heading above this paragraph is centered unlike all the others
  • Paragraph 112 - let’s start a new subsection here entitled Exploring Predictions Using Scikit-learn or something similar
  • Paragraph 114 - a couple minor typos here. New sentence for “This can give us . . .” A space before “which tells us. . .”. And make sure quotation marks come after the period if they appear at the end of a sentence, as in the last sentence in this paragraph.
  • Paragraph 119 - in the last sentence of this paragraph, start a new sentence at “however in our particular dataset”
  • Paragraph 120 - missing word here: “In comparison to the label ‘animal’, which mostly an easy for the human annotator of this dataset to identify,”
  • Paragraph 122 - the figure doesn’t appear - I can’t remember for sure but I think it was missing from what was originally submitted, and I noticed this when cleaning up the lesson in the fall.
    I’d also say the heading above this figure is a little unclear - what do you mean by “realistic” here? In the following heading, it appears in the center again, and seems too large. More importantly, “Sucking Pigs and Sirens” just seems out of place, too weird, in comparison to the language for every other section heading. The rest of the heading is fine
  • Paragraph 124 - this is a tough paragraph, the last sentence could be less convoluted. It is confusing who you are citing - Borges, Foucault, Wilkins? Part of the confusion is the “The Analytical Language of John Wilkins” needs quotations around it. Generally I think you can more slowly bring the reader into this theoretical discussion, perhaps first rehearsing a bit of what you’ve covered over this two part lesson, before diving into Borges and Foucault. I like you bringing in Foucault here, but it is a little out of nowhere. I wonder if you can cite some of this at the beginning of Part 2, and for symmetry sake, you should engage with similar theoretical references in Part 1 - I say this having not gone back and looked through Part 1 in detail for this. WIth that said, bear in mind you’re already over the standard 8K word limit PH sets, which is ok but your lessons shouldn’t grow too much longer.
  • Paragraph 125 - I’m also not sure it is true to say Borges is implying all categorization is arbitrary - I see what you are getting at, but it seems more complicated to me than that. Another useful reference for you is his essay, “The Total Library.”
  • Paragraph 126 - add quotation marks for the essay cited here as well. You should also provide the date of publication in parentheses for each of these published works. This citation is also confusing in the same way as the last, in that you are citing Borges citing someone else - maybe an unavoidable peril when engaging with Borges, but nevertheless this is going to be confusing for readers who have, up until now, been closely following technical discussion of steps in using code for machine learning. To help address this problem, consider also breaking these paragraphs up into shorter paragraphs to help guide the reader through the steps of your discussion
  • Paragraph 127 - the use of “not only” here would be easier to read if, instead of a period, you had a comma, and “but also” following immediately thereafter
  • The next section, “Next Steps,” should be titled something different, like “Further Reading and Resources.” It’s important at this point you clarify for the reader that the tutorial Part 1 and 2 is concluded. Again, summarizing everything you’ve covered will help wrap it up. The further resources are helpful, but it’s alot and some of it could be cut. Some of the concepts you cite could be introduced earlier in the tutorial and discussed as part of machine learning - bias in image analysis in particular seems something worth mentioning as a precaution, especially considering there are famous cases of these models mistaking humans for animals and vice versa, in particular in relation to ethnicity. Ditto for the GPU needs - that seems worth stating up front. Perhaps save this last part for just a few examples of Further Readings and Other Tools worth investigating.

Thanks for this great two-part lesson. Once you've revised both Part 1 and Part 2, we'll send it out for external peer review.

@davanstrien
Copy link
Contributor

@davanstrien I’m providing preliminary feedback on Part 2 of your Computer Vision tutorial, in light of feedback @nabsiddiqui gave you in Issue #342 for Part I: programminghistorian.github.io/ph-submissions/lessons/computer-vision-deep-learning-pt1.

Thank you for this super thorough feedback, it's really appreciated 😀 I have time blocked out later this week to work on this so I'm hoping I will be able to integrate the current feedback from part 1 and part 2 by the end of the week (I have been known to be overly optimistic with estimating these things...)

@davanstrien
Copy link
Contributor

@davanstrien I’m providing preliminary feedback on Part 2 of your Computer Vision tutorial, in light of feedback @nabsiddiqui gave you in Issue #342 for Part I: programminghistorian.github.io/ph-submissions/lessons/computer-vision-deep-learning-pt1.

Thank you for this super thorough feedback, it's really appreciated 😀 I have time blocked out later this week to work on this so I'm hoping I will be able to integrate the current feedback from part 1 and part 2 by the end of the week (I have been known to be overly optimistic with estimating these things...)

I was very optimistic with this time estimate... I have hopefully addressed the majority of the comments now. I am waiting for some of my co-authors to respond to the questions relating to the Foucault section since they wrote that. Hopefully, I can respond to those sections fairly soon.

I have included more sign-posting between the two lessons but I suspect that this will need a final review following any other suggestions from the reviewers.

Let me know if there is anything else I need to do in the meantime and thank you again for the detailed suggestions for this lesson (I realise it's a long one...)

@davanstrien
Copy link
Contributor

@hawc2 we have updated the conclusion section with the aim of improving the clarity. Hopefully, this addresses all of the editorial suggestions you've made. Please let me know if I have missed anything that needs looking at before this goes out for peer-review.

@cderose
Copy link

cderose commented Feb 6, 2022

davanstrien, do you have a link to the Kaggle notebook for the second lesson?

@anisa-hawes
Copy link
Contributor

Hello all,

Please note that this lesson's .md file has been moved to a new location within our Submissions Repository. It is now found here: https://github.com/programminghistorian/ph-submissions/tree/gh-pages/en/drafts/originals

A consequence is that this lesson's preview link has changed. It is now: http://programminghistorian.github.io/ph-submissions/en/drafts/originals/computer-vision-deep-learning-pt2

Please let me know if you encounter any difficulties or have any questions.

Very best,
Anisa

@cderose
Copy link

cderose commented Feb 6, 2022

Hi @anisa-hawes, thank you for reaching out. I have the link to the lesson, but I don't see a link to the Kaggle notebook that has the data and code. Or is there not a notebook that goes along with this lesson like there was for part 1?

@anisa-hawes
Copy link
Contributor

Hello @cderose. I have only moved the .md file in this case.

I understand that @davanstrien's Kaggle notebooks are hosted externally and they are set to private. Please connect with @davanstrien so they can grant you access !

@hawc2 is best placed to help with this aspect if you have any further questions.

@davanstrien
Copy link
Contributor

Hi @anisa-hawes, thank you for reaching out. I have the link to the lesson, but I don't see a link to the Kaggle notebook that has the data and code. Or is there not a notebook that goes along with this lesson like there was for part 1?

The notebook should be available here: https://www.kaggle.com/davanstrien/02-programming-historian-deep-learning-pt2-ipynb. Let me know if there are any issues geting acess.

@anisa-hawes
Copy link
Contributor

Thank you @davanstrien!
Hello @cderose, here's the link ^^

@cderose
Copy link

cderose commented Feb 8, 2022

@davanstrien and @anisa-hawes, thanks very much! I was able to copy the notebook over successfully and will share my notes this weekend.

@davanstrien
Copy link
Contributor

@davanstrien and @anisa-hawes, thanks very much! I was able to copy the notebook over successfully and will share my notes this weekend.

Many thanks! Shout if anything I can help with at my end.

@cderose
Copy link

cderose commented Feb 14, 2022

Another great lesson, @davanstrien! This one is, appropriately, the more technical of the two lessons. It very effectively highlights the many different steps and choices that are involved in preparing a dataset, training a model, and evaluating the model. Like with lesson one, I appreciate that you intersperse different examples of when and why you might do x versus y, and you link to a number of great resources for people who want to dive further into the decisions that have to be made.

My main thoughts are summarized below, but I would be happy to chat further or clarify any of my notes.

Main suggestions

  1. As you rightly emphasize, the decisions we make when preparing a dataset and training a model should be closely tied to our end goals, but there isn't an explicit goal that we're training toward in this lesson (unlike in part one). Given the findings at the end, it seems like the use case for this lesson could be a meta one, where we're training a model with an eye toward studying how an imbalanced dataset (more images of humans than animals) might affect our model's learning. Stating a goal like that early on in the lesson can help situate the work we go on to do.

  2. The dataset we use in the lesson has a lot of unlabeled images in it, which is very realistic. It would be helpful at a few points in the lesson if you would clarify how the unlabeled images are (or aren't) impacting the results of our model. Are we removing the unlabeled images? If we're not, how are they being validated? I tried to signal below a few spots where some of that discussion might happen.

  3. Regarding Kaggle - in order to create the model, users will need to have enabled internet access in the notebook. To enable such access, they have to give Kaggle their telephone number. For this reason, it could be worth considering switching to a Colab notebook so that people don't have to share personal information. If internet access hasn't been enabled, users will see an error for the code in p86. Here's the StackOverflow page that helped me when I got the error:

Minor edits/thoughts

  • p1 - include a link to the Kaggle notebook, along with a reminder of how to switch over to the GPU
  • p3 - no comma between "data" and "to training"
  • p5 - hyphenate "high-level" in the caption
  • p7 - add a comma after "machine learning model"
  • p10 - are the labels we'll be using ones that humans applied to the images or a computer?
  • p12 or p15 - you might add a sentence that touches on the limitations of labeling models, too
  • p20 - the Kaggle notebook provides a little more information about the format of the dataset right before the line of code; include that in the lesson on the Programming Historian, too
  • p25 - does the double label (separated with |) indicate that some images have two labels applied to them in this dataset? Will that matter for our purposes?
  • p27 - typo in the comment to the code, should be: "labels". I would also put it in quotes for clarification: 'create a variable "labels" to store the list'
  • p28 - add a "but" after the first comma: "Now we have the labels in a list, but we still..."
  • - add an "a" before list comprehension: "If you haven't come across a list comprehension before"
  • p33 - you might add a paranthetical here or in the next paragraph to say that the '' represents images that weren't given a label - you do that in p38, but might also mention it here or in p24, which has the first output that hints at the presence of unlabeled images.
  • p34 - I think this count refers to the total number of images in the dataset rather than the number of labels? If so, update the first sentence accordingly.
  • p38 - Since we're in the data exploration phase, you might mention that depending on the goals of the project, researchers may want to remove unlabeled images, or they might want to try to assign labels to those images before using them. They also might want to remove some of the human images to have more of an even balance across labeled images.
  • p40 - The example you offer in p41 is excellent for demonstrating why you shouldn't rely on the metric if you take the dataset as is. For curious readers, if researchers trimmed down the dataset with an eye toward having a more even distribution across the labels, would accuracy potentially be an approrpiate metric to use again? (As you show later on, even in such a case it likely shouldn't be the only metric that's used.)
  • p45 - this is a really helpful distinction between precision and recall. I would split these sentences up and put them next to where you first define the terms in p43 and p44 since they are more concrete and make the difference between the two clearer.
  • p46 - you might give a quick example of a situation where you'd prefer recall at the expense of precision or vice versa
  • p48 - really great reminder
  • p57 - You might start the paragraph by saying "In Part 1, we saw an example..." since we haven't seen an example yet in this lesson.
  • - Also, for the labels with semicolons (such as human;human-structure), is that how fastai is handling the labels that had a pipe separating them? In other words, is fastai preserving the doubly labels? You might state how that will or won't impact the model's training.
  • p60 - did we remove the unlabeled images, then, or why isn't there a fifth label for them?
  • p62 - use parentheses instead to separate the two parts for clarity: "Since our data is made up of two parts (the input images and the labels), one_batch() will return two things."
  • p70 - does this mean that there are still unlabeled images in the dataset? If there are, how is that going to impact the model and the precision/recall metric?
  • p73 - the code in the notebook is different from the code in the Programming Historian lesson (functionally, it looks the same, but the code should match)
  • p81 - add "that" after "Now"
  • p81 - we haven't said much about what we're training for - what's our example end goal in this case?
  • p84 - add "use" before "an existing model"
  • p85 - change to "fewer compute resources"
  • p86 - you might say F1ScoreMulti has round brackets or parentheses for clarification
  • p86 - this line of code will throw a not immediately decipherable error if the internet hasn't been enabled for the Kaggle notebook. Include a quick note here about how users can do that (Settings -> Internet slider) - first, though, they'll have to create accounts with Kaggle and provide their phone number, if they haven't done so already.
  • p87 - "Now that" and typo: "let's look"
  • p88 - might include a screenshot of the output since you helpfully do that for the other steps
  • p96 - great example that circles back to why it's good to look at a few measures
  • p102 comment - you can remove the two commas in the sentence that begins: "You will be able to see..."
  • p104 - change to "an unfrozen model"
  • p105 - add a period after the parentheses and before "When"
  • p109 - rephrase the first sentence: "Our model is not performing super well yet."
  • p115 - "Now that"
  • p117 - slightly rephrase: "We also pass in an average, which determines how our labels are averaged, to give us more control..."
  • p121 - this paragraph is another really great callback that reinforces some of the cautions earlier in the lesson around the uneven distribution of examples in the dataset
  • p123 - fantastic example that raises questions about the labels we use in machine learning and the impact that decision has on the training process and how much data may be required for the model to perform well
  • p124 - it looks like there's a footnote or paragraph link that's not working: [^7]
  • p128 - typo: "used to asking fundamental questions" - but actually, I would remove this sentence. The lesson is technical, but you also raise important fundamental questions along the way. Plus, the lesson isn't unusually technical in The Programming Historian context.
  • p131 - I would remove the parenthetical "especially humanists" and leave it at classification being a concern for anyone.
  • p135 - "how the deep learning model 'learns' from the data"
  • p136 - add a colon: "These steps included:"
  • - add a comma: "that some of our labels performed better than others, showing"

@davanstrien
Copy link
Contributor

@cderose, thanks so much for this review. I plan to work through the listed suggestions either this week or early next week. For some of the other overarching points:

As you rightly emphasize, the decisions we make when preparing a dataset and training a model should be closely tied to our end goals, but there isn't an explicit goal that we're training toward in this lesson (unlike in part one). Given the findings at the end, it seems like the use case for this lesson could be a meta one, where we're training a model with an eye toward studying how an imbalanced dataset (more images of humans than animals) might affect our model's learning. Stating a goal like that early on in the lesson can help situate the work we go on to do.

I will add some more contextual information at the start of this lesson to point to these aims. One of the reasons we chose this example was to try and prepare people for the typical outcome of ML models not working as expected. Many teaching materials focus only on the 'happy path' where the model trains well and the dataset is perfect. We wanted to bring this up in the lesson since this will be even less likely to be a situation when applying ml to humanities data. I will make this a bit more explicit upfront, though, so the fact that the model doesn't perform well in some cases isn't so abrupt in the lesson.

The dataset we use in the lesson has a lot of unlabeled images in it, which is very realistic. It would be helpful at a few points in the lesson if you would clarify how the unlabeled images are (or aren't) impacting the results of our model. Are we removing the unlabeled images? If we're not, how are they being validated? I tried to signal below a few spots where some of that discussion might happen.

I will add some more discussion and integrate this into the places you suggest.

Regarding Kaggle - in order to create the model, users will need to have enabled internet access in the notebook. To enable such access, they have to give Kaggle their telephone number. For this reason, it could be worth considering switching to a Colab notebook so that people don't have to share personal information. If internet access hasn't been enabled, users will see an error for the code in p86. Here's the StackOverflow page that helped me when I got the error

Thanks for pointing this out. I think I may be able to get around the need to have internet-connected by having bundling the resnet model weights as a dataset in the Kaggle space. I think it makes sense also to have a Colab option. This shouldn't be too hard to add, but I'll hold off until the content is (almost) final before doing this.

Thanks again for this review

@davanstrien
Copy link
Contributor

davanstrien commented Feb 17, 2022

Things for @davanstrien to check:

  • LaTeX rendering working correctly i.e. $a$ is rendered correctly.
  • brief explanation/description of negative sampling
  • sync notebook and lesson code

@davanstrien
Copy link
Contributor

Hi @cderose , thanks again for your comments. I have changed to fix most of the more minor comments. I will hold off on a few suggestions until I've got comments from @mblack884. I also plan to try and make the Kaggle process more straightforward and also add a Colab hosted version of the notebook. I will do that towards the end so it's easier to keep all of the content between the notebooks and the lesson in sync.

@mblack884
Copy link

I really enjoyed reading and working through this lesson. The discussion of methodological decisions was generally clear, and the lesson did well in integrating short explanations of the more technical/theoretical aspects of the work. The many links throughout work well to offer users deeper reading on those topics while keeping the focus of the lesson on implementing its method.

  1. A good overview of lesson objectives or learning outcomes at the start of the lesson, like the list found at the top of Part 1, would be helpful. I try to provide them for longer, complex units in the classes I teach to emphasize the relationship between theory & practice. They would also have the added benefit of making the specific contributions of the lesson more visible to people who are browsing through the PH's collections.

  2. Kaggle notebook loaded and ran correctly with this lesson. I could step through the process as I read and follow the output. In the interest of usabiltiy, should add some reminder about setup (sign-in, copy/edit netbook, enable Internet under settings) to ensure that the notebook will proceed past p31. Not familiar enough with Kaggle to know if its possible to pre-download and store into the notebook itself to avoid having to simply setup and/or avoid phone verification for those who don't want to give out their #.

  3. I like the conclusion as it helps to pivot the lesson's methods towards answering big research questions. But I think it might be more effective if you were to foreground the question of human/animal/landscape boundaries earlier. I'd imagine that most readers would have a project in mind when seeking out this lesson, but having a short paragraph noting that you're going to explore the fuzziness of cultural labels or boundaries between concepts using computer vision at the outset may help readers better understand the trajectory of your decisions at each stage of the process.

Other minor suggestions:
p38: Briefly mention what should be improved here. No need to get into how or why here as that would distract too much from the lesson. If you want to include some recommendation of how to handle the images without labels, I'd suggest a short note or appendix at the end.

p45: Short, conceptual definition of F-beta would be helpful here. There's a more technical definition provided in p51 (which is fine as is), but I could see some potential confusion given that the topic indicated by the section heading isn't directly acknowledged until several paragraphs into the section.

p68: You start using the yellow textbox here to mark off clarifications. I was intially confused because there were similar remarks above that didn't use it. May be a good way to include short explanation of what needs to be improved in the figure near p38.

@nabsiddiqui
Copy link
Collaborator

Thanks @mblack884. @davanstrien, let me know what you are thinking time line wise in terms of revision.

@davanstrien
Copy link
Contributor

@mblack884 thanks so much for doing this review 🙂
@nabsiddiqui I should be able to incorporate these changes early next week. I'll let you know if there are any issues with that.

@davanstrien
Copy link
Contributor

@nabsiddiqui I have incorporated the suggestions into the lesson content and made a few formatting fixes. The next step is to sync the lesson and notebooks on Kaggle and create a Colab version. I will do that tomorrow unless you think any other changes need to happen to the structure of the lessons.

@hawc2
Copy link
Collaborator Author

hawc2 commented Mar 7, 2022 via email

@davanstrien
Copy link
Contributor

@hawc2 my main reason for including the full text is to help avoid people having to switch between windows but I'm happy to defer to the editorial board on this. If you prefer to keep things separate I will make a new version of the notebooks that strip out most of the prose. I will leave some in to help provide a bit of signposting at least. Let me know if that sounds okay to you?

@hawc2
Copy link
Collaborator Author

hawc2 commented Mar 8, 2022 via email

@davanstrien
Copy link
Contributor

@hawc2 I have made a version of the lesson one notebook with the prose removed (https://www.kaggle.com/davanstrien/cleaned-01-progamming-historian-deep-learning-pt1). I have kept the headings to signpost where the code fits in the lesson. If this seems like a good approach to you/PH team I can do the same for part 2 and update the link in the lessons to point to that version of the notebook.

@hawc2
Copy link
Collaborator Author

hawc2 commented Mar 8, 2022 via email

@davanstrien
Copy link
Contributor

per discussion on #342 @nabsiddiqui and @davanstrien, both Part 1 and 2 of this lesson are now ready for copyediting @anisa-hawes

That's awesome! Thanks so much, @nabsiddiqui @hawc2 @cderose @mblack884, for all the work you've put into this 🤗

@cderose
Copy link

cderose commented Apr 13, 2022

The lessons will make a terrific addition to Programming Historian, @davanstrien. Thank you for the opportunity to have early access to them!

@anisa-hawes
Copy link
Contributor

Thank you, all! I am back from Leave today. I have #436 (another two-part lesson) on my desk for this week, so I will work on copyediting this lesson next week, aiming to deliver by the end of the day on Friday 29th April.

@davanstrien
Copy link
Contributor

@anisa-hawes thanks! Feel free to ping me if anything needs clarifying etc.

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 2, 2022

@anisa-hawes I'm finishing up Part 1, but wondering if Part 2 is also ready to go?

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 2, 2022

@davanstrien I'm updating the yaml for part 2, need a few things from you, including an abstract and if you have a preference, a second image. You can see the yaml at the header of the lesson markdown with my recent updates: https://github.com/programminghistorian/ph-submissions/edit/gh-pages/en/drafts/originals/computer-vision-deep-learning-pt2.md

@davanstrien
Copy link
Contributor

Abstract for part 2:

This is the second of a two-part lesson introducing deep learning based computer vision methods for humanities research. This lesson digs deeper into the details of training a deep learning based computer vision model. It covers some challenges one may face due to the training data used and the importance of choosing an appropriate metric for your model. It presents some methods for evaluating the performance of a model.

@davanstrien
Copy link
Contributor

suggested image:
computer-vision-deep-learning-pt2

source: https://www.flickr.com/photos/britishlibrary/11162263063/

If that one works I would suggest this for the avatar_alt: A cropped illustration of a mechanical diagram of a machine with pipes.

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 3, 2022

Thanks @davanstrien, looks great. Do you want to update your bio? This is what we currently have:

- name: Daniel van Strien
  team: false
  bio:
    en: |
      Daniel van Strien is a Library Science student at City University, London.
    es: |
      Daniel van Strien es estudiante de Biblioteconomía en la Universidad de la Ciudad, Londres.
    pt: |
      Daniel van Strien é estudante de Biblioteconomia na City University, Londres.

You can also provide your ORCid if you have one

@davanstrien
Copy link
Contributor

davanstrien commented Aug 3, 2022

Updated bio (let me know if you want me to attempt translations too).

- name: Daniel van Strien
  orcid: 0000-0003-1684-6556
  team: false
  bio:
    en: |
      Daniel van Strien is Digital Curator for the Living with Machines project at the British Library, London
    es: |
      Daniel van Strien es curador digital del proyecto Living with Machines en la Biblioteca Británica de Londres.
    pt: |
      Daniel van Strien é curador digital do projeto Living with Machines na British Library, Londres

@melvinwevers @kasparvonbeelen @kmcdono2 @tpsmi may also need to provide/update these.

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 3, 2022

yes, thanks! Please do provide translations if you can. Here's the template for your co-authors:

- name: Jim Clifford
  team: false
  orcid: 0000-0000-1111-1111
  bio:
      en: |
          Jim Clifford is an assistant professor in the Department of History
          at the University of Saskatchewan.

@kmcdono2
Copy link

kmcdono2 commented Aug 3, 2022

added translations

- name: Katherine McDonough
  team: false
  orcid: 0000-0001-7506-1025
  bio:
      en: |
          Katherine McDonough is Senior Research Associate in History on Living with Machines and UK PI on Machines Reading Maps at The Alan Turing Institute.
 es: |
Katherine McDonough es investigadora asociada sénior en historia para el proyecto Living with Machines e investigadora principal para el proyecto Machines Reading Maps en The Alan Turing Institute.
    pt: |
Katherine McDonough é Pesquisadora Associada Sênior em História para o projeto Living with Machines e Investigadora Principal do projeto Machines Reading Maps no The Alan Turing Institute.
fr: | 
Katherine McDonough est une chercheuse postdoctorale en histoire pour le project Living with Machines et la directrice du project Machines Reading Maps au Alan Turing Institute.

@davanstrien
Copy link
Contributor

yes, thanks! Please do provide translations if you can. Here's the template for your co-authors:

- name: Jim Clifford
  team: false
  orcid: 0000-0000-1111-1111
  bio:
      en: |
          Jim Clifford is an assistant professor in the Department of History
          at the University of Saskatchewan.

I've attempted translations for my bio.

@kasparvonbeelen
Copy link

- name: Kaspar Beelen
  orcid: 0000-0001-7331-1174
  team: false
  bio:
    en: |
      Kaspar Beelen is Research Associate in Digital Humanities for the Living with Machines project.
    es: |
      Kaspar Beelen es investigador asociado en humanidades digitales para el proyecto Living with Machines.
    pt: |
      Kaspar Beelen é Pesquisador Associado em Humanidades Digitais para o projeto Living with Machines.

Here is my bio with automatic translations.

@melvinwevers
Copy link

melvinwevers commented Aug 5, 2022

  • name: Melvin Wevers
    orcid: 0000-0001-8177-4582
    team: false
    bio:
    en: |
    Melvin Wevers is Assistant Professor Digital Methods at the History Department of the University of Amsterdam.
    pt: |
    Melvin Wevers é Professor Assistente de Métodos Digitais no Departamento de História da Universidade de Amesterdão.
    es: |
    Melvin Wevers es Profesor Asistente de Métodos Digitales en el Departamento de Historia de la Universidad de Ámsterdam.

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 6, 2022

@davanstrien are we still waiting on one authors bio? I'll move forward with publication next week. In the meantime, can you post the following to both Computer Vision tickets?:

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a [CC-BY](https://creativecommons.org/licenses/by/4.0/deed.en) license.

@davanstrien
Copy link
Contributor

davanstrien commented Aug 7, 2022

@hawc2 we're still waiting on one more, but I know @tpsmi is on leave, so might not have seen these. I've written something for Thomas now.

name: Thomas Smits
orcid: 0000-0001-8579-824X
team: false
bio:
en: |
Thomas Smits is a postdoc in the History of Bias Project at the University of Antwerp
pt: |
Thomas Smits é pós-doutor em History of Bias Project na Universidade de Antuérpia
es: |
Thomas Smits es un postdoctorado en el Proyecto de Historia del Sesgo en la Universidad de Amberes.

@davanstrien
Copy link
Contributor

I the author hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

@melvinwevers
Copy link

Hi @davanstrien I spoke to @tpsmi and he provided me with a short bio.

Thomas Smits is a postdoc in the History of Bias Project at the University of Antwerp

@davanstrien
Copy link
Contributor

@davanstrien are we still waiting on one authors bio? I'll move forward with publication next week. In the meantime, can you post the following to both Computer Vision tickets?:

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a [CC-BY](https://creativecommons.org/licenses/by/4.0/deed.en[](https://creativecommons.org/licenses/by/4.0/deed.en)) license.

We have all the author bios in place now; from our perspective as authors, the two parts of the lesson are ready to publish. Is there anything else blocking publication at this point?

@davanstrien
Copy link
Contributor

@hawc2 following up on my previous comment to see if anything else is blocking publication at this point?

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 18, 2022

nope, we're good, and it's almost published! stay tuned

@hawc2
Copy link
Collaborator Author

hawc2 commented Aug 25, 2022

This lesson, Part 1 and 2, is now published! Congrats everyone!

@davanstrien
Copy link
Contributor

This lesson, Part 1 and 2, is now published! Congrats everyone!

Thanks so much to you and @nabsiddiqui @cderose @mblack884 @anisa-hawes for all your hard work to prepare this lesson! Realise this was that was a lot of work but hoping this is a useful resource going forward!

I will be on leave next week but will keep an eye out on email/notifications etc in case anyone reports any setup difficulties etc.

@anisa-hawes
Copy link
Contributor

Hello @nabsiddiqui. It would be great if you could add Tweets (2 for each Part) to our Twitter Bot spreadsheet, so we can periodically publicise these lessons in the future. Instructions for how to do that are here but let me know if you have any questions.

As the lessons are now published, I'm closing this Issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

9 participants