Showing posts with label Writing technical papers. Show all posts
Showing posts with label Writing technical papers. Show all posts

Thursday, November 11, 2021

How to write a paper on a new hydrological model component

 Let’s try to keep the matter simple.  General rules apply:



Analyzing back the general scheme, in the case of software presenting, you need a specific part dedicated to the availability and delivery of the software. The main parts required here were already illustrated in explaining the Zero Notebook contents.

Because you are talking about scientific software your methodology has two parts. One related to the science you have to produce and one related to the science of writing good software.

Taking the example of Evapotranspiration. The science could be the one included in the sub-models you are implementing. Meaning, what is the science behind Priestley-Taylor, which the one behind FAO approach, and which the one one behind, for instance, our Prospero model ? Here the material is very large so you have to work usually by extracting the essentials and citing the literature. Part of it can easily fit actually inside the introduction. The informatics has to do with the way your system is built. Which is the framework you use, in our case, OMS3, and why you use it, instead of others. It also the system you are working with, like in our case GEOframe that provides ancillary tools. Finally the informatics can boil down to the algorithms and their organization in classes. Algorithms can be new or old and irrelevant. Just in the first case it is important to mention them with details, otherwise just a a little note can be done. Classes, assuming we are talking of some OO programming, have two scopes, one is to contain the algorithms, the other is to orchestrate the software relations in order to make easy the reuse of the softwares and their expansion. This part will be routine in future, maybe, but now it is not part of the common knowledge of hydrologist, and therefore it is worth to be explained if well engineered. In explaining classes and the overall working of the software using of UML diagrams is mandatory.

In a software paper, it is debatable what is the test of the contents. Let’s say that, because we are hydrologists, we need to test both the software running, and the models’ physics.

The software running test for who is programming in Java, like we do, is obtained through the appropriate Unit Tests and this part is commented, in case, inside the section which inherit from the Notebook Zero. For the physics we have, in turn, two modes. If we are solving problems, i.e. equations,  that have an analytical solution, then we have to reproduce the analytical results. Secondly the nasty reviewer, would also see that the model reproduces measurement. Getting some measurements to reproduce is then important. A third case is also ideally possible, which is that, no measurements are available and therefore eventually the model provide a possibility to test something that was never tried before. In this case it must be emphasized that the model makes possible something that before was not not, and we have to rely to some virtual, behavioural, experiment.

If measurements are involved, new methodological steps come in: explaining the case study, first. Secondly, not differently from other cases, we have to say if parameters to calibrate and to mention the techniques we use for doing it. Explaining how we assess the goodness of the results, and finally commenting the results are the rest of the story. An exceptionally good software that does not reproduce reality is simply not useful from the hydrology point of view, even if its implementation can still provide novelties worth to be explained. The physical test, however, should not extend to be very complicate but just functional to convince that the software is doing what it is designed to do. In the mentioned case of evapotranspiration, another issue is relevant, which is the comparison among sub-models or models alternative. It is clear that different models produce different results, so assessing in which case they work or work netter is important. However, that can be pursued with moderation in a “software presentation” paper, because this is clearly an argument which requires a paper by itself. For example , in a recent paper, Clark et al., 2021, they talk of “laugh test” for emphasizing this aspect.

At the end of the post, you have some ingredients and an idea of the procedure. To cook them together for a nice result is a little of art.  In general, a good example to follow is the WHETGEO paper.

Tuesday, August 31, 2021

Building a story or how a "narrative" is important in science I: in writing

 I found the below figure which I do not know the Author which I think can be useful to understand both what it is implied in writing a scientific paper and what is a theory, with respect to more simple analysis of data (or models, BTW). The first four arrangements of the data have some interest but, they do not capture much our interest. To do a gory example, is like to take an animal or a tree, separate them in parts and analyzing them from the point of view of the atoms it is made.  This information is real but it does not say anything crucial about the living being.  The being important think is realized when all the material is put together again (it would be great if the separation operation would be reversible) and it is analyzed in its "holistic" form and function. 


So, it is for the topic of a paper. Usually we have a problem and we dissect it using a "reductionist" approach, but we are not able to put again the whole together and make sense of it. The reductionist action is usually not trivial at all, as the figure could, on the contrary, suggest, and the Authors are usually exhausted after having applied the techniques for doing it which could be experimentally and/or mathematically very complex.  But writing the paper needs the vision of the whole, the story to tell, and the discovery, in the rough matter,  of the sense. It is not a bottom-up action but more a top-down one, where hypothesis and deduction comes before than induction.  
Therefore in writing a paper, we should first have an idea of the whole functioning, trying to get a working a logic from the elements we have in hands and see if they fit. At the first trial they will probably don't. Then we have to go back, refining our theory and trying again (and again).  After a while, the narrative, if we are patient and lucky, works. It is not necessary that it fully works. It is necessary that the final results is an appealing theory that can be further tested (or, better, falsified) in other cases and an improvement with respect to the actual knowledge. The steps forward are usually small. 

Tuesday, August 10, 2021

