From bacock  Fri Jul  8 08:43:15 1994
Return-Path: <bacock>
Received: by ncsr (5.0/SMI-SVR4)
	id AA01399; Fri, 8 Jul 1994 08:43:15 +0500
Date: Fri, 8 Jul 1994 08:43:15 +0500
From: bacock
Message-Id: <9407081243.AA01399@ncsr>
To: ejtes@arsusda.gov
Subject: Publication policy
X-Sun-Charset: US-ASCII
content-length: 15006

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, bacock@asrr.arsusda.gov.  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


From bacock  Fri Jul  8 08:45:00 1994
Return-Path: <bacock>
Received: by ncsr (5.0/SMI-SVR4)
	id AA01550; Fri, 8 Jul 1994 08:45:00 +0500
Date: Fri, 8 Jul 1994 08:45:00 +0500
>From: bacock
Message-Id: <9407081245.AA01550@ncsr>
To: ejtes@arsusda.gov
Subject: Journal appearance
X-Sun-Charset: US-ASCII
content-length: 2410

The look and feel of EJTES:

An electronic journal has some disadvantages compared with a paper journal:
you can't easily stuff it in your pocket, read it in bed, or riffle through 
the pages to find some page whose layout you remember; but it also has some 
advantages: easy to search, and supports hypertext interlinking.  I think we 
need to fully exploit the advantages to make the new journal acceptable to our 
readers.  The following are my ideas about the appearance of EJTES to readers 
and how this appearance can be achieved.  From discussions with Tony Trent, I 
believe these ideas can be implemented in Adobe Acrobat, but our primary aim 
should be to find the ideal appearance at this stage.  Can you improve on these 
ideas?

Basil

ACCESS TO EJTES

Readers will log on to the ASA computer.  Initially, the ASRR computer at 
Beltsville will double as the ASA computer.  The first screen will be a fixed 
screen with a banner for EJTES and ASA.  Below that there will be "hot" 
hypertext buttons for "publication policy", "list of keywords", "boolean 
search of journal" and "titles published in past year."  Choosing "boolean 
search..." will produce a fixed screen with a data entry window where the 
keywords and logic words can be entered.  A boolean search, or choosing 
"Titles published in past year" will produce a scrollable list of articles 
with Title, author(s), affiliation(s), and abstract.  There should be some 
simple way of marking articles in the list for downloading to the reader's 
own machine.  The full text of an article will only be accessible by 
downloading the article.  This is to prevent people bogging down the computer 
and modems by reading articles on-line.  

LAYOUT OF ARTICLES as seen in reader's own computer

As normally prepared for submission to paper journals: with the text going the 
full width of the page (single column) and tables and figures separate from the 
text.  The captions would be included with the figures and tables.  In the 
text, references to tables and figures would be hot buttons which would call 
up the thing referenced.  Each table and figure would have a button to return 
the reader to the text.  Immediately under the title, authors and affiliations 
would be hot buttons to jump the reader to major subdivisions of the article, 
e.g. abstract, main text, code, etc.  All text should be in scrollable windows.

END OF FILE


From bacock  Fri Jul  8 09:00:35 1994
Return-Path: <bacock>
Received: by ncsr (5.0/SMI-SVR4)
	id AA01724; Fri, 8 Jul 1994 09:00:35 +0500
Date: Fri, 8 Jul 1994 09:00:35 +0500
>From: bacock
Message-Id: <9407081300.AA01724@ncsr>
To: ejtes@arsusda.gov
Subject: Comments from John Thornley
X-Sun-Charset: US-ASCII
content-length: 3254

Comments from John Thornley

In an earlier message to me John made the following points which I think are of interest to the whole group.

Basil

The Electronic Journal of Terrestrial Ecosystems Software

Publishing models is a pain at present and is thoroughly unsatisfactory.
Therefore let's try something different.  Maybe it'll work and maybe it won't.
So count me in.

I'll give you some of my views on publishing models.

1. Other people's programs are usually difficult/impossible to understand.
The most important thing about the write-up of a model is 
(not that it should be "validated" or some such stuff, but)
that it should be understandable - as transparent as possible.
Then people can decide what bits, if any, to use themselves.

