codeisscience / manifesto Goto Github PK

• http://sciencecodemanifesto.org/

It seems to me that there is some common ground but also a little different Focus. Maybe it could be worth to point it out?

Ideas include:

• Sharing and asking people to sign up on Twitter
• Keep talking about the Manifesto and its importance at workshops and events
• Printing stickers and asking people to be ambassadors of the Manifesto
• Write a blogpost (#6)
• Write a paper

Currently there is no line width on manifesto.md which makes the diffs slightly harder to read. For example: https://github.com/codeisscience/manifesto/pull/28/files looks like a long diff but is just a single word added to the sentence.

If it's helpful to put in a max width (the markdown still renders fine): I'm happy to PR this.

I very much like the spirit of this manifesto! But as so often, the devil is in the details.

My main problem with the current version is that there are different types of code involved in doing science, but the principles cited in the manifest cannot be applied straightforwardly to all of them.

Here is an illustration of how I see the typical scientific software stack:
software-stack.pdf

I'd say that the top three layers are in the domain of the manifesto, so let's go through the principles one by one and see how they fit:

1. Open over closed

Makes sense for all layers, but "released by the time of publication" makes sense only for the top one, assuming that "publication" refers to a scientific paper. The lower layers evolve independently on any specific paper.

2. Code for the future

As a principle this is fine for everything, but "testing, writing documentation, instructions on how to run and maintain your code" is not always reasonable or practical for the top layer. Nobody maintains project-specific workflows or notebooks today, and it isn't clear that this is a practice one could reasonably move towards unless scientific papers become less numerous and more substantial. Testing is also of very limited interest for code that computes things that have never been computed before.

3. Incorrect code results in incorrect science

"Code published in journals should be peer reviewed." I'd say that all scientific code should be peer reviewed. For the top layer, this should be part of reviewing the scientific paper, because the review must also check if the code actually does what the paper says. But this requires changes in the review process that are not obvious to implement. For example, the experience of ReScience suggests that effective code review requires rapid interaction between authors and reviewers referring to a common codebase.

For the bottom two layers, code review needs to be continuous as the code evolves, meaning that it must be separate from any journal publication. There is no infrastructure for this at all at this time. Is it reasonable in a manifesto to call for something that is impossible in the immediate future? Honest question, I don't know how pragmatic manifestos should be.

4. Availability over perfection

This mostly applies to the top layer. The further down the stack you move, the more professionalism can and should be expected.

5. Code deserves credit

Certainly, but how far down the stack should one cite? For the top two layers, the obligation seems obvious. But should you cite NumPy? BLAS? Python? zlib? gcc? Linux?

So that the manifesto itself also becomes properly citable.

At the start the manifesto writes:

... [scientific code] needs to be treated as a primary research output

But later it writes:

Code published in journals should be peer reviewed.

While the second quote does not specifically demote it, any code should be peer reviewed, also if not published in journals. After all, if it only applies to code with a journal article, then the scientific code is secondary research output, not primary.

As a manifesto, I think it's worthwhile to aim for a future you'd like to see, and I can't really comment on those ideals (they look great to me, but I'm not experienced with this area). I wonder if some of the elements may appear overwhelming to someone in today's research world, and if it would be worthwhile taking a pragmatic view to implementation.

The Center for Open Science's TOP guidelines are an interesting method to consider: accept we're not at perfection today, measure where we are (honest and transparent), and see where to take the next small step towards implementation of ideals.

Could something similar be drawn up for this? In particular, I feel there are some useful indicators for this in @khinsen's review #7.

Example, for publishers:

• are software cited? in what way? e.g. are they cited in text and in references, does this include version number, commit number, etc as recommended in software citation principles
• are code files shared? in what way? e.g. from source files as supplements to a workflow that encourages authors to post them to active repositories and platforms like GitHub
• is code reviewed? in what way? e.g. from reviewer proactively requesting code from author (via journal) and reviewing it, to structural processes in place to make this the default. what are review outside of journal infrastructure, e.g. institutional or lab-based review?

These are just starting ideas, but I think it would be really useful to assess where each stakeholder (publisher, PI, developer/researcher) is at present and what is needed to advance the ideals in the manifesto in each situation.

I'd value some community input on this.

The official "start signing the manifesto" drive is going to happen soon. The manifesto has been accepted for two talks already, but I don't have the bandwidth or funds to go to all the interesting and relevant conferences myself. I'm hoping other people in the open community might care about this passionately enough to be willing to represent it as well.

How does "Code is Science ambassadors" sound? Open to other titles, too.

What I can offer:

• your name added to the list of contributors (maybe launch a specific ambassador page?)
• a pack of Code is Science materials including
  • Manifesto leaflets
  • Code is Science stickers
  • Optionally a manifesto poster (see #32) for accepted posters at conferences?

I would need to sponsor this from a relatively limited pot of money, so I'm unsure how to strike a balance between seeming welcoming and friendly and not wanting to waste funds sending packs out where they'll just sit in someone's desk until forgotten and dumped a few years later.

Equally I'd like to be able to sponsor people attending conferences to represent the manifesto, but then the money would run out even faster 😬 maybe a to-do item is to seek more funding.

I really enjoyed reading this manifesto, and it made me think of a similar call to action I've sometimes heard data scientists make about data.

One thing that sticks out to me, though, about your manifesto is that I think it would be easier to remember the principles if they were all in the same grammatical form. For example, you sometimes have a fragment of a sentence, like "Open over Closed" or "Code for the Future." Other times, you have complete sentences--"Incorrect code results in incorrect science." Maybe make every principle a sentence? Or every principle a fragment?

This is another little thing, but looking at other manifestos, I see that "X over Y" is a convention that's used often, so it might be interesting to depart from that and try something different. I don't think you have say that something is important--or necessary--by having it eclipse something else.

visiting https://codeisscience.github.io/manifesto/ returns ERR_ADDRESS_UNREACHABLE response

links back to the site.

To give some background about the Manifesto and encourage people to sign and share.
This would be published in the Software Sustainability Institute blog and other platforms(?)

Inspired by https://twitter.com/jjmerelo/status/994605979953254405 - can we add a "tweet this" button with similar text to what @JJ used?

The file to edit: https://github.com/codeisscience/manifesto/blob/master/index.md

You can use this site to generate the button: https://publish.twitter.com/?buttonType=TweetButton&widget=Button

if you want to pick up this task

1. Comment on this issue stating that you intend to work on the task
2. When you're ready, add your work to the repo and create a pull request.
3. Bask in glory and email me your address if you'd like to have some codeisscience stickers for your trouble. <3

What to do if you need help

Mention @yochannah, tweet @yoyehudi, pop by to say hi on gitter or if needed email [email protected] <3

It's early June! This is when we originally planned to freeze the manifesto text and start getting sign-ups. We've also had the manifesto accepted for two talks - GCCBOSC2018 and RSE2018, so there's a lot that needs to be done!

We'll need to break this into sub-tickets, but for now:

• update manifesto site with sign-up links (currently google forms)
  • Institutional sign-up form https://docs.google.com/forms/d/1W75S7DCa9Iv5FHTL7oeUWAnakl-oaEBoY5oNVcvDX5A/viewform?edit_requested=true
  • Individual sign-up form: https://docs.google.com/forms/d/1qEfuzo3TacqHYBatq9Gea3vPd_SFMpAqjlEe3TGt6ag/viewform?edit_requested=true
• We probably need some sign-up form disambiguation text and interlinking.
• Produce poster #32 for the conferences. (Needs to be done soon)
• Create citation guidelines - #25

If anyone is up to helping with any of these, that would be awesome!

e.g. have a signup verification process (send email to signee, ask them to confirm they exist)

There are almost certainly other good use cases to include here

https://github.com/burnash/gspread/pulls may be used for this.

https://www.codeisscience.com and https://www.codeisscience.github.io/ are currently 404ing (but https://codeisscience.github.io/manifesto/ appears fine?)

It would be really helpful for the manifesto to have paragraph that states that all collaborative projects should have a code of conduct, and that bullying and harassment are forms of scientific misconduct.

Thank you for adding a code of conduct to this respository, by the way!

Hey cool people! We've had the manifesto accepted for a talk / poster for GCCBOSC. This is fabulous! So now it's time to actually make the poster.

Specs

Size: A0 - 118.9 x 84.1cm

Poster contents:

• Header
  • Logo - use model 1 or 2: https://github.com/yochannah/code-is-science/tree/master/static/images
  • Title: "Code is Science - a manifesto for anyone who deals with code in a scientific scenario"
  • Authors and academic affiliations: Yo Yehudi, University of Cambridge, Alexander Konovalov [affiliation to follow], Selina Aragon [affiliation to follow] - @selina-aragon @alex-konovalov can you update with your details when you get a chance?
• Main body:
  • the preamble and text for each of the five manifesto concepts, as worded here: https://codeisscience.github.io/manifesto/manifesto (note - there's no need to includethe background or footer from the manifesto webpage)
  • the fantastic icons designed by Yee Mun beside each of the five manifesto concepts: https://github.com/codeisscience/manifesto/tree/master/codeisscience
• Footer
  • Credits to yourself for the poster design, as well as Yee Mun @yeemunnn for the icon design.
  • link to codeisscience.com

Here's some good academic poster guidance: https://colinpurrington.com/tips/poster-design

Output formats

• original editor format (this will depend on whatever editor you end up choosing)
• PDF
• SVG.

graphics editor I'd recommend using a vector editor such as Inkscape or Gravit Designer - they're both free, but Inkscape is open source. Gravit isn't open, but is somewhat easier to use.

It's due soon!

I'll be leaving for GCCBOSC on the 23rd of June, so ideally we need to wrap up the poster no later than the 12th of June to give us time to order the poster and for it to arrive. I'll pick this up on the 12th if no one else has had a chance to look at it.

if you want to pick up this task

1. Comment on this issue stating that you intend to work on the task
2. When you're ready, add your work to the repo and create a pull request.
3. Bask in glory and email me your address if you'd like to have some codeisscience stickers (plus perhaps some fliers of this poster!) for your trouble. <3

What to do if you need help

Mention @yochannah, tweet @yoyehudi, pop by to say hi on gitter or if needed email [email protected] <3

See details here for .cff standards and see #25 and #32 for guidelines on who should be credited as authors.

if you want to pick up this task

1. Comment on this issue stating that you intend to work on the task
2. When you're ready, add your work to the repo and create a pull request.
3. Bask in glory and email me your address if you'd like to have some codeisscience stickers for your trouble. <3

What to do if you need help

Mention @yochannah, tweet @yoyehudi, pop by to say hi on gitter or if needed email [email protected] <3