---
tags: OpenDreamKit, FPSAC, Sage, GAP, workshop
breaks: false
slideOptions:
theme: white
width: 95%
height: 100%
margin: 0
minScale: 1
maxScale: 1
centered: false
slideNumber: true
---
<style type="text/css">
p { text-align: left; }
ul { text-align: left; }
h3 { text-align: left; }
</style>

# Some best practices for computer exploration

July 9th of 2019

[Free and Practical Software for Algebraic Combinatorics 2019](https://wiki.sagemath.org/fpsac19)

[this document as slides](https://hackmd.io/@nthiery/some-best-practices-for-computer-exploration)

---

## Conducting computer exploration

A great reference: François Bergeron's talk [Mathématiques Expérimentales](https://opendreamkit.org/meetings/2019-02-11-CIRM/MathExperimentale.pdf)

Two key recommendations:

### Seek Beauty and Surprise

### Interact with the computer in your own language

---

## Correctness, Reproducibility, Reusability

A great reference: Mike Croucher's talk: [Is Your Research Software Correct](https://mikecroucher.github.io/MLPM_talk/)

**Croucher's Law:** I am an idiot, and I will make mistakes

We all do.

How hard does it affect us?

What can we do about it?

----

### Document our experiments

- What was the goal?
The hypothesis to be tested?

- What was the process?

- What artefacts were used?
(software stack, ...)

- What was our interpretation?

----

### Maintain a laboratory notebook!

To enable:
- **retrieving** what was tried, when, what was the outcome

- **checking** the process: is it really doing what we meant?

- **reproducing** the process: is it still the same outcome?

- **reusing** the artefacts for related experiments

- **sharing** it with others!

----

### How to write great lab notebooks?

----

#### Automate

Ideal description of the process:

Results = MyAnalysis(Data)

where ``MyAnalysis``:
- reveals the business logic
- hides the technical details

----

#### Use literate computing

Write the notebook as a **narrative text** mixing prose and computation.

- Jupyter notebooks
- Rich text files (Markdown, org-mode, RST)
- Code file with documentation strings
- Code snippets in your LaTeX file
- ...

**Desirable features**:
- easy to read
- easy to reexecute
- easy to version control
- easy to test
- easy to share
- standard

----

#### Interact with the computer in your own language

The logic should be easy to read by the casual scientist in your field, with no special preparation

- Express what you compute rather than how
E.g. comprehensions rather than loops

- Model the business objects
E.g. with Object Oriented Programming

- Model the business processes
E.g. with functions

- Write code in a high level language

----

#### Separate lab notebook and code

- In the lab notebook: the bare necessary to document the process
- Every other bit of code: as reusable functions/class, in separate files

Rationale:
- Easier to reuse
- Easier to document
- Easier to test
- Easier to version control

----

#### Get some training!

Learn basic computer science skills:

- **Version control**
git, mercurial, ... +[nbdime](https://nbdime.readthedocs.io/) for Jupyter

- **Tests**
`sage -t file.sage` +[nbval](https://nbval.readthedocs.io/) for Jupyter

- **[Documentation](https://doc.sagemath.org/html/en/developer/coding_basics.html#template)**
[Documentation conventions in Sage](https://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings)

- **Profiler**
*Early optimization is the root of all evil!*
%prun, [snakeviz](https://jiffyclub.github.io/snakeviz/), ...

- **Debugger**
[pdb](https://docs.python.org/3/library/pdb.html), ...

---

## Publish your code and logbooks!

Provide or document all artefacts:

- Personal code
- Software stack
- Data
- Use open source software / open data

**Instant bonus**: reproducibility with Binder!

---

## References about computational logbooks in Sciences
Computational maths tends to be a bit different, with less reliance on data
Nevertheless much of the analysis and tips in the following pages remains relevant up to adaption:

- https://drivendata.github.io/cookiecutter-data-science/
- https://blog.godatadriven.com/write-less-terrible-notebook-code
- [A few thoughts on organizing computational (biology) projects](https://bionics.it/posts/organizing-compbio-projects)
- https://bioinfo-fr.net/soutiller-et-sorganiser-pour-mieux-travailler

---

## Watch for your health!

- Watch your back!
- Watch your wrists!
- Watch your eyes!
- Watch your ears!
- Get some sleep!