How to learn (La)TeX

 If you want to know an interesting story, go and see what is TeX and why it was produced by Donald Knuth. It is a typesetting system with a language behind it, and the way most scientists who use mathematical formulas, write their paper (and equations). Actually, most of us use LaTeX the Leslie Lamport TeX, which is usually customized to obtain the desired layout by many journals. Native digital used to WYSIWYG can find strange the way it works but after a little practice, no one can really avoid to use it for formulas.



Assuming that I have convinced you (but my students SHOULD agree 😉 ) you have to learn it now. On the web there are many resources. Starting from the quickest,

Obviously there are several video tutorial available. The best thing for gettin them is that you Google "Latex Tutorial Video" by yourself. Any one for beginners can be found here:
Because TeX and Latex have their glorious history, there are several groups promoting them. The oldest one is the TeX user group, or, in brief, TUG

P.S. - Italians can also read the beautiful:

Friday, February 28, 2020

About papers Authorship in Hydrology

Because many often collaborate to a part of a research, it is worthwhile to try to establish some good rule for authorships. A standard text is the one provided by The International Committee of  Medical Journals Editors (ICMJE). I think it gives some reasonable indication which can be adapted where necessary for Hydrological Sciences. Here below you will find verbatim their rules with comments in Italics for Hydrology.

1. Why Authorship Matters

Authorship confers credit and has important academic, social, and financial implications. Authorship also implies responsibility and accountability for published work. The following recommendations are intended to ensure that contributors who have made substantive intellectual contributions to a paper are given credit as authors, but also that contributors credited as authors understand their role in taking responsibility and being accountable for what is published.
Because authorship does not communicate what contributions qualified an individual to be an author, some journals now request and publish information about the contributions of each person named as having participated in a submitted study, at least for original research. Editors are strongly encouraged to develop and implement a contributorship policy. Such policies remove much of the ambiguity surrounding contributions, but leave unresolved the question of the quantity and quality of contribution that qualify an individual for authorship. The ICMJE has thus developed criteria for authorship that can be used by all journals, including those that distinguish authors from other contributors.

2. Who Is an Author?

    The ICMJE recommends that authorship be based on the following 4 criteria:

  • Substantial contributions to the conception or design of the work; or the acquisition, analysis, or interpretation of data for the work; AND
  • Drafting the work or revising it critically for important intellectual content; AND
  • Final approval of the version to be published; AND
  • Agreement to be accountable for all aspects of the work in ensuring that questions related to the accuracy or integrity of any part of the work are appropriately investigated and resolved
Comment: In case of Hydrology, besides the conception, the design and the data, there can be Software writing or Working out the mathematics (when they are present) which should be added to point (1).  However, please be careful to observe that when I say new “software writing”, I mean new software and when I say “Working out the mathematics”, I mean for the first time. We can call Software and Mathematics writers, “Developers”. Developers may reserve the right for the first scientific application of their schemes but not claim to be inserted in any paper using their method or software later on. The citation of the first paper should be  enough in most of the cases. Please also notice that Project Administration and Funding acquisition is usually not considered as a sufficient reason to be co-author.

Therefore for hydrologists, the points for claiming authorship could be:

  1. Substantial contributions to the conception or design of the work; or the acquisition, analysis, or interpretation of data for the work; or software and mathematics development of the work; AND
  2. Drafting the work or revising it critically for important intellectual content; AND
  3. Final approval of the version to be published; AND
  4. Agreement to be accountable for all aspects of the work in ensuring that questions related to the accuracy or integrity of any part of the work are appropriately investigated and resolved.
  5. Corollary: Developers may reserve the right for the first application of their scheme, as well as data providers can claim their first publication.
In addition to being accountable for the parts of the work he or she has done, an author should be able to identify which co-authors are responsible for specific other parts of the work. In addition, authors should have confidence in the integrity of the contributions of their co-authors.
All those designated as authors should meet all four criteria for authorship, and all who meet the four criteria should be identified as authors. Those who do not meet all four criteria should be acknowledged—see Section II.A.3 below. These authorship criteria are intended to reserve the status of authorship for those who deserve credit and can take responsibility for the work. The criteria are not intended for use as a means to disqualify colleagues from authorship who otherwise meet authorship criteria by denying them the opportunity to meet criterion #s 2 or 3. Therefore, all individuals who meet the first criterion should have the opportunity to participate in the review, drafting, and final approval of the manuscript.
The individuals who conduct the work are responsible for identifying who meets these criteria and ideally should do so when planning the work, making modifications as appropriate as the work progresses. We encourage collaboration and co-authorship with colleagues in the locations where the research is conducted. It is the collective responsibility of the authors, not the journal to which the work is submitted, to determine that all people named as authors meet all four criteria; it is not the role of journal editors to determine who qualifies or does not qualify for authorship or to arbitrate authorship conflicts. If agreement cannot be reached about who qualifies for authorship, the institution(s) where the work was performed, not the journal editor, should be asked to investigate. The criteria used to determine the order in which authors are listed on the byline may vary, and are to be decided collectively by the author group and not by editors. If authors request removal or addition of an author after manuscript submission or publication, journal editors should seek an explanation and signed statement of agreement for the requested change from all listed authors and from the author to be removed or added

