Typesetting Code in LaTeX

Since I recently pulled a few all-nighters to prepare code slides to teach my students R and they were less than enthusiastic, I thought I’d use the opportunity to at least write up a post on how to display code in LaTeX for you guys. It focuses on displaying the code for teaching, writing tutorials and so on. So the integration of code in beamer will be dominant, or at least the example on which I demonstrate things. Of course, you can also use the tips to just display it in a ‘normal’ document.

When I thought about it, I realized there are actually so many ways of displaying code using LaTeX packages. So I’ll start with the most basic and then go on to the more advanced ones 😉  You can find the example document here on Overleaf. It uses the beautiful metropolis beamer theme, which is worth looking into as well.

code-listings1
Be sure to check out the template on Overleaf.

The \texttt{} command

This one isn’t a verbatim way to express code, but it will change the font to typewriter, so it ‘looks like code’. However, in these short bits of code, you will have to use escape sequences for reserved characters. Furthermore, it (shockingly!) is not natively included in beamer, so you have to add it yourself in the preamble if you want it (as demonstrated in the template). How can one write about code without over-using \texttt{}?

I make massive use of \texttt{} when ‘talking’ about code or, you know, writing explanatory text sequences. It is especially useful for bits of code where there is no excessive (or none at all) use of escape sequences. Then it is a really handy way to quickly typeset code. Once you have lots of reserved characters, you might be better of just using this next one.

The verbatim environment

This one really is a staple and pretty failsafe, but also doesn’t have code highlighting which you might want in most cases, apart from very short bits of code where highlighting isn’t important.

You can use verbatim as an environment for multiple lines of code which appear like a quote as a separate block in your text. In other cases, where you just want \texttt{} but without having to escape reserved characters, you might want to use the \verb|some code| command. You can use any characters as delimiters to denote beginng and end of code. To be more precise, a quote from the Overleaf site: “Any character, except letters and *, can be used as delimiter. ” So it can also be \verb+test+. The idea is that you can choose one which you will not need inside the code, as not to ‘confuse’ the enviroment.

A note about code in beamer

When you use code in beamer, make sure to always use the fragile option for the frames in question. This is necessary due to the way how beamer handles verbatim, apparently.

Also, beamer and code can generally can wreck quite some havoc. I have had problems with lots of KnitR where it would stop working for no reason, then the exact same code would work again later, etc. And there are lots of conflicts and bugs you need to know about. So if you run into problems here, don’t blame yourself. It might easily be beamer which is ‘responsible’ for some of the problems.

The lstlisting package

You can just use the lstlisting environment without configuring anything but then again, it will not have code highlighting which is kind of the point in typesetting code (most times at least).

However, I find that without setting your own colours for the listings, it still looks quite boring with the black and white hightlighting (bold vs. non-bold). You can configure it any way you like, can even define yourself which elements are to be hightlighted and how. But it is quite a lot of work if there isn’t something you like out of the box. I personally prefer minted and especially tcblisting – that is minted with tcolorbox (as far as I know, even though it’s called listing). It has these cute little boxes. I like boxes.

Using KnitR

When using knitr to run R in LaTeX, don’t forget to change the file extension from .tex to .Rtex so LaTeX gets a heads up that you want to use KnitR. Otherwise you’ll end up with jumbled code and might spend hours trying to find the mistake, since it isn’t actually in your code. (Just so you know, I speak from experience here 😉 It’s just so easy to forget to do this. Basically happens to me all the time…)

You can use KnitR out of the box on Overleaf. Note, however, that they might not have all the packages you might want. But if, like me, you just want to display code to teach coding, you can eval=FALSE the results (which will be error messages due to lacking packages) and let the students run the code themselves. Since my elaborated fancy didactical plan was not to share the code as a file but rather have them type it themselves from the presentations, to increase the learning effect. Disclaimer: It did not work out the way I had hoped it would 😉

The minted package

If you like fancy, minted probably is for you. It’s kind of like lstlisting but with more beautiful colours and preset options. Give it a try. It’s probably the go-to solution.

Minted and tcblistings

tcblistings use minted and tcolorbox to create highlighted code listings in cute boxes. For me, that’s just too good to be true 😉 Note, however, that Beamer, tcblisting and enumitem are not compatible with each other. There is a bug I haven’t yet found a way around. So you can’t use customized enumerates oder itemize in the same presentation as these code listings! Sad, but true. But maybe there is a not-all-that-inconveniant way for you to keep presentation and code parts in separate sets of slides anyway. Here, it’s on you to get creative 😉

