The nice thing is - code is open. Anyone who suspects something weird can look at the basic papers and implementation and fix it. And the solution in turn benefits everyone. For me, this is a prime example of the power of free software.
12 Likes
This is what I learned after working some years in science, and then some years in industry, being reviewed, doing reviews and organizing confereces and workshops all the time: People tend to expect too much from the peer review. (Almost) Nobody will re-implement an algorithm only to check it for the review. Most reviews will probably check the idea and concept, additionally some reviewers will find formal mistakes (citation format, spelling mistakes, graph readability etc.), and if you are lucky, somebody may follow the math coarsely and gives feedback in that regard.
Furthermore, reviewers will recognize the author (workgroup) and judge based on it, double blind review does not help. I was able to name the origin just by looking at a single image from a new paper, if it was from my field.
This is from an RF engineers perspective, where hardware is involved what makes re-implementation even harder, but I have review experience with several algorithmic papers from both sides.
When the TV news shows report about new findings regarding the corona virus, I always have to smile a little bit when they mention that the paper written by a well recognized workgroup is a preprint and not yet peer reviewed. What do they expect from the reviewers, do they think they will spend two years in the lab to re-synthesize the vaccine RNA (or whatever), do another long term study with people just to find out that the paper mentioned a wrong process chemical and reject the paper?
6 Likes
In their defense, editors and reviewers prepare those articles as a side job, and reviewers arenāt paid. Both tend to have rather full schedules already. So theyāll catch glaring mistakes (one hopes), but more subtle ones can get overlooked. In fine, itās the authorsā responsability that the calculations are correct, the review ensures that the work is scientifically sound (in the ideal case 
).
Cited articles are never checked (citations are, the articles themselves arenāt, beyond a quick glance to see if the citation makes sense in context).
@s7habo In theory, yes, everyone can rework the problem. In practice, thatās rather time consuming, even once you have the articles. And those articles are often not freely available, which means paying for copies (*) or a trip to the nearest (if youāre lucky) university library, where you would just pay copier costs.
(*: iirc in the order of 40$/copy. Publishing costs, and the publishers like some profit. There are big discussions on how much profit they should be allowed, and who should pay for the publishing, authors or journalsā¦)
2 Likes
Same here 
Not only canāt they rework the paper, the peer review process in itself takes weeks, in the best case. Papers (used to) have a few dates just under the title: date received, and date accepted. Interesting to compare those, and with the publication date (Iāve had some where more than a year passed between submission and publication, though that was in the old āpaperā days).
In fact, the advances with the corona virus came at a dazzling speed, way faster than any ānormalā research theme can ever hope to advance. Two years from discovering a new disease to having a working vaccine isnāt just fast, itās virtually instantanuous. It helps to throw $$ at scienceā¦
2 Likes
I found the artifact suspicious in your video tutorial (eg here), but decided that there is probably something I donāt understand about the math so I didnāt ask before I read the papers.
Sure, anyone can look at the papers and the code, but few people have the skills for both. The fact that this went unnoticed for so long is a strong signal that the module is currently underdocumented, and very few users have a clear idea of how the sliders are related to the output.
1 Like
Diffuse and sharpen was released 2 months ago. Also references are in comments in the code, which is how @flannelhead tracked the source of the mistake.
I meant documentation at the user level (ie the manual).
In its current state, I am not sure that even a user who is familiar with PDEs and numerical methods would be able to understand what this module does.
(I understand that this is a very complex module and documentation is WIP, and appreciate the fact that it was included in 3.8 as is.)
So itās not documentation you want, itās a paper with all the formulas and references.
The point of the user manual is for those who donāt understand PDE to be able to use the module. We donāt want equations in the user manual.
3 Likes
These could be appendices, special topics or links to the papers to make that information available but I donāt think it belongs in the manualā¦
I am sure lots of people are current with calculus and linear algebra etcā¦I havenāt done any since I learned the basics 40 years ago so I can generally follow things from use cases and get a general understanding of the math but I couldnāt follow the equations and I donāt think too many users canā¦given that we have to keep reinventing the wheel on some simple topics and concepts I canāt imagine there is a widespread utility for that level of detail in the main manual, it might even be counter productive, however maybe as a references, or special topics if someone wanted to create them perhaps put that sort of thing in that format?? It would seem that sufficient information is in the code to document the math for those that could make use of itā¦
While it seems like a simple ask, I think just maintaining the references to external documents is a lot of work (broken weblinks).
Maintaining links to Scihub is easier.
In this case, we are talking about references to research papers. Those tend to be pretty stable, and standardised. Either the references are to articles in paper journals (and Iāve used such references to find papers from the1860ās, and that is indeed eighteen hundred and sixty, not a computer science reference, I might add 
), or they (should) use DOI numbers.
1 Like
No, something in between. Ideally the equation(s) that tell the user how the module applies the four speed and direction parameters, as abstracted from the implementation details as possible.
I realize that not all users would find it useful, nevertheless I imagine that significant fraction of users have the background for it. Some sections of the manual do have equations (albeit simple ones), so it is not an exceptional thing to ask for.
Based on this, the module docs would be a great place for illustrating the components, ideally using an artificial example image like in the tutorial by @s7habo. Personally I find the subtract blend mode great for visualizing what the module did to my image, eg this is 2nd order speed with subtracted with a -0.1 fulcrum (showing a radiator lattice 
):
I would be happy to contribute these once I have a better understanding of the math behind the module, still working through it.
It depends on what you expect from the manual.In the module reference section, I prefer a concise description of the function of the module, and an explanation on how to use the module (order of operations, what do the different controls do).
That keeps the information for the user short and to the point,and, it makes keeping the reference up-to-date easier, as itās only a short text to modify when controls change (cf. filmic, the interface went through a few iterations.
Compare it to e.g. a camera: I like to know that a given control changes the diaphragm opening.
I do not need to know that changing the F-stop value makes the blades rotate over x degrees (or even that the diaphragm has rotating blades, which isnāt always true anyway). That might be interesting to know, but itās not something I want to worry about when handling my camera.
Even the effects of changing the diaphragm donāt have to be in a reference manual.
If someone wants to write more in-depth about certain modules, thatās very good. But, in my opinion (and thatās all it is), that should be published separately from the reference manual (in a section of the darktable site? or here?)
3 Likes
So do I, but this is a very technical module, and from the current description I am not sure that it is possible to gain the kind of understanding that you outline.
I would rather face the fact that a very technical module has a somewhat technical documentation, which does not give all the details and derivations of course (those belong in the paper).
I fully understand that people prefer less detail in the manual, and generally I agree with that. But for this module I am wondering if thatās the right choice.
You donāt have to wonder because we have already told you several times that we wonāt fill the manual with equations, it isnāt the appropriate place for it.
You even admit it yourself:
There are several other places where a very technical piece of documentation can go, and Iāve already outlined that. No amount of pushiness is going to change that.
1 Like
@Tamas_Papp if you get your head around the mathā¦perhaps think about adding a blog post. Back when I first started to use DT I found them great reads and they would be a great spot for that type of content and a nice contributionā¦ so something like this with all the math and examples that you would choose to introduce??
and
6 Likes
Great idea, working on the math for now but I will get back to it.
5 Likes
I look forward to your breakdown of the topicā¦