Comment: The first Author should be the major contributor to the paper. It is a fair policy that Ph.D. student can claim first Authorship for the work coming out from their dissertation. In Hydrology (and in EU funding schemes) is also growing the habit to consider the last Author as the senior Author who possibly provided funding, the starting ideas and the supervision of the work (besides the other necessary requirements).
The corresponding author is the one individual who takes primary responsibility for communication with the journal during the manuscript submission, peer review, and publication process. The corresponding author typically ensures that all the journal’s administrative requirements, such as providing details of authorship, ethics committee approval, clinical trial registration documentation, and disclosures of relationships and activities are properly completed and reported, although these duties may be delegated to one or more coauthors. The corresponding author should be available throughout the submission and peer review process to respond to editorial queries in a timely way, and should be available after publication to respond to critiques of the work and cooperate with any requests from the journal for data or additional information should questions about the paper arise after publication. Although the corresponding author has primary responsibility for correspondence with the journal, the ICMJE recommends that editors send copies of all correspondence to all listed authors.
When a large multi-author group has conducted the work, the group ideally should decide who will be an author before the work is started and confirm who is an author before submitting the manuscript for publication. All members of the group named as authors should meet all four criteria for authorship, including approval of the final manuscript, and they should be able to take public responsibility for the work and should have full confidence in the accuracy and integrity of the work of other group authors. They will also be expected as individuals to complete disclosure forms.

Some large multi-author groups designate authorship by a group name, with or without the names of individuals. When submitting a manuscript authored by a group, the corresponding author should specify the group name if one exists, and clearly identify the group members who can take credit and responsibility for the work as authors. (....)

3. Non-Author Contributors

Contributors who meet fewer than all 4 of the above criteria for authorship should not be listed as authors, but they should be acknowledged. Examples of activities that alone (without other contributions) do not qualify a contributor for authorship are acquisition of funding; general supervision of a research group or general administrative support; and writing assistance, technical editing, language editing, and proofreading. Those whose contributions do not justify authorship may be acknowledged individually or together as a group under a single heading (e.g. "Clinical Investigators" or "Participating Investigators"), and their contributions should be specified (e.g., "served as scientific advisors," "critically reviewed the study proposal," "collected data," "provided and cared for study patients", "participated in writing or technical editing of the manuscript").
Because acknowledgment may imply endorsement by acknowledged individuals of a study’s data and conclusions, editors are advised to require that the corresponding author obtain written permission to be acknowledged from all acknowledged individuals.

Examples of Authorship recognition required by some Journals


1 - Conceptualization, M.B. and S.M.; Methodology, M.B., S.M. and R.R.; Software, M.B., S.M. and R.R.; Validation, M.B. and S.M.; Resources, S.M.; Data Curation, M.B.; Writing—Original Draft Preparation, M.B.; Writing—Review & Editing, M.B., S.M. and R.R.; Supervision, S.M.; Project Administration, S.M.; Funding Acquisition, S.M.

2 - M.B., G.F. and F.S. developed the model code integrated in the GEOframe-SIK 10 package. M.B., F.S., M.B. W.A. designed the experiments and performed the simulations. M.B. and R.R. prepared the manuscript with contributions from all coauthors. R.R. provided funding, supervision and methodology.

3 - S.F. and T.M. designed the study. J.P., R.R., B.S. and M.B. contributed with data. P.H. contributed to the optimization of the parallel simulations. T.M. performed the simulations and the analyses. T.M. designed the figures with contributions from G.M and S.F. The results were synthesized by T.M., S.F., C.P. and P.M. T.M. and S. F. wrote the manuscript with contributions from all other authors.

Tuesday, March 27, 2018

Making a good poster

Everybody fight for having an oral presentation at conferences. However, a poster is often not a bad idea. A poster is like a resume. His scope is not to tell everything about your work, but to attract potentially interested people from who you can have nice conversations, learn something, start a collaboration. To get the general idea of an award winning poster, give a close look to the poster below, that is part of a dedicated page on Nature.
A less traditional layout is the one of the poster to which I dedicated the first post of this year. Finally informative guidelines by:
Obviously, it is assumed that you have something to tell (but this is another topic). 

Wednesday, October 18, 2017

Using Colorblind friendly Plots

Brought to my attention by Michele Bottazzi. I rarely think to this. Instead it is important. Please refers to this Brian Connelly post:

Click on the figure to be redirected. BTW, this was the 500th post!🎉

Wednesday, December 23, 2015

Rejection of Rejection

Dear readers, if you are tired to have your paper rejected, you can consider the send this rejection of rejection letter, whose template has been published on BMJ journal (here) authored by  Cath Chapman and Tim Slade :

Rejection of rejection letter


[insert university emblem here]
Dear Professor [insert name of editor]

[Re: MS 2015_XXXX Insert title of ground-breaking study here]