2. If only everyone had taken on board the stuff de Wit was saying
25 years ago.  Define your state variables (with initial values),
define the difference/differential equations, and last give the
rate processes equations with parameter values.  Some referencing of why
is helpful but this need not be exhaustive.

3.  I still find a mathematical statement the clearest to understand.
(If only so many biologists/ag engnrs hadn't learnt computer programming
before learning maths.)  I am always delighted when people take one
of my models, and code it up directly from the maths, and it works.
And this has happened more than once.  Computer languages will go on
changing for a while yet - therefore a computer coding is only of
transient value.  A mathematical description has a much longer life.

4.  You ask for text etc in ASCII.  I guess me and many colleagues 
write our ms's in WordPerfect or Word which have pretty good eqn writers. 
We could print/postcript our files and get an ASCII file.  But these files
probably aren't of much use electronic journal-wise.
In the US, LATEX or something like it seems to be more widespread
than over here.  I guess some people who use say WordPerfect for
letters, reports, ms's etc would not want to switch and start climbing
up some new learning curve.  I don't know what the NAPLPS standard is.

5.  Software.  Fortran is widely used but it is a lousy language for
ecosystem software.  An ecosytem/crop model is the ultimate
parallel process, and fortran is not good for parallel processes.  
Some people use a variety of special simulation languages, mostly because
they know their way around them and it makes model coding much easier
than in fortran.     I use ACSL at presemt - more or less a successor
to CSMP.  But ACSL software costs $$$ and most people can't run my
programs.  Nothing is perfect.  I simply can't see busy people
spending much time running other peoples models with all the
problems that would arise.  Big models can be desperate things to
work with - even when you've built them yourself.
 
6.  Refereeing.  With recent changes in the UK research scene there
are very few possible referees of ecosystem models.  I already am
sent more stuff than I want just because competent modellers are so
thin on the ground.  I suppose things are a bit more robust where
you are with more possibilities.  

I guess much of this seems pretty negative, but there is a logjam in
publishing modelling work, and someone has to try and break it.

John


From bacock  Fri Jul  8 08:37:20 1994
Return-Path: <bacock>
Received: by ncsr (5.0/SMI-SVR4)
	id AA01241; Fri, 8 Jul 1994 08:37:20 +0500
Date: Fri, 8 Jul 1994 08:37:20 +0500
From: bacock
Message-Id: <9407081237.AA01241@ncsr>
To: ejtes@arsusda.gov
Subject: Update on progress
X-Sun-Charset: US-ASCII
content-length: 1964

Friends,

Its time for us to seriously consider the publication policy for EJTES, and
the appearance of the journal to readers.  Since there has been no activity 
on this conference for several months, let me summarize what has happened so 
far.

The Board of the American Society of Agronomy has issued letters of invitation 
to Jim Reynolds, Rien van Genuchten, Steve Running, Fritz Penning deVries, 
John Thornley and myself to constitute the Editorial Board of EJTES.  Tony 
Trent will be the Technical Advisor to the Board.  All the above agreed to 
serve.  Joe Landsberg also agreed to serve if invited by the ASA but I did 
not have his consent in time for the first batch of letters.  Members of the 
Board were chosen for their experience in software development, their name 
recognition, their ability to represent several continents and various 
disciplines, and the credibility they would give the journal.  We have to get 
people to take us seriously, and I think they will.

However, many other people have worked towards establishing EJTES and we want 
everyone with an interest to continue working with the Editorial Board to 
ensure this journal meets the needs of ecosystem software developers.  

Tony has been testing Adobe Acrobat without finding any problems.  It is now 
available on UNIX as well as DOS, Windows and MacIntosh.  He has a student 
setting up some articles for us to look at, but would like some discussion of 
the desired appearance of the journal.

Following this note I will be posting draft statements on publication policy 
and the appearance of EJTES to get some discussion going.

There is a conference on Electronic Publication to be held on the McGill 
University Campus, Montreal, August 12-13, 1994.  Steve Rawlins and I both 
have prior commitments and cannot attend.  Is anyone else free to go and 
interested in reporting back to the rest of us?  I may be able to help 
financially, if that is a problem.

Basil


