The Good Research Code Handbook source
This is the source for the Good Research Code Handbook, by Patrick Mineault. The website lives at goodresearch.dev. This book uses jupyterbook to build, with a highly customized theme based off of tufte.css
.
Reporting issues with the website
Please report any issues via the Issues tab.
Building the book
Recreate the conda environment with:
conda create --name cb --file environment.yml
Run jupyter-book build .
to build.
Use netlify deploy --prod
to deploy.
Citing this book
Patrick J Mineault & The Good Research Code Handbook Community (2021). The Good Research Code Handbook. Zenodo. doi:10.5281/zenodo.5796873
Sphinx module problem
Hi, I am trying to build this jupyter notebook and I get these errors even after
pip install sphinx
andpython -m pip install sphinxext-opengraph
The conf file already has these lines:
so I don't know what the problem is?
Error installing required packages and building book
Hi, running into a few problems trying to set up the theme:
Conda version: 4.11.0
conda create --name cb --file environment.yml
gives:CondaValueError: could not parse 'name: cb' in: environment.yml
Seems like the command should be
conda env create -n cb --file environment.yml
:env
Running the modified command, I still get:
And when I try to build the jupyter book this is the error:
Any idea what's wrong? Thank you!
command to recover environment from yml file did not work
conda create --name recoveredenv --file environment.yml
did not work, but instead:conda env create --name recoveredenv --file environment.yml
This might need to be changed in the handbook.
Thanks!
Patch 3
Changed
experienced
toexperience
based on tenses (figured it might have been a typo based on to double-up of the wordexperienced
) and updated sentence so that it reads in the same tense.Talk about the difference genericizing conda environment.yml and pip freeze
Oftentimes, the environment you get through exporting environment.yml or pip freeze is too specific; it doesn't work on other systems. Write about alternative ways of freezing the environment that are more flexible.
e.g. https://github.com/patrickmineault/codebook/issues/15
PDF version
Hiya,
I really love the codebook! It would be nice to have a PDF version. It seems jupyter-book allows you to do this: https://jupyterbook.org/advanced/pdf.html
Update pipelines.md
Also, beyond Software carpentry, what do you think of linking to https://makefiletutorial.com/ as well?
Tag not hidden from code
In the testing chapter, one of the code cells has some tags that should probably be hidden in the rendered version so to not cause any confusion for the reader. The problematic cell is this one: https://github.com/patrickmineault/codebook/blob/f4cc9b7371dea93a250b8efdc4db37ed1cbb9840/testing.md?plain=1#L100
Thanks for a really nice book!
Update tidy.md
Typo fix.
Nb- would be easier to make changes if your markdowns had an 80 (or some other number around high double digits) line limit as well, instead of one line per paragraph:)
consistency in setup.md
Make references to package directory/name consistent. Looks like you used to call it
code
then renamed it tosrc
but missed a few.Btw- when renaming the package, should the
name=
in setup.py be updated as well? (You write just renaming the directory is sufficient)env export vs export env
On the website, when exporting your Python environment, you list the command as:
conda export env > environment.yml
This didn't work for me, and the Conda webpage says to use:
conda env export > environment.yml
This worked for me.
Differentiate when to use assertions vs exceptions
Hi,
I really liked your talk on test & code, and I'm working through the book at the moment.
One comment/question I have is that I found your suggestions when to assert vs raise an exception were a little vague. From my understanding, assertions are great in tests (its the main mechanism to implement them) but should not be in production code. Production code should raise a ValueError, NotImplementedError, SomeCustomError... Something more representative than AssertionError.
For example, the exercise https://github.com/patrickmineault/codebook/blob/083bf3840bebee35e99203c87ab00b265841a392/testing.md?plain=1#L433-L435 Might lead us to believe that you should have asserts in your production code vs a more appropriate exception.
In the testing to maintain your sanity section you mix tests at runtime (the data is bad) and tests that can be done at implementation time (you're loading the data incorrectlly) which add to the vagueness of when to put asserts. https://github.com/patrickmineault/codebook/blob/083bf3840bebee35e99203c87ab00b265841a392/testing.md?plain=1#L29-L33
Thanks again for the ideas, ill be implementing some of them!
Mention tesing juptyer notebooks?
Came across this package to run jupyter notebooks with pytest.
https://pypi.org/project/nbmake/
Playing around with it to test someone else's demos:
https://github.com/Remi-Gau/GLMsingle/blob/fb9f0a9781c8d575abfd7742505593b8006ad876/.github/workflows/run_demos_python.yml#L42
Maybe worth mentioning.
Discuss documenting alternative analyses
From a reader:
Discuss git branching, gigantum, others.
Discuss data management solutions
From a reader:
Some solutions:
Also discuss sharing these versions, e.g. through dryad, figshare, OSF, etc.