Subject: Publication policy

From: bacock
Date: Fri, 8 Jul 1994 08:43:15 +0500

Policy for the Electronic Journal of Terrestrial Ecosystems Software

I have now updated my earlier notes on a proposed policy for an electronic 
journal.  Most of the changes resulted from discussions with interested
people at the Agronomy meetings in Cincinatti last November.  I welcome your 
comments on this new draft.  We must make EJTES serve the needs of our 
scientific community.

Basil

NAME OF JOURNAL
Electronic Journal of Terrestrial Ecosystems Software
The name recognizes that agronomy is increasingly being seen as the management 
of a crop ecosystem, and that agronomists have much in common with ecologists 
who are trying to understand natural or unmanaged ecosystems.

PURPOSE OF THE JOURNAL
The purpose of EJTES is to record, in forms that can be stored and
manipulated in computers, both old and new scientific knowledge 
about managed and unmanaged terrestrial ecosystems so that we can sustain a 
high yield of food, fiber, and timber, with the minimum detrimental impact 
on the environment.

ARTICLES ACCEPTED FOR PUBLICATION
EJTES will publish articles on all types of original software 
relevant to terrestrial ecosystems, including whole models, descriptions of 
model structures, objects from object-oriented models, modules, algorithms 
describing a well-defined process or group of processes, important 
functions, expert systems, and significant databases.  Some examples 
of acceptable software are (a) an algorithm describing 
photorespiration, (b) a function defining solar declination, (c) a set of 
data summarizing the properties of soils over a large enough area to 
be of general interest.  EJTES will also publish articles on the validation 
of published models along with the full validation data set, notes on reader's  
experience with commercial software relevant to modeling and data manipulation, 
and philosophical discussions about the methodology of software development.

The journal will mainly publish models of the type known variously 
as mechanistic, process-level, or explanatory. Completely empirical 
models will be published if they can be demonstrated to have good 
predictive ability for the intended application.

GENERAL STANDARDS
The software may be written in any language, and authors are asked 
to supply the names and addresses of three potential reviewers who 
are familiar with the language.  However, authors are reminded that 
the purpose of the journal is to record and communicate scientific 
knowledge, and so the use of common languages is encouraged.

SI units must be used, although other units will be accepted if (1) the 
original work was done in those units and there is no exact SI 
equivalent, or (2) the units have been chosen for their familiarity to 
the intended user.  In these cases, the factors for converting to the SI 
units must be given when the other units are first mentioned.

Descriptive text should meet normal journal standards for good 
English.  It should be possible for people who cannot read the code to 
nevertheless understand what the software does and how it is done.

The text of the article should be in lower-case letters with upper-case as 
appropriate; comments in the code should preferably take the same form.  Text 
consisting solely of upper case letters is hard to read and will not be 
accepted.

The text and figures may be prepared using any of the authoring packages 
that run in DOS, WINDOWS, UNIX and MACINTOSH.

INFORMATION TO BE INCLUDED IN ARTICLES SUBMITTED  
For all articles, authors must supply (a) a title, (b) names, affiliations, 
telephone numbers, and computer network addresses (if any) of the 
authors, (c) a list of key words chosen from the master list supplied by the 
editors, (d) an abstract stating briefly the purpose of the work, the need for 
it, and any special features, and (e) references to literature cited.

For all articles on software, authors must also supply (a) a statement of any 
critical assumptions and/or limitations, listed in order of 
importance, (b) the name of the computer language in which the 
code is written and (c) the compiler(s) and compiler 
version number(s) used to run the code. 

For articles on models, modules, objects, algorithms, and functions, authors 
must also supply (a) a complete description of what the code does, with 
sufficient documentation to trace the origin of the ideas it contains, 
(b) a dictionary defining all the variable and parameter names and 
their units, (c) at least one set of test data, both input and output, 
and (d) the code itself, liberally annotated with comments that state 
the function of the subsequent (or previous) equations and are 
sufficient to serve the same purpose as pseudo-code or a flow 
diagram. [Pseudo-code is a flow diagram in words, i.e., without 
the boxes and arrows.] If a piece of code supplies default values for 
some variables, these values must be specified in the text or in a 
table.  Each module of code must be labeled in a comment with a name, version 
number and date.  

