The structure of a digital research object

[khinsen]

A discussion started on another issue by @Repositorian, which deserves its own issue.

[khinsen]

@Repositorian raises a couple of issues which are not in the core objective of everpub as I see it, but which we need to take into account in some way, if only by deciding to look at them later. BTW, I have explored some of this issues in my ActivePapers project and discussed them in this paper.

I see the core objective of everpub as providing technology, i.e. software tools, for the creation of computational documents that allow interactive manipulation. Obviously these documents will have some internal structure. From an implementation point of view, each document consists of a computational environment, software libraries, notebooks, and documentation. However, this implementation-oriented structure is not necessarily reasonable from different points of view, such as referring to specific pieces from other research objects. Today it is common in a paper to refer to "Equation 5 of reference 15". In computational papers, such references should still be possible, and even be more versatile. I might want to refer to a dataset, a cell in a notebook, or a line in a code module, either for (computational) reuse or simply for discussing the science in some detail.

These preoccupations are largely orthogonal to the technical core objectives, so we can just brush them aside for now. The main risk is that everpub becomes an instant success and computational documents will not be citable for the next 10 years because we didn't think about it. If you consider this unlikely, read a bit about this history of JavaScript.

At some point we will have to think about the "publishing object model" that @Repositorian refers to. Of course others are working on this as well, and it would be good to keep an eye of what is happening. Or we decide that this is somebody else's problem, and encourage people to play with different object models inside the everpub platform.

[betatim]

Hadn't thought about this before and the question of how you refer to
something that isn't a figure, table or equation is interesting. Would you
want to reference things at the cell, file, line, function, module, library
level? Probably the answer is "it depends".

On Sat, Mar 5, 2016 at 7:30 PM Konrad Hinsen notifications@github.com
wrote:

@Repositorian https://github.com/Repositorian raises a couple of issues
which are not in the core objective of everpub as I see it, but which we
need to take into account in some way, if only by deciding to look at them
later. BTW, I have explored some of this issues in my ActivePapers project
and discussed them in this paper
http://f1000research.com/articles/3-289/v3.

I see the core objective of everpub as providing technology, i.e. software
tools, for the creation of computational documents that allow interactive
manipulation. Obviously these documents will have some internal structure.
From an implementation point of view, each document consists of a
computational environment, software libraries, notebooks, and
documentation. However, this implementation-oriented structure is not
necessarily reasonable from different points of view, such as referring to
specific pieces from other research objects. Today it is common in a paper
to refer to "Equation 5 of reference 15". In computational papers, such
references should still be possible, and even be more versatile. I might
want to refer to a dataset, a cell in a notebook, or a line in a code
module, either for (computational) reuse or simply for discussing the
science in some detail.

These preoccupations are largely orthogonal to the technical core
objectives, so we can just brush them aside for now. The main risk is that
everpub becomes an instant success and computational documents will not be
citable for the next 10 years because we didn't think about it. If you
consider this unlikely, read a bit about this history of JavaScript.

At some point we will have to think about the "publishing object model"
that @Repositorian https://github.com/Repositorian refers to. Of course
others are working on this as well, and it would be good to keep an eye of
what is happening. Or we decide that this is somebody else's problem, and
encourage people to play with different object models inside the everpub
platform.

—
Reply to this email directly or view it on GitHub
#113 (comment)
.

[khinsen]

"It depends" and "time will tell". We can't rely on much experience with this. The difficult references are those for use by a computer program. Humans adapt to anything that's reasonably clear.

In ActivePapers, I use references at the HDF5 dataset level. This has proven sufficient but until now all ActivePapers I know of are supplements to traditional papers, containing no narrative of their own.