Generally, with the beamer package, there are actually quite a few things which don’t work once you want to use some less common features. So in case you encounter a bug and really can’t see how it’s your fault, web search if it’s a common error or known bug. Maybe there will be a way around it, maybe there won’t.

A workaround for this specific case would be to use beamer with lstlisting.

Wrapup

So, I hope this helped you and provided you with  an overview of possible ways of typesetting code in LaTeX, with a focus on presentations.

Best, the Ninja

Resources

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

Advertisements

Two basic image manipulation life-savers

In this post, I wanted to share a few tricks for simple image manipulation (with the goal of making pictures look better) I’ve picked up over the years. While tip one will always be to learn to take better pictures, maybe these little tricks will help you when you are asked to put the latest conference pictures online and realize they’re not good and really need a makeover first. So one thing will be to beautify event photos. Another tip I share is how to easily create a nice little vector graphic from a photo of some historical object or person.

First things first

This might seem obvious, but make sure you only use images you actually have the right to use. Check explicitly, don’t just assume! Get written permisson, if it’s not 100% clear what your rights are. If you are supposed to take pictures for an event, most people now mention that pictures will be taken in the event invitation already and that by attending, you agree to have your picture taken. Check what practices are at your institution.

Secondly, I am not a graphic designer or anything and fully self-taught in this realm. These tips work well for me and might work for you too. But just to make sure: I’m not actually competent to teach anyone on this topic 😉

Vector graphic from photo

I want to give you a few tips on how to create a nice vector graphic from a historical photo. Vector graphics make for nice logos, for example. Adding one can be all the spicing up a simple template or poster needs. It’s an eye catcher. They take a while to make if you want a good one (a few hours), but can be done on a train ride or during a meeting 😉 and I’ve never regretted making one and people loved them. Even though I’m not a professional logo / graphic designer and my results are far from perfect.

tikzposter-with-timeline
A TikZ poster for the exhibit “Lyrik des Widerstands – Richard Zach zum Gedenken”, PH Steiermark / Graz / Austria. It illustrates what I mean by “a nice vector graphic can go a long way”. At least I hope it does.

How to go about it

Scan very high quality if the image is from a book. Or take a high quality photo, reducing background elements if possible (will save lots of time later). Get rid of noise (Gaussian blur, 10px or something, try it). Then vectorize it, for example using Vectorizer.io: they will let you do quite enough if you sign up for a free account and disable your adblock. You can’t do very many images at the same time but since you’ll have other image manipulation taks to do in between, this will be just fine. Of if you’re pressed, use a trial account.  Or do Vectorization.org. I also like the Imaengine app. But you can only save the results when you pay a few bucks for the full version (worth it though). In this case, save it high quality. But maybe also get back to Imaengine only after you’ve cleaned out background elements you don’t need to add final touches. Play around with reducing the number of colour or adding some blur. But reducing the number of colours basically is the main thing you want to do. Maybe start with the smallest possible number of colours and go back up until you think you got the “feel” of the original image back, but without the details. (For example, with just two colours, you’re likely to have lost the original “feel”.)

Then the work starts: Manually get rid of patchy sections as well as all the background in GIMP. It will look a lot better and way more professional if you just take the time to do this (even if it’s not perfectly done). This is where you can invest the 1-2 hours I mentioned this would take. As I said, I am by no means an expert but I feel that most image manipulation things just take a lot of time and effort – they aren’t necessarily difficult to do. So even a beginner can achieve an ok result if they’re just willing to put in the time.

maierus
This image is a direct result of a vectorization tool and now you probably understand why we need the manual labour. The simplicity of the end result is the result of lots of work. But tweaking the vector output can help, too. This was made from a scan of an engraving depicting the early modern iatrochemist Michael Maier.

Manually drawing on the computer in an image manipulation program is not everybody’s thing an might take some getting used to. Many people will want to use a mouse for this. Don’t get discouraged by initial failures. It still is a question of practice and routine. You will, however, be able to get instantly better and more failsafe results if your base image is fairly big and you zoom in very closely. Start with baby steps. It will get easier once the most patchy areas are gone. Once you’re done, run it through the vectorizer once again to get rid of some of the small patchiness you might have overlooked or created while manually drawing around.