For articles on expert systems, authors must also supply (a) the name 
of the inference engine, if it is available commercially or has already 
been published, or the code of the inference engine, (b) the 
knowledge base, either in the form of original code, or as a set of 
IF...THEN statements in English, (c) sufficient  documentation to trace 
the origin of the ideas contained in the knowledge base, (d) a 
dictionary defining any variable names and/or abbreviations that 
are used, and (e) examples of the use of the expert system to 
demonstrate its capabilities.

For all articles that include databases, authors must also supply (a) a 
data dictionary (complete description of what the database contains 
with formats and abbreviations), (b) examples of how to access the 
data, and (c) enough information about how the data were collected 
that readers can assess their quality.

For articles on model validation, the data set collected must be 
sufficiently detailed to run the model and to locate any problems in 
the model.  It is not enough to report that the model failed to predict, 
say, biomass without indicating why it failed.  The complete data set 
should be recorded along with a data dictionary.

In order to make the data sets generally useful, whatever the model 
being validated, data collected to validate models of animals, plants, 
insects, and disease organisms preferably will include (a) a full 
record of the environment experienced by the organism, (b) details 
of all human intervention in the system and of unusual events, and 
(c) appropriate observations of the organism at intervals over a 
period of time.  A full record of the aerial environment would consist 
of at least (a) daily solar radiation incident on the organism, (b) daily
maximum and minimum air temperature, and (c) daily rainfall.  A 
complete description of the soil environment would consist of at least 
(a) depths of the major soil horizons, (b) for each horizon: particle 
size analysis, bulk density, water release curve, and saturated 
hydraulic conductivity, (c) nutrient content at the start of the season, 
(d) organic matter content at the start of the season, and (e) soil 
temperature at a depth of 2 m or more.  For models of pest 
organisms, it is also important to record the condition of the host 
organism as this partly or wholly defines the environment of the 
pest.  Details of human intervention might include (a) water supplied, 
(b) nutrients supplied, (c) cultivations, (d) pesticides applied, (e) 
other forms of environment modification, and (f) modification of the 
organism and its physiological responses by surgery, drugs, 
hormones, etc.

PREPRINT PUBLICATION
Authors can choose to have their articles published as "unreviewed preprints" 
in EJTES.  Prior to posting the articles, the editors will ensure that they 
contain  the information requested above.  Articles can also be published as 
preprints while they are being reviewed, then, after review and amendment, 
their classification will be changed to that of "peer-reviewed publications."  
The editors will experiment with using preprint publication as a way of finding 
reviewers who have a special interest in each article.  

ORIGINALITY AND NOVELTY
To be acceptable for publication, the software and its documentation should not 
have been published previously in any journal, book, or bulletin likely to be 
found on the library shelves in the majority of biological institutions.  
(Using this criterion, very little terrestrial ecosystem software has yet been 
published.)  Descriptions of the general capabilities of the code in paper 
journals will not be considered prior publication, and such publication is 
encouraged to bring the work to the attention of a wider audience.  It will not 
be considered inappropriate if articles in EJTES, that fully disclose code and 
documentation, include descriptive material that has already been published in 
paper journals by the same authors.

The software should also (a) record some knowledge not previously 
captured in code, or (b) treat some process more comprehensively 
than earlier code, or (c) incorporate recent advances in our 
knowledge about a process, or (d) be valid over a wider range of 
cases than earlier code, or (e) be more efficient than earlier code.

Since code reuse is encouraged in modern practice, many contributions to EJTES 
are expected to consist of amendments to previously published code.  In these 
cases, originality is difficult to define exactly and reviewers will have to 
exercise their judgement, but a contribution should normally contain less than 
50% of code from any one other existing source.  Code reused from another 
source must be clearly labeled with comments at the start and finish, and 
attributed to the original authors.