Thank you for your rejection of the above manuscript.


Unfortunately we are not able to accept it at this time. As you are probably aware we receive many rejections each year and are simply not able to accept them all. In fact, with increasing pressure on citation rates and fiercely competitive funding structures we typically accept fewer than 30% of the rejections we receive. Please don’t take this as a reflection of your work. The standard of some of the rejections we receive is very high.
In terms of the specific factors influencing our decision the failure by Assessor 1 to realise the brilliance of the study was certainly one of them. Simply stating “this study is neither novel nor interesting and does not extend knowledge in this area” is not reason enough. This, coupled with the use of Latin quotes by Assessor 2, rendered an acceptance of your rejection extremely unlikely.
We do wish you and your editorial team every success with your rejections in the future and hope they find safe harbour elsewhere. To this end, may we suggest you send one to [insert name of rival research group] for consideration. They accept rejections from some very influential journals.

Please understand that our decision regarding your rejection is final. We have uploaded the final manuscript in its original form, along with the signed copyright transfer form.

We look forward to receiving the proofs and to working with you in the future.

Yours sincerely

Dr [insert name here]

[Insert research group acronym here]

[Insert university here]

[Insert country here—that is, Australia/New Zealand/small European Country/Canada]



Do not forget to look at the replays.

Tuesday, September 29, 2015

Writing a paper (in hydrologiy or related field) rule by N* L*

... therefore a paper must have:
  • Five sections
  • Five Figures
  • Eight or nine  paragraphs for section
  • Each paragraph must contain a concept
If you use words with synonyms, use the shorter one. 


   These are simple instructions. They are obviously oversimplifications, and assume that you have material to work with. They probably also gives for granted that you know all the others golden rules that you can find, for instance, here. However, if I look at some papers that I am reviewing, I say:  how I like this holy simplicity and clarity.



Monday, August 17, 2015

How to read a scientific paper

The American Society of Plant Biologists took sometimes to put together this little amusing booklet about what is a scientific paper.

Take the time to read it. It useful also to understand what a scientific paper is (and so to write one scientific paper). Not to forget what I already collected in this blog.


Tuesday, July 8, 2014

Quickness and exactitude

I put here an internal review of one of our manuscript, because, I hope, it can be useful in general. The topic is evaluating the rainfall runoff of a small catchment (but I hoped it was en estimation of the global hydrological cycle, even if without evapotranspiration measurements).

"The paper is written in a good English (finally). However good English does not mean is a good paper. It lacks of focus and is not concise (lack of exactitude and quickness, see at the end of the post). Objectives are not clear, and the novelties of the paper not evident. However, I am not desperate to obtain at the end something reasonable: but this just because I know the amount of work behind it, and, in part, the row-material.

