<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!