PEER REVIEW AND PEER COMMENT
Before publication each article will be reviewed by two people 
familiar with the subject matter  They will be asked to review the article 
for compliance with the criteria above, to make private 
recommendations to the editor about its acceptability, and to write 
brief statements about its strengths and weaknesses for publication 
with the article.  The reviewers will be responsible for checking the 
scientific value and/or scientific content of the article, but not for 
checking the performance or integrity of any software included.  
These remain the sole responsibility of the authors.  In fact, the 
reviewers should be able to assess the value of the article even if 
they cannot run the software or read the computer language in 
which it is written.

The journal editors will, as far as possible, run all software to check 
its performance, and have a programmer examine it for obvious errors.  
Any errors encountered will be communicated to the authors as part 
of the review process.

The public comments and names of the peer reviewers, along with any rebuttal 
by the authors, will be published with the article.  Appended to each 
article will be a file for brief constructive comments from users of 
the software.  Comments should be submitted to the editor for 
screening.  Comments about a supposed failure of code in a given 
situation should identify the reason for the failure and should 
preferably refer to an article validating the code.  The editor will 
not publish comments that are not constructive.

TECHNICAL PROCEDURE
Authors will prepare articles for publication on their own computers 
and send them as personal mail to the editor, [email-masked].  If 
this method of delivering the article is impossible, the editor will accept 
the article on 3.5" diskettes in MS-DOS, Windows, UNIX and MacIntosh formats.
Postscript or ASCII files are preferred.

The editor will scan the article for gross compliance with publication 
policy, post it as a preprint if so requested by the author(s), and make 
the article available to two reviewers.  When the article has been 
accepted for publication, it will be given a publication number and 
entered in the journal directory where it will be accessible 
immediately to everyone.  The article will be referenced by journal 
name, year and publication number, and its length indicated by the 
number of kilobytes.

ACCESS TO THE JOURNAL
(Depends somewhat on the organization adopted for EJTES)
Titles, authors' names and keywords may be searched on-line at the ASA 
computer.  The search will produce scrollable lists giving for each article 
found: title, author(s), affiliation(s), and abstract.  Individual articles 
may be copied to the reader's computer.  Each article will have hypertext 
capability for accessing tables, figures, etc. from the text.  Each
reader will need a copy of the Acrobat READER's software relevant to his/her 
machine.  

Back issues of the journal will be made available on CD-ROM 
eventually.

MASTER LIST OF KEY WORDS
The editors will develop a master list of key words for authors to use in 
classifying their articles.  This master list of key words will act as an index 
and will ensure that readers find all relevant articles when they search the 
journal.  The master list will be expanded as needed.  Authors may suggest key 
words to be added to the list.

QUARTERLY BULLETIN
At the end of each quarter, a photocopied bulletin will be mailed to 
individuals and institutions that have indicated an interest.  The 
bulletin will contain the title, author(s), affiliation(s), and abstract for 
each article published during the quarter.  The bulletin will also contain 
letters to the editor and news of coming events that are relevant to the 
readers of EJTES.  (The editors will explore the possibility of including this 
information in Agronomy News and similar society newsletters rather than 
starting a new bulletin.)

MASTER LIST OF KEY WORDS 
(I am still not sure how to present this master list.  At present, I see it as 
a set of interlinked sub-lists that are mostly hierarchical but use hypertext 
to access some sublists that are common to several parts of the hierarchy.  
For example, the sublist of plant species would be accessed from both the 
"expert system" and "model" branches of the hierarchy.  What follows is an 
example just to convey the idea.)

Type of article:
database  (if selected, sends reader to sublist: Type of database)
expert_system
model
review_of_commercial_software
discussion_of_methodology

Type of database:
weather
soil
plant  (if selected, sends reader to sublist: Plant)
animal

Plant:
plant part
plant process
plant species (if selected, sends reader to sublist: Plant species)

Plant species:
maize
potato
rice
(My problem is that some but not all of the selections should be keywords for
the article.  "Database" and "plant" are OK, but "plant species" is not.  The
last is just a way of getting to the list of plant species.  Maybe the words included only to give access to other sublists should be marked in some way.)

END OF FILE