Making a rainfall-runoff model cannot be usually considered an exercise at the frontier of our science (citing conversations with Ignacio Rodriguez-Iturbe. However, it could be, as testified by Gunther Bloschl's ERC). It, making rainfall-runoff, I mean, certainly can bring information about a certain basin. However, in our case, the works of N* and M* already filled this space. So what it is the goal of this paper ?
The initial idea was to assess the uncertainty in prediction of discharges by using appropriate statistical techniques. In particular, the idea was to assess the uncertainty inherent to rainfall extrapolation from point measurements to spatial measurements. 
This task has been only partially fulfilled. For the following reasons: errors due to instruments precision were not included (just the hypothesis of perfect functioning measures was applied);  the way rainfall has been included in the model (is not yet clear if average rainfall, one point for each hillslope was used, average rainfall volume for any information or other approximations were utlised: and no sensitivity analysis with respect to the way distribute rainfall was squeezed into the model was performed); the interplay between rainfall and discharge forecasting is not well developed, at least as it could be, i.e. explaining how it works inside the whole procedure is not explained well.  
Therefore the overall rainfall prediction analysis is incomplete, and I expect it would be completed for the thesis. 
The technical novelty we apply in this work is that we use a calibration tool (LUCA) to assess variograms, and we do it at hourly time step, while others do usually at daily time step. A few questions here: how much this approach improves rainfall estimates ? i.e., taking uncalibrated variograms and/or constant variograms (not varying in time) how much difference do we get ? How much this affects the forecasting of the volumes of water? Which comprehensive effect has this on the forecasting of the discharges ?

It could be that all of these approximation have negligible effects on the forecasting of discharges. But this would be indeed good to know and an achievement, which was not obtained so far. 

A second topic of interest was the simulation of the whole hydrological cycle, and a tentative to close the hydrological budget with the Priestley-Taylor simulation of evapotranspiration. This simulations were done but not shown at all in the manuscript. Why not ? Do the simulated discharges and the  simulated ET sum to the total volume of rainfall ? If not, which interpretation do we have about the missing mass ?  Are we able to assess the uncertainty in predictions of each single component of the hydrological cycle obtained with this method? Are we able to observe interannual variability (both in discharges and evapotranspiration, and, if the case, in storage) ? Is this variability estimate reliable, at least as a gross budget ?

Having missed to answer to each one of the questions above the paper results a wandering around that breaks our karma (citation from Vijay K. Gupta).  Please save us with more rigor. 

Regarding quickness and exactitude, I suggest the reading of Italo Calvino's Six Memos for the next Millennium.^1^2

^1 - Here a video seminar on the Six Memos by Paolo Granata
^2 - Hainging around, in a digression maybe, and unfortunately in Italian, the Discorso sulla Matematica (Talk on Mathematics) inspired and guided by Calvino's lectures, written by Gabriele Lolli

Friday, February 15, 2013

The mononota song as a paradigm for writing a scientific paper

This year at Sanremo festival (which I do no follow since many years) it happened that a particular song attracted my attention (because it is actually very tasty): the mononota song. It is from Elio e le Storie Tese. Obviously only the Italians can truly appreciate because the crazy and ironic text is integral part of the whole.

I thought it has a lot of structural similarities with a good scientific paper.  There is a simple statement to show (demonstrate): one can build a nice song using a single note (mono nota). The text of the song contain a literary review (Rossini^1 did it, Bob Dylan^2 too; Tintarella di Luna^3 again) where examples of wrong applications are presented (Jobim^4 implemented a samba where, however, it moved away from the single note: "he did not have the b***s they say"). The musics, besides the text is full of citations.
 It shows various examples of how the statement can be violated.  EelST also demonstrated the possibility of doing it, showing various possible declination of the statement, whistling it, changing rhythms in a way that reminded me certain Frank Zappa compositions, changing the tone, and so on.  The song has also a conclusion were it is remarked that the fidelity to the initial statement was respected, except for the very last note.

Naturally the result is good not for the fact that it follows a schema, but because the song  is , not necessarily the best ever, and not for all tastes, but overall enjoyable. The same applies also to any good paper that needs also to be possibly pleasant to read^5. Eventually the song is likely also to remind a set of other beautiful songs which is also part of the pleasure.

... Just an example.

References

^1 Adieux à la vie (G.Rossini)
^2 Bob Dylan's Subterranean Homesick Blues, I think is mononota. They say that actually many other blues sang by Dylan follow the same type of intonation, for instance  Levee's gonna break which is kind of pertinent with this blog
^3 Mina
^4 Samba de uma nota so (N.Mendonca / A.C.Jobim)
* See also the nice comment by Cesare Picco in his Video (unfortunately in Italian)
^5 I know also papers that are certainly not well written, and not formally enjoyable but that nevertheless eventually convey a lot of information and knowledge: so at the ends the contents are also important by themselves
** Finally in a comment to a The Rolling Stones' song Doom and Gloom  I also got this: "... So do a thousand punk and hip-hop songs; so did Louis Armstrong in his solo on the seminal recording of “West End Blues”; so did Cole Porter in the verse to “Night and Day”; so did Harold Arlen in the refrain to “Come Rain or Come Shine”; and so has Bob Dylan in dozens and dozens of songs since “Subterranean Homesick Blues. Jagger, like both Armstrong and Dylan, is an interpretive artist with the skill and audacity it takes to extract a scale’s worth of colors in just one note. "

Thursday, February 9, 2012

Reproducible Research (and papers)


Many papers I read in hydrology present research that is very difficult to reproduce. Because, as a scientist, I would like to reproduce the results of what I read (this is science, indeed!) some rules should be followed. I found this group of scientists that initiated a Reproducible Research web site, especially directed to image processing colleagues, but easily extendible to Hydrology, and related fields. They offer a how to guide, which is verbatim reported here below:



"Of course, it all starts with a good description of the theory, algorithm, or experiments in the paper. A block diagram or a pseudo-code description can do miracles! Once this is done, make a web page containing the following information:

  • Title 
  • Authors (with links to the authors' websites) 
  • Abstract 
  • Full reference of your paper, with current publication status, and a PDF of your paper 
  • All the code to reproduce all the results, images and tables. Make sure all the code is well documented, and that there is a readme file explaining how to execute it 
  • All the data (images, measurements, etc) to reproduce all the results, images and tables. Add a readme file explaining what the data represent 
  • A list of configurations on which you tested your code (software version, platform) 
  • An e-mail address that people can use for comments and remarks (and to report bugs) 

Depending on the field in which you work, it can also be interesting to add the following (optional) information to the web page:
  • Images (add their captions, so that people know what Figure xx is about) 
  • References (with abstracts)
For every link to a file, add its size between brackets. This allows people to skip large downloads if they are on a slow connection.
For examples, see this list of reproducible papers at LCAV, EPFL. "

Obviously they also link a blog and links to various RR resources. RR, incidentally, the same as my initials.

Now there is also a book about reproducible research made with R by Christopher Gandrud. The chapter can be found here.

Thursday, February 10, 2011

Writing good papers

Writing good papers is matter of having the contents before ("rem tene, verba sequentur").   So I give for granted that you chose a topic which is important (not just because fashionable, but because you humbly assimilated what your community of scientists, and the best among them, thinks it is important) and you have done the right amount of work with solid methods.

However, here, I want to support the idea that a scientific paper has its own structure. The Nature journal has a page with several useful references (here, last accessed February, 9, 2011, as well as all the links below). Other and many resources can be easily found googling "scientific writing" or similar keywords (and you find, for instance this).
However, I am summarizing here a contribution brought to us a few years ago by our friend  Julie Campbell.
She reminded that the general organization of a scientific paper has some standard parts:


Abstract
Introduction and Literature Review (Previous Studies)
Approach and Method(s)
Results and Analysis**
Summary**
Acknowledgments
References


Stanley Malloy wrote a small guide where he defines the previous parts as:


"Abstract: An abstract is a succinct (one paragraph) summary of the entire paper. The abstract should briefly describe the question posed in the paper, the methods used to answer this question the results obtained, and the conclusions. It should be possible to determine the major points of a paper by reading the abstract. Although it is located at the beginning of the paper, it is easiest to write the abstract after the paper is completed.

Introduction: The Introduction should (i) describe the question tested by the experiments described in the paper, (ii) explain why this is an interesting or important question, (iii) describe the approach used in sufficient detail that a reader who is not familiar with the technique will understand what was done and why, and (iv) very briefly mention the conclusion of the paper.

Approach and Methods: Or the Materials and Methods section should succinctly describe what was actually done. It should include description of the techniques used so someone could figure out what experiments were actually done. The details of a published protocol do not need to be reproduced in the text but an appropriate reference should be cited – e.g., simply indicate “were done as described by Hughes et al. (4)”. Any changes from the published protocol should be described. It is not appropriate to indicate volumes of solutions added – instead indicate the relevant information about the experiment such as final concentrations used, etc.

Results: Begin each paragraph with an opening sentence that tells the reader what question is being tested in the experiments described in that paragraph. Write the opening sentence in bold font for emphasis. (Sometimes a complete sentence is used and sometimes a short phrase is used – either style is OK but the style should be used consistently throughout the manuscript.) Any results that include multiple data points that are critical for the reader to evaluate the experiment should be shown in tables or figures. However, the results should be summarized in accompanying text. When referring to a particular table or figure, they should be capitalized (e.g., Table 1, Figure 6, etc.) The text of the Results section should be succinct but should provide the reader with a summary of the results of each table or figure.
Not all results deserve a separate table or figure. As a rule of thumb, if there are only a few numerical results or a simple conclusion describe the results in the text instead of in a table or figure. Your paper should focus on what worked, not things that did not work (unless they didn’t work for reasons that are interesting and provide insights).

Analysis (Discussion): Do not simply restate the results — explain your conclusions and interpretations of the Results section. How did your results compare with the expected results? What further predictions can be gleaned from the results?

Acknowledgments:  Projects or Institution that financed the research, reviewers that helped. People with whom the topics treated were discussed appear cited here.

Reference lists: Like citations, a variety of reference formats are used by different journals. For an example of a commonly used example, see “Instructions to authors” on ASM web site (http://jb.asm.org/misc/ifora.shtml) or examples from published manuscripts. "

Citations: It is essential to credit published papers for work mentioned in your manuscript. - RR Note: There are no many other rewards than being cited. So as you like to be cited, do not forget those from whom you learned something - There are a variety of ways of citing references in the text – the style used depends upon the policy of the journal. In text citations should refer to reference list. Do not rewrite title of references in text. "





Julie provided a nice hand-out in her lecture and here it is an excerpt regarding figures: create Tables and Figures that stand-alone.


"The tables and figures that you place in a scientific paper should be able to be understood mostly, if not completely, whether or not your reader reads the accompanying text. Therefore, contents should be clearly labeled and units of measure specified. Use only abbreviations of terms that will be clearly understood by your readers; otherwise, spell out terms. Keep in mind that even though you have defined abbreviations of terms in your text, including equation variables, the table or figure will not stand alone unless you redefine them in your table or figure, being consistent with the abbreviations that you have used in your text.

For figures, specifically plots, there should be a key for symbols used. Also, there should be fully explanatory axis labels that include the units of measure. Recall that the y axis
often begins at zero, but it if does not, you should consider, depending upon who your readers are and the nature of the quantity, calling that fact to your readers’ attention in your caption."

Example: From Gutierrez-Magness and McCuen.


(Notice that the graphic key is easier to comprehend than a verbal description of the line types and/or symbol types would be. Regarding the issue of standing alone, this figure basically satisfies some of the requirements for standing alone. It does, however, need further notation explaining what kind of data has been analyzed, as well as the region, the year(s), and the type of instrument used.)

Example: From “Distributions-Oriented Verification of Ensemble Streamflow Predictions” by A. Allen Bradley, Stuart S. Schwartz, and Tempei Hashino, Journal of Hydrometeorology 5 (2004): 532-545.


(Note the key for the symbols, as well as the notation that provides information about the data in question and its units, as well as the year. Note also the somewhat unusual abbreviation of September, which is traditionally abbreviated, Sept. In this case, the logarithmic scale must start at 1000. In general, this figure satisfies the requirements for standing alone.)


Example: From “Heavy Rainstorms in Chicago: Increasing Frequency, Altered Impacts, and Future Implications,” by Stanley A. Changnon and Nancy E. Wescott, Journal of the American Water Resources Association 38.5 (2002): 1467-1475.


(Note the detailed information in the title that aids the table in standing alone. Note that in the labels, the numbers 2 through 10 have been spelled out, while those numbers greater than ten are given in their numeric form. Many style guides request this differentiation. In general, the rule goes as follows: “Technical quantities of any amount are expressed in numerals. Nontechnical quantities of fewer than 10 are expressed in words. Nontechnical quantities of more than 10 are expressed in numerals” [Markel p. 644]. Needing clarification, however, are the last two rows—the third row indicates the maximum number of storms in a year, and the fourth row indicates that the specific year in question is 2001, but this information is essentially part of row three.)

For more information, see Ch. 14 in Markel on “Creating Graphics,” especially, “Creating Effective Tables,” pp. 333-335.

And more from Julie's handout

I. Notes from Article Excerpts: “Advances in the Use of Observed Spatial Patterns of Catchment Hydrological Response,” by Rodger B. Grayson et al, Advances in Water Resources 25 (2002): 1313-1334.

--Collective nouns—use a singular verb when the parts of the group act as one unit; use a plural verb when the parts of the group act individually. Example: the jury have/has reached a verdict. Note: the expression “a number of” means “several” and needs a plural verb.

--Parallelism—the repetition of a grammatical structure. It suggests similarity between ideas and creates symmetry and balance. A parallel construction repeats an identical grammatical pattern within the same sentence, paragraph, or passage. Sentence examples: a) In this study we will focus on examining the parameters of . . . , calculating the difference between . . . , and explaining how the different patterns signify . . . .
b) The first goal is to acquire the necessary data. The second goal is to calculate . . . . Finally, we hope to show . . . . c) Our study encompasses the derivation of . . . , the illustration of . . . , and the conclusions that we draw . . . .