Delete the background. This can be done in multiple ways. If it’s all done in the same color, there is the option ‘color to transparency’ (or something like that). Else you might want to use the wand too and click delete or the like. Save (=export) the result. Voilà, your vector graphic is done.

maierus3
After you’re finally done with the manual editing done and marvel at your finished vector graphic, you’ll be so relieved you’ll start making pop art out of it. Believe me, I know what I’m talking about 😉 Oh, those train rides…

 

 

Some more tips

  1. To take into account: If the logo is supposed to be displayed very small, be sure to reduce a lot of detail. Always opt for 30% less detail than you think you need.
  2. Maybe make multiple logos or draw stuff on paper. Multiple quick sketches always yield better results than trying to get it perfect the first time. Fail fast and learn from your failures.
  3. Another win when using vectors is that you can output them as SVG or enlarge their size without things getting pixely. This might also be a reason you want to create a vector graphic in the first place.

Summary of a few GIMP shortcuts (learn some to significantly speed things up)

  • O = get the color (click)
  • P = switch to pencil
  • CTRL + C: copy
  • CTRL + V: past
  • CTRL + SHIFT + V: paste as new image
  • CTRL + SHIFT + E: export as (this is the ‘saving option’ in GIMP which will save the actual product, not the project itself – ‘save’ will save the project).
  • CTRL+Z to undo
  • paste (CTRL+V)

Beautifying event photographs

Use the GIMP Retinex filter

From my research into the retinex filter you should only change the bottom-most setting to adapt the filter. The stronger you make it, the less natural the result, the more noise will be created, the more colours will be enhanced.

retinex-filter3
With retinex, adjust only the bottom-most option “dynamic”.

Usually, the point will come quickly where you crank up the colours and sharpness too much so the result looks weird and gets a “steely” feel (try it out to see what I mean).

 

retinex-filter2
Overdone retinex. Colours ruined. “Steely” feel.

 

For more or less failsafe use of this if you want to achieve results that still look more or less natural: use the filter, then copy the product (CTRL+C). CTRL+Z to undo the effect in the base image. Then paste (CTRL+V) the version with the filter on top of the now reverted to its initial state image. Open the layer editor, click right: make the pasted section as a new layer. Then scale down the manipulated layer’s transparency to 50% (or as you like). The original picture will be improved without looking all unnatural. And you won’t have to take a lot of time looking for the perfect retinex setting. Just take one that looks ok. With the overlay, details will get lost anyway. And by the way, retinex will always create noise. The default settings reduce this to a minimum but it’s still pretty noticeable. So maybe use a relatively fine-grained Gaussian blur afterwards to make up for it again.

And maybe combine the effect with the “three layer trick” explained below. Play around with it. Find something that works for you. I’m no expert either but I found these tricks quite useful.

 

The three layer trick to bring out colours and contrast

Copy your initial picture into three layers. Desaturate the first to grayscale and invert it. Then do a light Gaussian blur on it, set its transparency to 30-35% and ‘merge down’. Then (you’re ‘on’ the middle layer now) set this layer’s mode from ‘Normal’ to ‘grain merge’ (‘Faser mischen’ in German), then merge down. This will bring out colours and contrasts better. However, if the colours are not nice to begin with, they will just be intensified as if you’d cranked up the saturation too much.

If this is no good, mabye try the retinex filter to bring out the colours and sharpen instead. I found this three layer trick on the internet somewhere in the past and sadly, can’t find it anymore. If you accidentally happen to know the source, feel free to point it out to me 😉

Other things you could do to enhance your images would be to tamper with the white balance or colour curves. But I decided not to add other stuff here to keep it simple and actionable.

both-filters
Left: initial image. Not bad, but I’m not happy because these wooden rooms always give nasty light. Right: image after having used both techinques explained above. First the three layer trick, then retinex. The result is not much different in the way that it looks “obviously manipulated”, but it does kind of look better and more professional, I feel.

Very basic ‘mini’ retouch for dummies

Select the eyes and increse colour and contrast. Select the skin regions where there are no lines (like the nose, elbow pit on the arm, etc.) and blur them – either manually or with the blur ‘pencil’. This will smoothen out impefections. Don’t overdo it though or it will be very noticeable. Don’t smooth over lines or the result will look comical at best.

The best image manipulation is taking better pictures in the first place