--Revision of Second Sentence, Intro. Paragraph:
Original—“But these have served more to consolidate the work of the 1990s and propose new methodological advances, rather than focus on new data sources.”
Revision—“These, however, have served more to consolidate the work of the 1990s and (to) propose new methodological advances than to focus on new data sources.”

--Revision of Third Sentence, Intro. Paragraph:
Note: the comma is required before “and” in this case because the author is combining two “independent clauses” with a conjunction.
“Nevertheless, the calls of the 1980s and early 1990s for more research into representing spatial heterogeneity, the collection of data sets for the testing and development of distributed models, and methods how to best deal with issues of scale, have to some extent been heeded, and it is these on which we will focus in this paper.”

--Revision of Results Paragraph:
--See “trade-off”
--Why is it incorrect to place a comma before “and” in the last sentence?

--Revision of Summary Paragraph:
--How could we rewrite for parallelism here?

II. Punctuation Review, American English

--Most common punctuation errors:
A) The comma splice—links two independent clauses (clauses that could stand alone as sentences) with only a comma.
Incorrect: This report was distributed widely in the U.S., its findings were considered groundbreaking.
Correct: This report was distributed widely in the U.S., and its findings were considered groundbreaking.
This report was distributed widely in the U.S.; its findings were considered groundbreaking.
This report was distributed widely in the U.S.: its findings were considered groundbreaking.

B) The run-on or fused sentence—contains two independent clauses with no dividing punctuation.
Incorrect: The internal temperature reached 30 degrees we stopped the experiment at that point.
Correct: The internal temperature reached 30 degrees, so we stopped the experiment at that point.
The internal temperature reached 30 degrees; therefore, we stopped the experiment at that point.
The internal temperature reached 30 degrees. We stopped the experiment at that point.
Also: When the internal temperature reached 30 degrees, we stopped the experiment.

C) The sentence fragment—is an incomplete sentence; some grammatically necessary part is missing.
Incorrect: The drop in temperature caused by a leak in the canister.
Correct: The drop in temperature was caused by a leak in the canister.

Note: In the “Appendix: Reference Handbook,” in Markel (see bibliography below), there is an excellent section on “Editing Your Documents” that covers most aspects of punctuation and grammar.

III. Use of Acronyms and Initial Abbreviations

--An acronym is a word consisting of initials and pronounced as a word, for example, NATO—North Atlantic Treaty Organization, SAR—Synthetic Aperture Radar, or GRASS—Geographic Resources Analysis Support System

--An initial abbreviation consists of the first letter of each word in a phrase or name, for example, GPS—global positioning system or GIS—geographic information system.

IV. Use of Prepositions

-- Prepositions are the words that link and establish specific relations among words or group of words. In some cases, usage is highly idiomatic—in other words, there are few clear rules!
A. Prepositions of Place (literal and figurative)
a. in—in the picture, in the photo, in the paragraph, in the sentence, in the equation, in front (of), in the process (of), in New York, in fact, in place (of), in existence
b. on—on the map, on the page, on the subject, on the edge, on purpose, on top (of), on site, on the contrary
c. at—at the corner, at the intersection, at a glance, at least, at these coordinates, at one time, at work