But, the most important thing is: Try to get hold of a good camera and take pictures in good light. I personally find it easy to take good pictures when the light is good but when you would need flash, human beings always look bad. At least if you don’t have a clue what you’re doing. So I try to avoid situations where flash is necessary when taking pictures of people. Maybe other people are better at this. But if people are not wearning tons of foundation and powder to mattify their skin, flash is not advisable and you might get better people pictures without it.

Also, ever wondered why models spend so much time on makeup before photoshoots?That’s because image manipulation can only do so much. The better the pictures you start out with, the better the result.

Conclusion

So, these were some simple tips. I’m not really good at this myself but I’ve been doing it for a few years. These little tips have helped me in situations where, for example, I was asked to beautify some snapshots of the last conference. My experience is that your suffering will be minimized when you have good light and can bring a good camera. This is the most important part. “Repairing” pictures taken under bad circumstances and making them look good is a really hard task. But making mediocre shots a little better is something you can learn. But then again, if you only need small pictures for social media, phone apps offer filters to improve your pictures with a few clicks. So maybe it’s not even relevant for you to “go traditional” and use GIMP at all.

Hope this helps someone,

best,

the Ninja

 

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

Don’t call it a database!

When I started this blog, one of my promises and goals, apart from LaTeX-Ninja’ing, was to demystify the Digital Humanities for non-DH people. For a long time I have watched and I think one of the big mysteries of the DH still persists in Normal Humanists’ heads and thus, really needs demystifying. You might have guessed it, I want to explain why DH people will cringe if you call digital resources ‘databases’ which are not, technically speaking, databases.

Is it ok to call any digital resource / corpus a ‘database’?

We know, that’s what you tend to call a digital corpus. But in most cases it’s not correct, it’s a pars pro toto. A database is just one possible technical implementation, but the term is used more broadly for any ‘digital base of data’. By laypeople, at least. A pars pro toto stylistic device is a Humanities’ thing, right? You do get stilistic devices. So you can also understand why you shouldn’t use imprecise terminology. You don’t like it when people misuse your fields’ terminology either and probably make quite a religion about it.

If you want to work with the DH, you need to understand their terminology and respect it by using it correctly. Even though it might initially feel unintuitive to you. Believe me, you will adapt quickly if you give it a try.

I’ve caught myself so many times now, educating my Normal Humanist friends about digital resources and why my (DH) colleagues won’t take you, as a Humanist, very seriously if the word “database” slips out your mouth at inappropriate moments. It’s kind of like the Tourette’s of NH-moving-in-a-DH-world. Which probably is not a politically correct analogy. No offense to people who actually have Tourette’s, I don’t want to devalue or disrespect your struggle in any way! It’s just analogical in the way of spluttering out inappropriate words at inappropriate moments.

Everybody has their cringe-prone terminology item, right?

To be honest, I am not sure how strict the English speaking DH world is in this, but I can guarantee you that this distinction is very valid concerning the German language use of “Datenbank”. When a quick web search yielded this result, I wasn’t sure anymore if it’s actually a thing in English too. Digital Humanities at King’s College define a database as follows:

Database is the term we use for any large collection of online material.