B. Prepositions of Duration
a. for—for a while, for three days, for a week
(also: a need for, a desire for, for that reason, for instance)
b. while—while we calibrated the...., while I was watching...., while we measured....
c. during—during class, during the experiment, during the day

C. Prepositions of Time and Date
a. in—in a couple of weeks, in February, in time (for)
b. at—at seven o’clock, at Christmas, at sundown, at first
c. on—on Christmas day, on Tuesday, on schedule

Common Words and Phrases Used as Prepositions: about, above, according to, across, after, against, ahead of, along with, among, around, as, as for, at away from, because of, before, behind below, beneath, beside, between, beyond, by, concerning, due to, except, except for, for, from, in, in addition to, in back of, in case of, including, inside, inside of, in spite of, next to, of, off, on, onto, on top of, other than, out, out of, outside, over, past, regarding, through, to, toward, until, unlike, upon, up to, with, within, without

Note: See sections on prepositions in books listed in the bibliography below.

V. Use of Idiomatic Expressions

--Idioms are words, phrases, or expressions that are either grammatically unusual or they convey a meaning that is different from the literal meaning of the term or phrase. Examples: “the big picture”, “to warm up to someone”, “a cold fish”...

Note: A convenient source for help with idiomatic expressions in English may be found at http://english-zone.com/idioms/dictionary.html.

These sorts of expressions are interesting and useful to know in general, but have limited use in scientific and technical writing because of their lack of univocal meaning in some cases.

VI. Use of Capitalization
--For help with standard practices of capitalization in English, see one of the recommended handbooks in the bibliography below.

VII. Use of Precise Terms to Avoid Ambiguity
--When writing a technical paper, it is critically important to be as specific as possible. Avoid using imprecise words and terms (e.g., a lot, some, a few, an insignificant amount), and if you must use them, be sure to follow them with the precise explanation of what you mean. Use precise words and terms (e.g., 300 meters to the west, 40 degrees warmer than the previous measurement, two key points) whenever possible.
--See pp. 251-251 and pp. 625-627 in Markel, as noted in the bibliography below.

VIII. (Addendum) Writing “Mathematical English”
--When you incorporate an equation into your writing, you should remember that the parts of the equation function as parts of speech. Therefore, the equation and its parts require appropriate use of punctuation, as well as grammatical consideration.

--Variables used in the equation all need to be defined.

Typical errors include the following:
-- Misuse of the colon (:) to introduce every inset equation, no matter the grammatical structure of the sentence which incorporates the equation.
--Capitalization of linking words following the equation that are actually already in the middle of a sentence, such as where, therefore, thus, so, if, and that.
--Failure to follow the equation with a comma preceding the “where...” phrase because in this case, the “where...” phrase is a nonrestrictive element of the sentence.

Example: From “Recent Developments in Statistical Time Series Analysis: Examples of Use in Climate Research” by F. Godtliebsen, L.R. Olsen, and J.-G. Winther, Geophysical Research Letters 30.12 (2003): 56-1—56-4.

A relevant nonparametric regression problem for this is to attempt to use data of the form
where m(x) is the target curve. Here, we assume that the xi are equally spaced on the range of x, that m is smooth and that the εi are independent Gaussian variables with mean 0 (which makes m the regression curve of yi on xi) and variance Var (εi) = .

(Note that there is no colon introducing the equation, and “where” is not capitalized. A comma, however, should be placed after the equation.)


Example: From “Accuracy Evaluation of Rainfall Disaggregation Methods” by
Angelica L. Gutierrez-Magness and Richard H. McCuen, Journal of Hydrologic Engineering ASCE 9.2 (2004): 71-78.




(Note that there is no colon after “by.” Note also that elements which could stand alone as “mathmatical sentences” are set off with semicolons.)


For more information on “Mathematical English,” see the American Institute of Physics Style Manual at http://www.aip.org/pubservs/style/4thed/toc.html

Bibliography

--Anderson, Paul V. Technical Communication: A Reader-Centered Approach. 5th ed. Thompson/ Heinle, 2002.
--Fulwiler, Toby and Alan R. Hayakawa. The Blair Handbook. 4th ed. Upper Saddle River, NJ: Prentice Hall, 2003.
--Hacker, Diana. A Writer’s Reference. Bedford Books, 2003.
--Hacker, Diana. A Pocket Style Manual. Bedford Books, 2003.
--Markel, Mike. Technical Communication. 7th ed. Boston: Bedford-St. Martin’s, 2004.
--Strunk, William and E.B. White. The Elements of Style. 4th ed. Pearson Higher Education, 2000. See also: http://www.bartleby.com/141/strunk5.html

External links

See the beautiful presentation by Jeffrey McDonnell

And find here the clarification of co-authorship responsability

Here the Thomas Hengl guide to write a paper

The mononota song as a paradigm for writing a good paper