( https://libguides.kcl.ac.uk/dighum/dighumdbase )

This, however, is exactly the way I don’t suggest you use this term. I am aware that this is the association linked with it in many people’s minds. But hey, you are Humanists. You do have a sense for the intricacies of terminologies, right? I, for one, really hate it when people use the wrong gender on the term corpus (in German: neutral (!) for a collection of documents, so always neutral, unless you mean an actual body like that of a musical instrument). You probably have a thing like that, too, where you get furious at laypeople saying it wrong, don’t you? Well, the DH equivalent of this thing is the misuse of the term database.

Using terminology correctly is a sign of respect towards the DH community. It shows you respect us as researchers and don’t think of us as the ‘idiot who does the tech stuff’

Well, to be exact, it’s not even a misuse. You sure can use the term database in this way and it’s not, strictly speaking, completely incorrect. It’s just misleading, and – most importantly as the subject of this post – it is a strong pointer to the fact that you are not very tech-savvy and either unaware or else disrespectful of digital terminology. It will be seen as either a lack of respect and esteem towards the digital field or, I don’t know which is worse, a lack of competence in general. You would deem it impolite, too, and probably take it as a sign of general incompetence or lack of intellecutal ability/openness  if a DH person came along and persistently misused your terminology, right?

Edit/addition 2019/06/04: I think this issue is less about whether it is technically or theoretically correct to use a term like this or like that. It’s a question of being ‘politically correct’ and of not hurting people’s feelings. To show the point on an extreme example (which is maybe exaggerated applied to databases but illustrates the point): you could theoretically argue that the term ‘nigger’ has been used historically to mean ‘person of color’, ergo it would – terminologically speaking – not be incorrect to use it, right? Wrong. In this case, it’s obvious (to everyone, hopefully) that it would be extremely rude and not ok to call a person of color a ‘nigger’ nowadays. Nobody would be confused if people’s reaction to this was to feel insulted because the above explanation does not take connotations into account.

Like you could say that before the advent of the DH, it maybe wasn’t a big deal to throw around the term ‘database’ to mean any digital ‘base of data’, but since the DH is starting to be established as a discipline and not only as a tool like it might have been in the beginning, things have changed. DH people sometimes feel like their competencies are not taken seriously because their part of the job is seen as the ‘handiwork’ whereas the non-DH input data is the actual research. I think that this latent inferiority complex, or maybe rather some sort of struggle for recognition, is the reason non-precise use of DH-related terminology is sometimes taken bitterly.

So ultimately, it’s not about being right or wrong. It’s about being respectful and not hurting other people’s feelings. Also, non-DH people insisting on using the term in a non-DH way while simultaneously wanting to participate in a DH project will cause a clash of terminology. It might be ok for a non-DH person to use the term like this, but DH people are kind of bound to use the term in a strictly technical way or else they might be seen as incompetent of their own field. In this case, I think the non-DH person should give in because even when they will not be judged by their use of DH-specific terminology, a DH person will. You don’t want your imprecise language to reflect negatively on your cooperation partners.

Since the initial publication of the post, I received the feedback that some people with technical backgrounds are quite open to non-technical uses of the term ‘database’. But from my own experience of the DH overall, I feel this is not necessarily representative. And only because people will accept that it is theoretically valid to use the term to one’s own judgement, that doesn’t mean people will condone it in practice.

If you want collaboration, start actually collaborating by learning about DH terminology

Especially if you are trying to get a collaboration DH or label DH project, I suggest you prune your language a little bit here. After all, DH people usually have lots of people queueing to get a project with them. They will tend to take the ones interesting for them (in terms of subject) and/or those where the applicants seem nice. And it is deemed base politness to research your collaboration partners’ field so you don’t draw a complete blank. You want your partners to be understanding and reasonably well-educated on the baseline of your field too, right? And you probably catch yourself sometimes, secretly saying to yourself in indignation or disbelief ‘How can any academic not know that?! This is completely basic!’

Well, it happens to DH people, too. Often concerning so-called ‘databases’ which are not, in fact, databases. If you persistently use the term wrong, it’s seen as lack for trying or plain incompetence. Don’t be rude. Now you are aware of the problem, you have no excuse to continue saying it wrong.

How to know if it’s ok to call it a database?

Two questions to ask to get a feel for whether what you mean might actually be a database:

  1. Would it make sense to represent this data in an (Excel) spreadsheet? Then it is likely someone chose a database format to represent it digitally.
  2. Are there any other fitting means to represent it? Only because it outwardly looks like it stores spreadsheet-formatted data, this doesn’t mean it’s they way data is stored “behind the scenes”.
  3. In case of any doubt whatsoever, just refrain from calling it database. Just say ‘digital resource’, ‘digital corpus’ or basically anything else which seems half appropriate. Anything else is way less stigmatized and cringe-worthy than the misuse of ‘database’.
  4. So to be on the safe side: Just don’t call it a database unless you’re sure it is one (technically speaking). When not 100% sure, just term it a digital resource or digital data collection. I know you just mean a ‘digital base of data’. But please respect that the wide category ‘digital base of data’ doesn’t mean the same thing as the narrow term of ‘database’ in a technical field.

Just a little thought – hope this helps!

Best,

the Ninja

PS: Can someone tell me whether you think it is valid to inform people they should not use the term database or would it be ok with you when they use the term in a non-technical way? I only know that people around me react quite aggressively when you do and will think you’re a technical layperson, thus not trust you much once you did. You’d basically be ‘disqualified’ after that unless you really have some very interesting other assets or extremely good grant acquisition records or splendid networking connection value.

 

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00