diff --git a/.github/workflows/check_schedule.yaml b/.github/workflows/check_schedule.yaml new file mode 100644 index 000000000..931199bbf --- /dev/null +++ b/.github/workflows/check_schedule.yaml @@ -0,0 +1,30 @@ +# Check that the schedule has the right order +name: Check schedule + +# Check links on the 21st day of the month. +# 21st as the first letter of this repo is the 21st letter in the alphabet. +on: + push: + pull_request: + schedule: + - cron: "0 0 21 * *" + +jobs: + check_schedule: + + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-r@v2 + + - name: Install dependencies + run: | + install.packages(c("remotes", "testthat", "readr", "stringr", "tibble")) + shell: Rscript {0} + + - name: Run script + run: ./scripts/check_schedule.R + diff --git a/.wordlist.txt b/.wordlist.txt index 1b6264f97..431fe7a7d 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1510,3 +1510,30 @@ criticise Yay Mariam UNDF +HICexplorer +Readmes +Couplers +Dispensables +Preventers +blackbox +ann +Huw +Collingbourne +acknowledgements +Acknowledgements +KamilSJaron +ov +readme +runing +sacharomyces +smudgeplot +READMEs +pypi +bacsim +PyPi +testPyPI +Beielstein +subfunctions +Stroebe +Sitzmann + diff --git a/README.md b/README.md index 866d8febd..a9fc9752b 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ [![Check spelling](https://github.com/UPPMAX/programming_formalisms/actions/workflows/check_spelling.yaml/badge.svg?branch=main)](https://github.com/UPPMAX/programming_formalisms/actions/workflows/check_spelling.yaml) [![Check markdown](https://github.com/UPPMAX/programming_formalisms/actions/workflows/check_markdown.yaml/badge.svg?branch=main)](https://github.com/UPPMAX/programming_formalisms/actions/workflows/check_markdown.yaml) [![Create website](https://github.com/UPPMAX/programming_formalisms/actions/workflows/create_website.yaml/badge.svg?branch=main)](https://github.com/UPPMAX/programming_formalisms/actions/workflows/create_website.yaml) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14222353.svg)](https://doi.org/10.5281/zenodo.14222353) diff --git a/data/README.md b/data/README.md new file mode 100644 index 000000000..922e65275 --- /dev/null +++ b/data/README.md @@ -0,0 +1,3 @@ +# Data + +Data being collected during the course. diff --git a/data/counts/2023_autumn/README.md b/data/counts/2023_autumn/README.md new file mode 100644 index 000000000..afc2088eb --- /dev/null +++ b/data/counts/2023_autumn/README.md @@ -0,0 +1,5 @@ +# Counts + +## Other data + +- Number of registrations: 40 diff --git a/data/counts/2023_summer/README.md b/data/counts/2023_summer/README.md new file mode 100644 index 000000000..fa1a711b2 --- /dev/null +++ b/data/counts/2023_summer/README.md @@ -0,0 +1,5 @@ +# Counts + +## Other data + +- Number of registrations: 43 diff --git a/data/counts/2024_autumn/20241118_counts.csv b/data/counts/2024_autumn/20241118_counts.csv new file mode 100644 index 000000000..d814e8a91 --- /dev/null +++ b/data/counts/2024_autumn/20241118_counts.csv @@ -0,0 +1,35 @@ +time,n_cam_on,n_cam_off +9:00,6,0 +9:01,6,1 +9:02,7,0 +9:03,7,0 +9:10,7,0 +9:11,8,0 +9:12,8,1 +9:16,8,1 +9:19,9,0 +9:30,9,0 +9:41,9,0 +10:03,7,2 +10:04,8,1 +10:05,9,0 +10:11,9,0 +10:21,9,1 +10:28,9,1 +10:39,8,2 +10:47,9,0 +10:51,9,0 +11:11,8,1 +13:01,3,5 +13:03,6,2 +13:04,7,1 +13:11,8,0 +14:15,5,3 +14:16,7,1 +14:17,8,0 +14:29,8,0 +14:36,9,0 +14:37,8,1 +15:15,7,2 +15:42,9,0 + diff --git a/data/counts/2024_autumn/20241119_counts.csv b/data/counts/2024_autumn/20241119_counts.csv new file mode 100644 index 000000000..df8227d4d --- /dev/null +++ b/data/counts/2024_autumn/20241119_counts.csv @@ -0,0 +1,21 @@ +time,n_cam_on,n_cam_off +9:00,2,2 +9:01,5,1 +9:02,8,0 +9:03,8,0 +9:20,8,0 +9:21,7,1 +9:22,8,0 +9:27,8,0 +9:28,7,0 +9:35,8,0 +10:00,8,0 +13:00,2,2 +13:01,6,2 +13:02,8,0 +13:30,8,0 +14:16,8,0 +14:51,8,0 +14:52,7,1 +15:41,8,0 + diff --git a/data/counts/2024_autumn/20241120_counts.csv b/data/counts/2024_autumn/20241120_counts.csv new file mode 100644 index 000000000..217317bb8 --- /dev/null +++ b/data/counts/2024_autumn/20241120_counts.csv @@ -0,0 +1,9 @@ +time,n_cam_on,n_cam_off +11:10,8,1 +11:25,9,0 +11:48,9,0 +13:03,9,0 +14:17,9,0 +15:17,9,0 +15:41,9,0 +15:53,9,0 diff --git a/data/counts/2024_autumn/20241121_counts.csv b/data/counts/2024_autumn/20241121_counts.csv new file mode 100644 index 000000000..9ba88c65f --- /dev/null +++ b/data/counts/2024_autumn/20241121_counts.csv @@ -0,0 +1,11 @@ +time,n_cam_on,n_cam_off +9:01,5,0 +9:02,7,0 +9:23,7,1 +13:00,7,0 +13:01,7,1 +13:45,8,0 +14:00,8,0 +14:15,7,0 +14:40,5,0 +15:50,5,0 diff --git a/data/counts/2024_autumn/20241122_counts.csv b/data/counts/2024_autumn/20241122_counts.csv new file mode 100644 index 000000000..1f4d152b8 --- /dev/null +++ b/data/counts/2024_autumn/20241122_counts.csv @@ -0,0 +1,9 @@ +time,n_cam_on,n_cam_off +9:07,7,0 +9:59,7,0 +10:56,7,0 +11:15,6,1 +14:25,7,0 +14:51,7,0 +15:15,5,1 +15:16,6,0 diff --git a/data/counts/2024_autumn/README.md b/data/counts/2024_autumn/README.md new file mode 100644 index 000000000..7bc6e6a78 --- /dev/null +++ b/data/counts/2024_autumn/README.md @@ -0,0 +1,23 @@ +# Counts + +Goal of this experiment is to see how important camera usage is for +keeping learners in an online course. + +## Data description + +`[date]_counts.csv` field|Description +-------------------------|------------------------------------- +`time` |Time +`n_cam_on` |Number of learners with the camera on. This excludes teacher(s) and assistants +`n_cam_off` |Number of learners with the camera on. This excludes teacher(s) and assistants + +## Other data + +- Number of registrations: 23 + +## Conclusions + +The amount of learners present throughout the course was around 8 (mostly +9, but 7 on Friday). Hence, we should expect `n_registrations / 3` +active particpants. + diff --git a/lesson_plans/2024_autumn/20240422_counts.csv b/data/counts/2024_summer/20240422_counts.csv similarity index 100% rename from lesson_plans/2024_autumn/20240422_counts.csv rename to data/counts/2024_summer/20240422_counts.csv diff --git a/lesson_plans/2024_autumn/20240423_counts.csv b/data/counts/2024_summer/20240423_counts.csv similarity index 100% rename from lesson_plans/2024_autumn/20240423_counts.csv rename to data/counts/2024_summer/20240423_counts.csv diff --git a/lesson_plans/2024_autumn/20240424_counts.csv b/data/counts/2024_summer/20240424_counts.csv similarity index 100% rename from lesson_plans/2024_autumn/20240424_counts.csv rename to data/counts/2024_summer/20240424_counts.csv diff --git a/lesson_plans/2024_autumn/20240425_counts.csv b/data/counts/2024_summer/20240425_counts.csv similarity index 100% rename from lesson_plans/2024_autumn/20240425_counts.csv rename to data/counts/2024_summer/20240425_counts.csv diff --git a/lesson_plans/2024_autumn/20240426_counts.csv b/data/counts/2024_summer/20240426_counts.csv similarity index 100% rename from lesson_plans/2024_autumn/20240426_counts.csv rename to data/counts/2024_summer/20240426_counts.csv diff --git a/data/counts/2024_summer/README.md b/data/counts/2024_summer/README.md new file mode 100644 index 000000000..afb8413b8 --- /dev/null +++ b/data/counts/2024_summer/README.md @@ -0,0 +1,16 @@ +# Counts + +Goal of this experiment is to see how important camera usage is for +keeping learners in an online course. + +## Data description + +`[date]_counts.csv` field|Description +-------------------------|------------------------------------- +`time` |Time +`n_cam_on` |Number of learners with the camera on. This excludes teacher(s) and assistants +`n_cam_off` |Number of learners with the camera on. This excludes teacher(s) and assistants + +## Other data + +- Number of registrations: 33 diff --git a/docs/data_structures/class_design.md b/docs/data_structures/class_design.md index 90ab5b9fb..73188eaf0 100644 --- a/docs/data_structures/class_design.md +++ b/docs/data_structures/class_design.md @@ -144,7 +144,7 @@ On the other hand, a Python developer can at least see that this convention was broken. Note that some other programming languages completely disallows -you from modifying a so-called 'private' member variabel. +you from modifying a so-called 'private' member variable. ## Inheritance and polymorphism quote @@ -168,7 +168,7 @@ well `[Gamma et al., 1995]` ## Exercise -### Exercise: write a class with an invariant. +### Exercise: write a class with an invariant - Pick a class at your skill level: diff --git a/docs/data_structures/expressive_data_type.md b/docs/data_structures/expressive_data_type.md index 97ad996e4..1e62d6e07 100644 --- a/docs/data_structures/expressive_data_type.md +++ b/docs/data_structures/expressive_data_type.md @@ -58,7 +58,7 @@ def get_bacteria_initialization(parameters): return parameters[3] Also, reading such a list is too uninformative: which `uniform` belong to which parameter? -Using [a dictionary (`dict`)](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) +Using [a dictionary (`dict`)](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) can be considered good enough, until you've read up about classes: @@ -81,7 +81,7 @@ def get_bacteria_initialization(parameters): When having read up on classes, one understands these are dictionaries -with extra properties, such +with extra properties, such as **a name**. ## Good data structures increase expressiveness diff --git a/docs/data_structures/has_a_relation.md b/docs/data_structures/has_a_relation.md index 326d60a98..64fecffdf 100644 --- a/docs/data_structures/has_a_relation.md +++ b/docs/data_structures/has_a_relation.md @@ -232,7 +232,7 @@ classDiagram ???- question "Answer for the particle" - ``` + ```text class Position: def __init__(self, any_x, any_y): self.x = any_x diff --git a/docs/deployment/deploy.md b/docs/deployment/deploy.md index 0d8525853..a4977400a 100644 --- a/docs/deployment/deploy.md +++ b/docs/deployment/deploy.md @@ -6,9 +6,9 @@ !!! info "Learning objectives of 'Deployment'" - - learners can mentalize the installation needs from the users perspective - - learners can evaluate different available tools for reproducibility and installations - - learners can prepare for different users: local computer, Cluster + - I can mentalize the installation needs from the users' perspective + - I can evaluate different available tools for reproducibility and installations + - I can make an installation instruction for potential users !!! info "Content" @@ -19,8 +19,8 @@ - some theory of containers - get some hands on - ???- note "Instructor notes" + Prerequisites are: - ... @@ -51,28 +51,307 @@ !!! attention - Make your program or workflow works for others and yourself in the future. - - Let people understand how to use your program/tool -## Exercises +## Recording dependencies + +- **Reproducibility**: We can control our code but how can we control dependencies? +- **10-year challenge**: Try to build/run your own code that you have created 10 (or less) years ago. Will your code from today work in 5 years if you don’t change it? +- **Dependency hell**: Different codes on the same environment can have conflicting dependencies. + +### To make sure about needed dependencies + +- Start with empty environment +- Nowadays platforms are less important, still "system files" may differ among OS platforms and Linux distributions + - will your program require specific "system files" + - are these typically not installed already? + - in the **best world test on Windows/Mac and Linux platforms** + - and with as empty as possible environment +- What about Shared services like a cluster where users and most staff do not have writing privileges ('sudo' rights) for system installations? + +!!! discussion "Discussion: Where do you run your program?" + + - From a terminal? + - On different computers? + - On a cluster? + +- We need to either inform what is needed to run the software in the README file +- Or provide them with everything needed + - hopefully not interfering with other software they are using + +!!! note "Ways to distribute" + + - Python packages: + - pip (PyPI) + - conda + - R: + - R repos like CRAN and GitHub (devtools) + - conda + - Compiled languages: + - built binaries (platform specific) + - install from source + - manual + - make + - CMake + - General tools + - Containers + +### Conda, pip + +**These _Python-related_ tools try to solve the following problems:** + +- **Defining a specific set of dependencies**, possibly with well-defined versions + - requirements.txt... +- **Installing those dependencies** mostly automatically +- **Recording the versions** for all dependencies +- **Isolated environments** (venv, virtualenv) + - On your computer for projects so they can use different software. + - Isolate environments on computers with many users (and allow self-installations) + - Using **different Python/R versions** per project?? + - Provide tools and services to **share packages** + +- Let's focus here on PyPI! + - Remember we made a package this morning! +- We'll cover the other tools after the exercise. + +### Principle using python pip in a virtual environment + +- We can make other users aware of the dependencies for our Python project. +- One can state those specifically as a list in a README +- Or, we can make a ready file (in python) + +**Save your requirements as a file** + +- You may have developed your Python program with your existing python modules environment. You may have installed some new packages during the development but did not track it in a good way. +- We need to identify what python packages a user (or you on another computer) will need, to make the program work! + - There are many packages distributed in the "base" installation of Python so it is not just to look at the import lines in the code. + - You may also be hard to get an overview because you have too many import lines, also distributed among files if you worked in a modular way +- So here are some steps: + +- Start a python virtual environment. + - you can do this outside the git repo to not pollute it + +```console +python -m venv /usertest +``` + +- This creates an empty virtual environment located in `/usertest` directory +- Activate + +```console +source /usertest/bin/activate +``` + +- In Windows you may have to instead do: + +```console +source /usertest/Scripts/activate +``` + +- Note the ``(usertest)`` in the beginning of the prompt! +- Do note the python version and you may inform users that you know that this version is known to work! + +```console +which python #must point to the python belonging to the virtual environment +python -V # note this version +which pip #must point to the pip belonging to the virtual environment +``` + +- You can switch to the directory where you have your code and test to run it +- It may give you errors of missing packages, like ``numpy`` +- Install them with + +```console +pip install +``` + +- No need to use ´´--user``, since it will be installed in the virtual environment only. +- Do this until your program works +- Check what is installed by: + +```console +pip freeze #pip list works as well +``` + +- You will probably recognise some of them, but some may be more obscure and were installed automatically as dependencies. + +- Save your requirements as a file that user can run to get the needed dependencies + +```console +pip freeze > requirements.txt +``` + +- Other users can then install the same packages with: + +```console +pip install --user -r requirements.txt +``` + +- End the isolated environment and work with other things! + +```console +deactivate # deactivate the venv! +``` + +!!! example + + - [planet project](https://uppmax.github.io/programming_formalisms/deployment/deploy/) + - [requirements.txt](https://github.com/bclaremar/planets-bjorn/blob/main/code/requirements.txt) + +### README: installation section + +**Let's take a look at different READMEs** + +- Also interesting: Is there any test that makes sure it is correctly installed? + +!!! example + + - R: + - Conda: + - pip: + - pip: + - binaries/executable: + +## Exercises 20-30 min + +- We already have a file called ``README.md``, that is used for information for the course participants. +- Let's work with a README file for potential users. We can call it ``README-EXT.md`` !!! info "Intro" - - Users should be able to install the required python packages with ``pip``: - ``pip install -r requirements.txt`` (depending on system ``--user`` may be added) - - Revisit your README and update it with info after all our commits - - Installation - - Do a ``git pull`` to have the same version of your project repo locally! + - (External) Users should be able to install the the complete tool, including dependencies: + . Repo work + - work on GitHub! + - When modifying repo, use a group specific branch + - When done, merge + - In the end we do code review together of the merging conflicts -???+ question "Make a 'requirements' file in groups" + ???- info "Hints" + + - The main program ``main.py`` is in the repo. + - ``bacsim`` is a python package needed by ``main.py`` + - available here: + +???+ question "(In groups) Will people need any additional packages for this tool?" + + - Test in isolated environment (``venv``) on local computer if there are errors + - That is, are there any more packages needed + - follow the example above + +???+ question "(In groups) Make a 'requirements.txt' file (if needed)" - each group in different branches - then merge and teacher does code review -???+ question "Update the "installation instruction' in groups" +???+ question "(In groups) Make 'installation instruction' in groups" - each group in different branches - then merge and teacher does code review +## Going further with deployment + + +[Python packaging](https://aaltoscicomp.github.io/python-for-scicomp/packaging/). + +- **Possibilities for other languages can be** + - C/C+ + - CMake + - Conda + - Fortran + - Fortran package manager + - Julia + - Pkg.jl + +- [More info](https://uppmax.github.io/programming_formalisms_intro/reproducible_deeper.html#recording-dependencies) + +- [The tools](https://uppmax.github.io/programming_formalisms_intro/reproducible_deeper.html#the-tools) + + +**Course advertisement** +[Python for scientific computing](https://aaltoscicomp.github.io/python-for-scicomp/) + +### Containers + +- Containers let you install programs without needing to think about the computer environment, like + + - operative system + - dependencies (libraries and other programs) with correct versions + +![Containerization](./img/Containerization_nextlabs.png) + +> From [Nextlabs](https://www.nextlabs.com/what-is-containerization/) + +!!! info + + - 2(3) types + + 1. Singularity/Apptainer perfect for HPC systems + 2. Docker that does not work on HPC-systems + + - But docker images can be used by Singularity and Apptainer + + - Everything is included + - Workflow: + + - Download on Rackham or local computer + - Transfer to Bianca + - Move to from wharf to any place in your working folders on Bianca + + - Draw-backs + + - you install also things that may be already installed + - therefore, probably more disk space is needed + +!!! info "More info" + + - [Singularity course](https://www.uu.se/centrum/uppmax/utbildning/kurser-och-workshops/basic-singularity){:target="_blank"} + - [Environments by CodeRefinery](https://coderefinery.github.io/reproducible-research/environments) + - [Containers in the extra material](https://uppmax.github.io/programming_formalisms_intro/reproducible_deeper.html#containers) + + +### Workflows + +!!! info "See also" + + **Learn more** + [Workflow management by CodeRefinery](https://coderefinery.github.io/reproducible-research/workflow-management/) + [Snakemake by CodeRefinery](https://nbis-reproducible-research.readthedocs.io/en/course_2104/snakemake/) + +### Make a file executable by its own + +- Run a python script without the ``python`` before! + +- This line helps in the top of the main script: + +```bash +#!/bin/env python +``` + +- Then the python active in "PATH" will automatically be used + - especially important on a shared system where python is not in the typical "/usr/bin/python" path. + + +### Compiled languages + +- [Build Systems Course](https://github.com/PDC-support/build-systems-course) + + +### Ignoring files and paths with .gitignore + +Compiled and generated files are not committed to version control. There are many reasons for this: + +- Your code could be run on different platforms. +- These files are automatically generated and thus do not contribute in any meaningful way. +- The number of changes to track per source code change can increase quickly. +- When tracking generated files you could see differences in the code although you haven't touched the code. + +For this we use `.gitignore` files. + +- Read more + +!!! example "From our project repo" + + + ## Summary !!! info "Key points" @@ -98,7 +377,7 @@ - ☐ Sharing - ☑ open science - ☐ citation - - ☑ licensing + - ☐ licensing - ☑ deploying - ☐ Documentation - ☑ in-code documentation diff --git a/docs/deployment/documentation.md b/docs/deployment/documentation.md index de5760fc8..3c7a8f8a1 100644 --- a/docs/deployment/documentation.md +++ b/docs/deployment/documentation.md @@ -8,10 +8,9 @@ learners - - can make a full README - - can make a suitable choice of License - - can make citation info - - know how to find instruction of going more sophisticated + - I know the most important sections for a full public README + - I can make citation info + - I know how to find instruction of going to more sophisticated documentation !!! info "Content" @@ -29,22 +28,6 @@ - GitHub pages/ReadTheDocs - MkDocs/sphinx -!!! note "Instructor notes" - - Prerequisites are: - - - ... - - Lesson Plan: **FIX** - - - **Total** 30 min - - Theory 20 - - Discussions 10 min - -!!! info "TOC" - - - ## Revisiting documentation @@ -67,21 +50,21 @@ ### Where are we? -**DONE** +**DONE** - ☑ in-code documentation - ☑ Project documentation: - - requirements: what is the goal of the software, risks, platforms - - the analysis: pseudocode and UML - - risk analysis - + - requirements: what is the goal of the software, risks, platforms + - the analysis: pseudocode and UML + - risk analysis + **Finalize today** - ☐ README - ☑ installation instruction - ☐ Tutorial: get started - ☐ citation - + **Further documentation for future projects** - ☐ **License** @@ -90,24 +73,131 @@ - ☐ **Explanation**: understanding-oriented, explains a concept - ☐ **Reference**: information-oriented, describes the machinery +## The README + +### Example content + +- About +- Installation (with dependencies and testing) +- Get started +- Use cases +- Citation + +### About + +- About the software +- What does it do? +- One (Punch-)line describing what it does. + - Also in GitHub in upper right corner! +- More information below below the first description + +### Install + +- We covered this in last session + +### Get started + +- This session can be "running some test data" to get an overview of what the program can perform. +- It may describe how to get test data +- Example: + +### Use cases + +- This may sometimes be merged with the previous section + +- **How-to guide**: goal-oriented, shows how to solve a specific problem +- May be a sub-set of the most important commands, depending on how wide the program is. +- Example: + +???- discussion "would it be needed for your project?" + +### Contributions + +- How to contribute? +- Example: + +### Acknowledgements + +- Add references that inspired or added algorithms to your code +- Example: + +### References/Citation + +- Think the same as for a scientific paper + +**Practical recommendations**: + +- Get a [DOI](https://en.wikipedia.org/wiki/Digital_object_identifier) using [Zenodo](https://zenodo.org) or similar services. +- Open source license can't demand citation, but it is required by science ethics anyway. +- Make it as easy as possible! Clearly say what you want cited. +- Make it easy for scripts and tools, use the [Citation File Format](https://citation-file-format.github.io). +- [GitHub now supports CITATION.cff files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) + +This is an example of a simple `CITATION.cff` file: + +```yaml +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +authors: + - family-names: Druskat + given-names: Stephan + orcid: https://orcid.org/0000-0003-4925-7248 +title: "My Research Software" +version: 2.0.4 +doi: 10.5281/zenodo.1234 +date-released: 2021-08-11 +``` + +Recommended format for software citation is to ensure the following information +is provided as part of the reference [Katz, Chue Hong, Clark, 2021](https://f1000research.com/articles/9-1257/v2): + +- Creator +- Title +- Publication venue +- Date +- Identifier +- Version +- Type + +- Digital object identifiers (DOI) are the backbone of the academic reference and metrics system. +- CodeRefinery has an exercise to see how to make a GitHub repository citable by archiving it on the Zenodo archiving service. If you are interested, have a look [here](https://coderefinery.github.io/github-without-command-line/doi/#making-your-project-citable) + +- Example: + +!!! example + + - R: + - Conda: + - pip: + - pip: + - binaries/executable: + +!!! info "See also" + + - [Collection of (Academic) software repo links](https://www.softwareheritage.org/) + - [Awesome list of Research Software Registries](https://github.com/NLeSC/awesome-research-software-registries) + ## Exercise !!! info "Intro" - - Revisit your README and update it with info after all our commits + - Revisit ``README-ext.md`` and update it with info after all our commits - About - - Citing - - License + - Citing - Lastly, you may, if time allows, update the doc/index.md file that should describe the content - Do a ``git pull`` to have the same version of your project repo locally! - ???+ question "Update your documentation in groups" - You can now work in GitHub directly - Do ``git push`` first from local command-line! - ???- question "Group 1: Work together and formulate an 'About' section + + - We already have a file called ``README.md``, that is used for information for the course participants. + - Let's continue to work with the ``README-EXT.md`` we used in last session. + + + ???- question "Group 1: Work together and formulate an 'About' section" ???- question "Group 2: Work together and formulate 'Getting started' section" @@ -116,8 +206,15 @@ ## Discussion -???- Describe what you've done and why? +???- question "Discussion: Describe what you've done and why?" + +## Licensing + +!!! info "See also" + [Extra material about licensing](https://uppmax.github.io/programming_formalisms_intro/sharing_deeper.html#licensing) + + ## Going further with documentation !!! info "See also" @@ -129,10 +226,11 @@ - Popular solutions (but many others exist): - [MediaWiki](https://www.mediawiki.org) - [Dokuwiki](https://www.dokuwiki.org) - - Also on GitHub! - - Typically needs to be hosted and maintained - -- Example with [WRF weather model](https://github.com/wrf-model/WRF/wiki) + - These typically needs to be hosted and maintained +- Also on GitHub! + - [About wikis](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis) + - [Adding or editing wiki pages](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages) + - Example with [WRF weather model](https://github.com/wrf-model/WRF/wiki) ### HTML static site generators @@ -141,7 +239,7 @@ There are many tools that can turn RST or Markdown into beautiful HTML pages: - [Sphinx](http://sphinx-doc.org) - Generate HTML/PDF/LaTeX from RST and Markdown. - [Read the docs style](https://sphinx-rtd-theme.readthedocs.io/en/stable/) - - [Earlier Intro day for this course]() + - [HICexplorer documentation](https://hicexplorer.readthedocs.io/en/latest/) - [Jekyll](https://jekyllrb.com) - Generates HTML from Markdown. - GitHub supports this without adding extra build steps. @@ -171,11 +269,36 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: - Somewhat more possibilities, like having several versions of documentation to switch between. - - - - - +### What contributes to reusability? + +What contributes to you being able to reuse stuff that others make, and others +(or you) being able to reuse your stuff? When you find a repository with code +you would like to reuse, you may look at the following things to determine its +reusability: + +!!! note + + - Date of last code change + > ... is the project abandoned? + - Release history + > ... how about stability and backwards-compatibility? + - Versioning + > ... will it be painful to upgrade? + - Number of open pull requests and issues + > ... are they followed-up? + - Installation instructions + > ... will it be difficult to get it running? + - Example + > ... will it be difficult to get started? + - License + > ... am I allowed to use it? + - Contribution guide + > ... how to contribute and decision process? + - Code of conduct + > ... how to make clear which behaviors are unacceptable and discouraged? How violations of Code of conduct will be handled? + - Trust and community + > ... somebody you trust recommended it? + !!! admonition "Parts to be covered!" - ☑ Source/version control diff --git a/docs/deployment/img/Containerization_nextlabs.png b/docs/deployment/img/Containerization_nextlabs.png new file mode 100644 index 000000000..e57b5cff1 Binary files /dev/null and b/docs/deployment/img/Containerization_nextlabs.png differ diff --git a/docs/deployment/img/README.md b/docs/deployment/img/README.md new file mode 100644 index 000000000..f7d9e43b7 --- /dev/null +++ b/docs/deployment/img/README.md @@ -0,0 +1 @@ +# Some images diff --git a/docs/design_develop/OO_development.md b/docs/design_develop/OO_development.md index a834334dd..2933fa475 100644 --- a/docs/design_develop/OO_development.md +++ b/docs/design_develop/OO_development.md @@ -1,6 +1,7 @@ # Object Oriented development ???- info "Learning objectives" + - Understand the benefits of object-oriented development, including smaller semantic gaps for improved understanding and easier modification of models. - Learn the definition and characteristics of an object, including its ability to save state and perform operations. - Comprehend the principles of object-oriented development, such as information hiding, encapsulation, and message passing. @@ -73,8 +74,6 @@ classDiagram Animal <|--GoldFish ``` - - Further reading: [Aggregation vs composition and Generalization vs Specialization](https://www.visual-paradigm.com/guide/uml-unified-modeling-language/uml-aggregation-vs-composition/) diff --git a/docs/function_design/README.md b/docs/function_design/README.md index 086bedaa3..e8d100a4c 100644 --- a/docs/function_design/README.md +++ b/docs/function_design/README.md @@ -526,6 +526,6 @@ which should include your reasoning. "O'Reilly Media, Inc.", 2016. Chapter 'General concepts' - `[Wilson et al, 2017]` Wilson, Greg, et al. - "Good enough practices in scientific computing." - PLoS computational biology 13.6 (2017): e1005510. + "Good enough practices in scientific computing." + PLoS computational biology 13.6 (2017): e1005510. [here](https://doi.org/10.1371/journal.pcbi.1005510) diff --git a/docs/misc/definitions.md b/docs/misc/definitions.md new file mode 100644 index 000000000..6be69bb8d --- /dev/null +++ b/docs/misc/definitions.md @@ -0,0 +1,27 @@ +--- +tags: + - definitions + - glossary + - dictionary +--- + +# Definitions + + + +Term |Definition +-----------------------|---------------------------------------------------------------------------------------- +Aggregation |A has-a relation between two objects, where the smaller object is not owned, e.g. a university has professors +`assert` |A function to test one's own assumptions or indicate a stub +Composition |A has-a relation between two objects, e.g. a car has an engine +Function |Isolated piece of code with a name, input arguments and output value +Function arguments |The values that a function needs to do its work, e.g. a number to determine if it is prime +Function return value |The value produced by a function, e.g. a `TRUE` or `FALSE` for a function that determines if a number is prime +Inheritance |An is-a-type-of relation between two objects, e.g. a duck is a type of animal +Integration test |Test of multiple classes working together +Stub |A beginning of something, something that needs to be expanded on later +TDD |See test-driven development +Test-driven development|The software development methodology to write tests that initially fail to grow the code +Unit test |Test of a single function or class + + diff --git a/docs/misc/evaluation.md b/docs/misc/evaluation.md index e4b8aa83f..34ed69b32 100644 --- a/docs/misc/evaluation.md +++ b/docs/misc/evaluation.md @@ -14,7 +14,7 @@ ``` ```text -[Richel] What I don't like, is that the results are not public +> [Richel] What I don't like, is that the results are not public ``` ## NBIS Short Term Feedback (STF) @@ -23,13 +23,31 @@ The intention of the STF survey is to find out how participants have used the skills and knowledge they gained through participating in the NBIS course. + +> [Richel] This seems false to me. Could this be a copy-paste mistake +> from the Long Term Feedback survey? +> +> A goal I suggest: The intention of the STF survey is to find out +> how the course can be improved. + The STF survey aims to provide data back to NBIS from course participants. + +> [Richel] Suggest: 'The results of this survey are used by NBIS'. +> +> I wish it would say: +> +> The results of this survey will be published online, +> to make sure each voice is heard. + The survey should preferably be given by the course leader to the participants on the last day of the course. Some of the questions below are CORE Questions and needs to always be included in the survey. There are also room for ADDITIONAL questions that can be modified for respective course. +> [Richel] Sounds like the core questions are the only ones bothering +> learners with. The additional questions already feel too much 'nice to have'. + - Contents - Important Information - Core Question Set @@ -59,6 +77,9 @@ be administered as close as possible to the end of the training event, preferably on the last day of the course. Please add the result of the survey to the course folder in Google Drive (NBIS Course Catalogue). +> [Richel] In teaching, I don't care about where the learners come from. +> I guess this is just to make pretty pictures? + The core question set is followed by a set of Additional (suggested) questions that training organisers might also like to ask. Please note: while the core question set is compulsory, Course leader(s) are encouraged to ask any @@ -87,13 +108,17 @@ your comments - which are not mandatory - are especially precious. We may share anonymised information with course presenters and developers as well as for wider quality/impact analyses. +> [Richel] Suggest to use 'The results will be posted online as-is, to make +> sure all voices get heard' + - Required ### Section 2 - Demographic Information -```text -[Richel]: I don't feel it is worth to bother our learners with question 1 below -``` +> [Richel]: I don't feel it is worth to bother our learners with question 1 +> below: I don't care. +> I do see its use in an intake form, but even there, I feel +> we should respect our learners' time. 1. Where did you see the course advertised? `advertised` @@ -107,9 +132,8 @@ well as for wider quality/impact analyses. - h. Internet search - i. Other (comments) -```text -[Richel]: I don't feel it is worth to bother our learners with question 2 below -``` +> [Richel]: I don't feel it is worth to bother our learners with question 2 below +> it will have no effect on my preparation 2. What is your career stage? `career_stage` @@ -120,15 +144,14 @@ well as for wider quality/impact analyses. - e. Industry scientist - f. Other (comments) -```text -[Richel]: I don't feel it is worth to bother our learners with question 3 below -``` +> [Richel]: I don't feel it is worth to bother our learners with question 3 +> below: +> it will have zero effect on my preparation 3. What is your host university? `host_university` -```text -[Richel]: I don't feel it is worth to bother our learners with question 4 below -``` +> [Richel]: I don't feel it is worth to bother our learners with question 4 below: +> it will have zero effect on my preparation 4. Gender `gender` @@ -238,9 +261,17 @@ Richel: I don't see how question 1 below would change my teaching 6. Any other comments? Comments -```text -[Richel]: I don't feel it is worth to bother our learners with question 7 below -``` +> [Richel]: I don't feel it is worth to bother our learners with question 7 below, +> for these reasons: +> +> - SETs ('Student Evaluations of Teaching') encourage poor +> teaching `[Stroebe, 2020]` +> - I do not care about 'satisfaction', instead I care about the learning +> outcomes. Sure, they may correlate, but I prefer to ask the thing I care for +> - Asking for satisfaction needlessly hurts teachers' feelings, as it allows +> bullying. I've seen two reasonable teachers (one of these me) get a '1' +> here. I hypothesize for both that this was because the learners simply +> did not like the teacher. We don't need to take such crap 7. PLEASE RATE EACH SESSION OF THE COURSE `satisfaction_per_session_YYYY_MM_DD_am/pm` @@ -252,7 +283,7 @@ Richel: I don't see how question 1 below would change my teaching - f. Excellent (5) ```text -[Richel]: I don't feel it is worth to bother our learners with question 7 +[Richel]: I don't feel it is worth to bother our learners with question 8 below, as we have question 5 ``` @@ -328,3 +359,15 @@ Now go make something great! + +## References + +- `[Stroebe, 2020]` Stroebe, W. (2020). Student Evaluations of Teaching + Encourages Poor Teaching and Contributes to Grade Inflation: A Theoretical + and Empirical Analysis. Basic and Applied Social Psychology, + 42(4), 276–294. +- `[Sitzmann & Johnson, 2014]` Traci Sitzmann and Stefanie Johnson. + "The paradox of seduction by irrelevant details: How irrelevant information + helps and hinders self-regulated learning." + Learning and Individual Differences (2014): 1-11. + [Download page](https://doi.org/10.1016/j.lindif.2014.05.009) diff --git a/docs/misc/exercise_procedure.md b/docs/misc/exercise_procedure.md deleted file mode 100644 index 460b8ac6b..000000000 --- a/docs/misc/exercise_procedure.md +++ /dev/null @@ -1,3 +0,0 @@ -# Exercise procedure - -See [here](https://richelbilderbeek.github.io/teaching/exercise_procedures/duos_in_breakout_rooms/). diff --git a/docs/misc/richel.md b/docs/misc/richel.md deleted file mode 100644 index 075dbf4f8..000000000 --- a/docs/misc/richel.md +++ /dev/null @@ -1,4 +0,0 @@ -# Richèl - -See Richèl's name's pronunciation -and teaching style [here](https://richelbilderbeek.github.io/teaching/who_is_richel/). diff --git a/docs/misc/wrap_up.md b/docs/misc/wrap_up.md new file mode 100644 index 000000000..5ee22a046 --- /dev/null +++ b/docs/misc/wrap_up.md @@ -0,0 +1,104 @@ +--- +tags: + - wrap-up + - wrap up + - conclusion + - summary +--- + +# Wrap-up + +!!!- info "Learning objectives" + + - Remember what the course was about + +## Why? + +!!! note "Course mottos" + + - Turning scripters into computer scientists + - Add theory to bolster already present practical skills + +To determine if the course mottos have held. + + +## Course overview + +```mermaid +flowchart TD + + classDef bjorn_node fill:#ddf,color:#000,stroke:#00f + classDef lars_node fill:#dfd,color:#000,stroke:#0f0 + classDef richel_node fill:#fdd,color:#000,stroke:#f00 + + sdlc[Software development lifecycle]:::lars_node + devtools[Software development tools]:::bjorn_node + + requirements[Requirements]:::lars_node + risk_analysis[Risk analysis]:::lars_node + + requirements --> issues + risk_analysis --> issues + + issues[Issues]:::richel_node + kanban_board[Kanban board]:::richel_node + team_roles[Team roles]:::richel_node + + team_roles <--> issues <--> kanban_board <--> team_roles + + team_roles --> pair_programming + + version_control_1[Version control on single branch]:::bjorn_node + version_control_many[Version control on multiple branches]:::bjorn_node + + version_control_1 --> version_control_many + + class_design[Class design]:::lars_node + + pair_programming[Pair programming]:::richel_node + tdd[TDD]:::richel_node + + testing[Testing]:::richel_node + code_reviews[Code reviews]:::bjorn_node + + data_structures[Data structures]:::richel_node + algorithms[Algorithms]:::richel_node + optimisation[Optimisation]:::richel_node + + modular_programming[Modular programming]:::lars_node + package[Package]:::richel_node + deployment[Deployment]:::bjorn_node + documentation[Documentation]:::bjorn_node + + + sdlc --> requirements + sdlc --> risk_analysis + devtools --> version_control_1 + + requirements --> class_design + version_control_1 --> requirements + version_control_1 --> risk_analysis + pair_programming --> tdd + pair_programming --> code_reviews + version_control_many --> code_reviews + class_design --> data_structures + version_control_1 --> tdd + tdd --> testing + issues --> testing + code_reviews --> data_structures + testing --> data_structures + testing --> code_reviews + testing --> algorithms + data_structures --> package + package <--> modular_programming + package --> optimisation + algorithms --> package + + package --> deployment + package --> documentation +``` + +> Overview of the course. +> Red: Richel. +> Green: Lars. +> Blue: Björn. diff --git a/docs/modularity/modular.md b/docs/modularity/modular.md index 27d943a7a..8fec5b16d 100644 --- a/docs/modularity/modular.md +++ b/docs/modularity/modular.md @@ -91,7 +91,7 @@ As discussed in the lesson The 4 most important relationship classes can have are association, composition and aggregation -#### Bad structure #### +#### Bad structure - `PetsIOwn` is a relation DB table not an object as it has - no function, which pets an owner has is not a object that exist in the real world - big semantic gap. diff --git a/docs/optimisation/big_o.R b/docs/optimisation/big_o.R index 4703e2eb2..350abc4e8 100755 --- a/docs/optimisation/big_o.R +++ b/docs/optimisation/big_o.R @@ -4,8 +4,12 @@ create_big_o_example <- function(n = seq(0, 100)) { t_wide$a <- 10 + log10(t_wide$n + 0.1) t_wide$b <- t_wide$n t_wide$c <- 0.001 * (t_wide$n ^ 2) - t_wide$total <- t_wide$a + t_wide$b + t_wide$c - t <- tidyr::pivot_longer(t_wide, cols = c("a", "b", "c", "total")) + if ("use_total" == "true") { + t_wide$total <- t_wide$a + t_wide$b + t_wide$c + t <- tidyr::pivot_longer(t_wide, cols = c("a", "b", "c", "total")) + } else { + t <- tidyr::pivot_longer(t_wide, cols = c("a", "b", "c")) + } colnames(t) <- c("n", "sub", "t") t } diff --git a/docs/optimisation/big_o.md b/docs/optimisation/big_o.md index c4a4c9d65..971958ecb 100644 --- a/docs/optimisation/big_o.md +++ b/docs/optimisation/big_o.md @@ -9,10 +9,7 @@ tags: !!!- info "Learning objectives" - - Understand misconceptions on optimisation - - Understand Amdahl's law - Practice to determine the big-O profile of a function - - Practice to get a run-time speed profile ???- question "For teachers" @@ -44,85 +41,114 @@ tags: Exercise 2 after the break: crit, after exercise_2, 5s ``` -## Problem +## Why? -Q: When to optimize for speed? +You've added a continuous integration script to measure which code +is spent most time in. You've made the program 10x as fast: +from 1 second, to 0.1 second. -A: +Likely, you've wasted your time. + +Instead, you want to optimize your code in a way that is useful. + +## Big O - Don't optimize without reason `[CppCore Per.1]` - Don't optimize prematurely `[CppCore Per.2]` - Don't optimize something that's not performance critical `[CppCore Per.3]` -## Problem - -Q: How to improve the run-time speed of an algorithm? - -. . . +## How to improve the run-time speed of an algorithm? > Make it work, make it right, make it fast. > > Kent Beck -A (simplified): +A simplified workflow is this: -1. Measure (hard to do @bartz2020benchmarking) +1. Measure (hard to do `[Bartz-Beielstein et al., 2020]`) 2. Think 3. Change code 4. Measure again -## Problem +???- question "What to measure?" -Q: How to improve the run-time speed of an algorithm? + There are two things one can measure: -A (simplified): + - Where the code spends its time + - How speed scales to increasingly complex input -1. Measure big-O -2. Measure speed profile -3. Think -4. Change code -5. Measure again -## Measurement 1: big-O +## Big-O How your (combination of) algorithms scales with more complex input. - Counting the words in a book: O(n) - Looking up a word in a dictionary: O(log2(n)) -:warning: Do measure big-O in release mode! +!!! warning "Do measure big-O in release mode" + + Do measure big-O in release mode! + + See the lesson on `assert` how to do so. + +???- question "Why?" -## Your algorithm + Debug mode -by definition- has more tests: + in our code, in the code used from other packages, + in the code produced by our compiler (if any). + When all tests pass, our program does not need these anymore. -![Many scatter plots](many_scatter_plots.png) + In debug mode, our speed measurements would take us + to the functions that test themselves most :-) -## Example +## Example 1 + +Your program runs three functions after each other: A, B and C. +All use the same input. + +You've measured how each of these functions take per input: ![Big O plot for 100](big_o_100.png) -:monocle_face: Work on B? +You want your benchmark to be short: +this full benchmark takes 1 second to run. -## Example +???- question "Which function would you improve?" -![Big O plot for 500](big_o_500.png) + B takes most time, so B -## Example +## Example 2 + +Out of curiosity, you've increased the complexities of +the benchmarking inputs. Now the picture looks like this: ![Big O plot for 2000](big_o_2000.png) -:sunglasses: No, work on C instead +The full benchmark now takes 100 second to run. + +???- question "Which function would you improve?" -## Discussion + C takes most time, so C + +## Conclusion Big-O helps to: - find algorithm to profile - make predictions -Agree yes/no +A benchmark done in debug mode is useless: +you care about your code doing actual work. + +A short benchmark time is useless: +you care more about complex input than simple input. +Using a continuous integration script to run a (max) two hour +benchmark is a convenient solution. + +## Exercises -## Exercise 1 +### Exercise 1 - Measure big-O complexity of @@ -147,7 +173,7 @@ def isprime(num): return False ``` -## Exercise 2 +### Exercise 2 - Measure big-O complexity of DNA alignment algorithm at @@ -161,3 +187,4 @@ def isprime(num): - `[CppCore Per.3]` C++ Core Guidelines: Per.3: Don't optimize something that's not performance critical [here](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per3-dont-optimize-something-thats-not-performance-critical) +- `[Bartz-Beielstein et al., 2020]` Bartz-Beielstein, Thomas, et al. "Benchmarking in optimization: Best practice and open issues." arXiv preprint arXiv:2007.03488 (2020). diff --git a/docs/optimisation/big_o_100.png b/docs/optimisation/big_o_100.png index af7c439aa..384f7a241 100644 Binary files a/docs/optimisation/big_o_100.png and b/docs/optimisation/big_o_100.png differ diff --git a/docs/optimisation/big_o_2000.png b/docs/optimisation/big_o_2000.png index edb28dc7f..8af5ed4c1 100644 Binary files a/docs/optimisation/big_o_2000.png and b/docs/optimisation/big_o_2000.png differ diff --git a/docs/optimisation/big_o_500.png b/docs/optimisation/big_o_500.png index a5a7475fc..fdcf40bc8 100644 Binary files a/docs/optimisation/big_o_500.png and b/docs/optimisation/big_o_500.png differ diff --git a/docs/optimisation/misconceptions.md b/docs/optimisation/misconceptions.md index 17b22cc5a..3ceb048c0 100644 --- a/docs/optimisation/misconceptions.md +++ b/docs/optimisation/misconceptions.md @@ -14,8 +14,6 @@ tags: - Understand misconceptions on optimisation - Understand Amdahl's law - - Practice to determine the big-O profile of a function - - Practice to get a run-time speed profile ???- question "For teachers" @@ -47,83 +45,184 @@ tags: Exercise 2 after the break: crit, after exercise_2, 5s ``` -## Optimisation misconceptions +## Why? -Q: What would be **bad advice** to improve the run-time speed of an algorithm? +There are a lot of misconceptions on optimisation. -Fill in in the shared document! - -(if you dare and have time: add good advice too) +You may prefer correct advice regarding this. ## Bad advice 1 -'Use C or C++ or Rust' +!!! warning "Bad advice 1" -Variance within programming languages is bigger than variance between -languages (adapted fig 2, from `[Prechelt, 2000]`) + Python is slow! Learn C or C++ or Rust to go fast! -![Figure 2, from Prechelt, 2000](prechelt_fig_2_sub.png) +???- question "Why does this advice make sense?" -## Bad advice 2 + C, C++ and Rust allows one to write direct machine code. + You can write the theoretical best machine code in ... well ... + machine code. Hence, these are indeed the theoretically fastest + languages. + + Python does not allow one to write machine code. + Hence, it cannot be as fast as the languages that can. -'No for loops', 'unroll for-loops', any other micro-optimization. +???- question "Why is this bad advice?" -Premature optimization is the root of all evil. -It likely has no measurable effect. + This is bad advice, because the variance within programming + languages is bigger than variance between + languages (adapted fig 2, from `[Prechelt, 2000]`): + + ![Figure 2, from Prechelt, 2000](prechelt_fig_2_sub.png) + + Instead of learning a faster language, learn how to be fast in + your language. ## Bad advice 2 -> We should forget about small efficiencies, -> say about 97% of the time: premature optimization is the root of all evil. -> Yet we should not pass up our opportunities in that critical 3%. -> -> Donald Knuth +!!! warning "Bad advice 2" -![Donald Knuth](donald_knuth.jpg) + - [any micro-optimization] + - Do not use for-loops! + - Unroll your for-loops! -> Source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/4/4f/KnuthAtOpenContentAlliance.jpg) + Or in code, this is 'bad': -## Bad advice 3 + ```python + my_values = get_values() + assert len(my_values) == 3 + sum = 0 + for i in range(3): + sum += my_values[i] + ``` + + This is 'better': + + ```python + my_values = get_values() + assert len(my_values) == 3 + sum = my_values[0] + my_values[1] + my_values[2] + ``` + +???- question "Why does this advice make sense?" -'Always parallelize' + The 'better' code does not contain a loop anymore, + hence needs to do less, hence is faster. + + These micro-optimizations may even have a measurable effect + when tested in isolation. + +???- question "Why is this bad advice?" + + > We should forget about small efficiencies, + > say about 97% of the time: premature optimization is the root of all evil. + > Yet we should not pass up our opportunities in that critical 3%. + > + > Donald Knuth + + ![Donald Knuth](donald_knuth.jpg) + + > Source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/4/4f/KnuthAtOpenContentAlliance.jpg) + + - Don't optimize without reason `[CppCore Per.1]` + - Don't optimize prematurely `[CppCore Per.2]` + - Don't optimize something + that's not performance critical `[CppCore Per.3]` + + It likely has no measurable effect in the context of a complete program: + the chance that this was the speed bottleneck is low. -- Maximum gain depends on proportion spent - in the parallelized part `[Rodgers, 1985]` -- Overhead is underestimated -- Hard to debug ## Bad advice 3 -![https://en.wikipedia.org/wiki/File:AmdahlsLaw.svg#file](amdahls_law.png) +!!! warning "Bad advice 3" + + 'Always parallelize' + +???- question "Why does this advice make sense?" + + Using more processors for the same calculation makes it + reasonable to asssume it goes faster. + + Parallellization of a single function may even have a measurable effect + when tested in isolation. + +???- question "Why is this bad advice?" + + First, it likely has no measurable effect in the context + of a complete program: the chance that this was the speed bottleneck is low. + + The speed-up of a program from parallelization is limited + by how much of the program can be parallelized. + This is Amdahl's law (and also found in `[Rodgers, 1985]`). + The figure belows shows the theoretical best + speed up redarding percentage of code that can be parallalized: + + ![https://en.wikipedia.org/wiki/File:AmdahlsLaw.svg#file](amdahls_law.png) + + The figure above shows the best possible speed increase. + However, there is overhead in parallalized code, as the + processes need to communicate with each other. + + Lastly, parallalized code is commonly harder to debug (with + irreproducible bugs) and harder to read. ## Bad advice 4 -'Optimize the function where you feel the performance problem is' +!!! warning "Bad advice 4" + + 'Optimize the function where you feel the performance problem is' + +???- question "Why does this advice make sense?" + + As developers, the more experience we get, the better + we understand our code. + +???- question "Why is this bad advice?" -Developers -also very experienced developers- are known -to have a bad intuition `[Sutter & Alexandrescu, 2004]` + Developers -also very experienced developers- are known + to have a bad intuition `[Sutter & Alexandrescu, 2004]` -Instead (from `[Chellappa et al., 2008]`): + Instead (from `[Chellappa et al., 2008]`): -1. find the code that the program spends most time in -2. measure the timing of that code -3. analyze the measured runtimes + 1. find the code that the program spends most time in + 2. measure the timing of that code + 3. analyze the measured runtimes ## Bad advice 5 -'Optimize each function' +!!! warning "Bad advice 5" -- The 90-10 rule: 90% of all time, the program spends in 10% of the code. -- Your working hours can be spent once + 'Optimize each function' + +???- question "Why does this advice make sense?" + + If we optimize each function, the full program will be faster! + +???- question "Why is this bad advice?" + + - Don't optimize without reason `[CppCore Per.1]` + - Don't optimize prematurely `[CppCore Per.2]` + - Don't optimize something + that's not performance critical `[CppCore Per.3]` + - The 90-10 rule: 90% of all time, the program spends in 10% of the code. + - Your working hours can be spent once ## References -- `[Prechelt, 2000]` Prechelt, Lutz. "An empirical comparison of c, c++, java, perl, python, rexx and tcl." IEEE Computer 33.10 (2000): 23-29. -- `[Rodgers, 1985]` Rodgers, David P. "Improvements in multiprocessor system design." ACM SIGARCH Computer Architecture News 13.3 (1985): 225-231. -- `[Sutter & Alexandrescu, 2004]` Sutter, Herb, and Andrei Alexandrescu. C++ coding standards: 101 rules, guidelines, and best practices. Pearson Education, 2004. - `[Chellappa et al., 2008]` Chellappa, Srinivas, Franz Franchetti, and Markus Püschel. "How to write fast numerical code: A small introduction." Generative and Transformational Techniques in Software Engineering II: International Summer School, GTTSE 2007, Braga, Portugal, July 2-7, 2007. Revised Papers (2008): 196-259. +- `[CppCore Per.1]` C++ Core Guidelines: Per.1: Don't optimize without reason + [here](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rper-reason) +- `[CppCore Per.2]` C++ Core Guidelines: Per.2: Don't optimize prematurely + [here](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per2-dont-optimize-prematurely) +- `[CppCore Per.3]` C++ Core Guidelines: Per.3: + Don't optimize something that's not performance critical + [here](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per3-dont-optimize-something-thats-not-performance-critical) +- `[Prechelt, 2000]` Prechelt, Lutz. "An empirical comparison of c, c++, java, perl, python, rexx and tcl." IEEE Computer 33.10 (2000): 23-29. +- `[Rodgers, 1985]` Rodgers, David P. "Improvements in multiprocessor system design." ACM SIGARCH Computer Architecture News 13.3 (1985): 225-231. +- `[Sutter & Alexandrescu, 2004]` Sutter, Herb, and Andrei Alexandrescu. C++ coding standards: 101 rules, guidelines, and best practices. Pearson Education, 2004. diff --git a/docs/optimisation/runtime_speed_profiles.md b/docs/optimisation/runtime_speed_profiles.md index 9dc99e531..c9bf32a69 100644 --- a/docs/optimisation/runtime_speed_profiles.md +++ b/docs/optimisation/runtime_speed_profiles.md @@ -11,9 +11,6 @@ tags: !!!- info "Learning objectives" - - Understand misconceptions on optimisation - - Understand Amdahl's law - - Practice to determine the big-O profile of a function - Practice to get a run-time speed profile ???- question "For teachers" @@ -49,19 +46,20 @@ tags: ## Why? -- See which code is spent most time in -- :monocle_face: Use an input of suitable complexity - - Note to self: next example should take at least 10 seconds! -- :sunglasses: Consider using CI to obtain a speed profile every push! +> It is far, far easier to make a correct program fast, than it is to make a fast program correct. +> +> Herb Sutter + +![Herb Sutter](herb_sutter.jpg) + +> Source [Wikimedia](https://commons.wikimedia.org/wiki/Category:Herb_Sutter#/media/File:Professional_Developers_Conference_2009_Technical_Leaders_Panel_7.jpg) -## Run-time speed profile: code +You've found out an input of sufficient complexity. +You now need to measure which code is spent most time in -- [ ] Show R code in repo -- [ ] Run R code from RStudio -- [ ] Show Python code in repo -- [ ] Run Python code from command line +You are making a run-time speed profile! -## Myth 1 +## Another myth ```python def slow_tmp_swap(x, y): @@ -79,56 +77,140 @@ def superfast_xor_swap(x, y): - [C++ Core Guidelines: Per.4: Don't assume that complicated code is necessarily faster than simple code](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per4-dont-assume-that-complicated-code-is-necessarily-faster-than-simple-code) - [C++ Core Guidelines: Per.5: Don't assume that low-level code is necessarily faster than high-level code](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per5-dont-assume-that-low-level-code-is-necessarily-faster-than-high-level-code) +- [C++ Core Guidelines: Per.6: Don't make claims about performance without measurements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per6-dont-make-claims-about-performance-without-measurements) -## Exercise 1 \[30 mins\] +## How to create a run-time speed profile? -Create speed profile of any function you like. +- Use an input of suitable complexity +- The code to be run should take at least 10 seconds +- Consider using CI to obtain a speed profile every push! -- [ ] Remind Python and R code on learner's repo +In our project, this is the current main function: -## Exercise 2 \[SKIP\] +```python +if __name__ == "__main__": + run_experiment("parameters.csv", "results.csv") +``` -Create speed profile of +We've tuned `parameters.csv` to create input of the right complexity. -## Exercise 3 \[SKIP\] +To run-time speed profile this code, run instead: -Create speed profile of DNA alignment +```python +import cProfile +cProfile.run('run_experiment("parameters.csv", "results.csv")') +``` -## Step 3: Think +This will look similar to this: -- How to achieve the same with less calculations? - - Aim to change big-O, not some micro-optimization - - For example, store earlier results in a sorted look-up table +```bash +$ /bin/python3 /home/sven/programming_formalisms_project/main.py + 6 function calls in 0.000 seconds -> Feynman Problem Solving Algorithm: -> -> 1. Write down the problem. -> 2. Think very hard. -> 3. Write down the answer + Ordered by: standard name + + ncalls tottime percall cumtime percall filename:lineno(function) + 1 0.000 0.000 0.000 0.000 :1() + 1 0.000 0.000 0.000 0.000 experiment.py:3(run_experiment) + 1 0.000 0.000 0.000 0.000 {built-in method builtins.exec} + 2 0.000 0.000 0.000 0.000 {built-in method builtins.isinstance} + 1 0.000 0.000 0.000 0.000 {method 'disable' of '_lsprof.Profiler' objects} +``` -## Step 4: Measure again +This is what the columns mean (simplified from [the Python profiling manual](https://docs.python.org/3/library/profile.html)): -In TDD, this test would have been present already: +Parameter|Description +---------|--------------------------- +`ncalls` |The number of times the function is called +`tottime`|The total time spent in the given function +`percall`|The time spent in the given function per call +`cumtime`|The cumulative time spent in this and all subfunctions +`percall`|The cumulative time spent in this and all subfunctions per call + +## Test for increase in runtime speed + +Imagine improving the speed of `function_a`. +You create a function called `function_b` that +should be faster. +You use TDD to have a test to work on: ```python assert 10.0 * get_t_runtime_b() < get_t_runtime_a() ``` -Adapt the constant to reality. +Adapt the constant to your preference. -- [C++ Core Guidelines: Per.6: Don't make claims about performance without measurements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#per6-dont-make-claims-about-performance-without-measurements) +## Exercises -## Recap quote +### Exercise 1: read a run-time speed profile -> It is far, far easier to make a correct program fast, than it is to make a fast program correct. -> -> Herb Sutter +Take a look at this speed profile: -![Herb Sutter](herb_sutter.jpg) +```bash + ncalls tottime percall cumtime percall function + 1 97.000 97.000 97.000 97.000 function_a + 1 1.000 1.000 1.000 1.000 function_b + 1 2.000 2.000 2.000 2.000 function_c +``` -> Source [Wikimedia](https://commons.wikimedia.org/wiki/Category:Herb_Sutter#/media/File:Professional_Developers_Conference_2009_Technical_Leaders_Panel_7.jpg) +- Which function will you work on? + +???- question "Answer" + + `function_a`: as 97 out of a 100 seconds, Python was running + it code. + +- Imagine you have improved that function. How much faster will your + program maximally be? + +???- question "Answer" + + If `function_a` is made to take 0 seconds, your program + still takes 3 seconds. You've made the code (100 sec / 3 sec =) 33.3x + faster. + +- Would it be worth your time? + +???- question "Answer" + + This depends on you. + +### Exercise 2: read a run-time speed profile + +Take a look at this speed profile: + +```bash + ncalls tottime percall cumtime percall function + 1 40.000 40.000 40.000 40.000 function_a + 1 30.000 30.000 30.000 30.000 function_b + 1 20.000 20.000 20.000 20.000 function_c + 1 10.000 10.000 10.000 10.000 function_d +``` + +- Which function will you work on? + +???- question "Answer" + + `function_a`: as 40 out of a 100 seconds, Python was running + it code. + +- Imagine you have improved that function. How much faster will your + program maximally be? + +???- question "Answer" + + If `function_a` is made to take 0 seconds, your program + still takes 60 seconds. You've made the code (100 sec / 60 sec =) 1.67x + faster. + +- Would it be worth your time? + +???- question "Answer" + + This depends on you. -## Case study +### Exercise 3: create a run-time speed profile -- [ ] Show ProjectRampal +Follow the steps at 'Create a run-time speed profile' +in your own code, to obtain your own run-time speed profile diff --git a/docs/package/README.md b/docs/package/README.md index d9d88d832..cfcc43ad0 100644 --- a/docs/package/README.md +++ b/docs/package/README.md @@ -11,7 +11,8 @@ tags: - Understand how to package a Python project - Package our Python project locally - - Run a script with out Python project + - Run a script with our Python project + - Upload our package to PyPI ???- question "For teachers" @@ -45,12 +46,16 @@ tags: ## Why? +![bacsim on PyPI](bacsim_on_testpypi.png) + +> `bacsim` on (the test version of) PyPI + You want to share or re-use your work in the regular way. ## Exercises -### Exercise 1: Install and use a Python package +### Exercise 1: install package locally - Scan the ['Python Packaging User Guide' section on 'Packaging Python Projects'](https://packaging.python.org/en/latest/tutorials/packaging-projects/) @@ -142,3 +147,90 @@ in the regular way. If you get an error such as `Cannot find file 'parameters.csv'` it means that our package is installed successfully. Sure, it does not do actual work, but it is installed! + + +### Exercise 2: upload package to PyPI + +#### Exercise 2.1: Build the package distribution files + +Follow the steps at [here](https://packaging.python.org/en/latest/tutorials/packaging-projects/): + +Install `build`: + +```bash +python3 -m pip install --upgrade build --break-system-packages +``` + +Running `build`: + +```bash +python3 -m build +``` + +???- question "How does that look like?" + + ```text + richel@richel-N141CU:~/GitHubs/programming_formalisms_project_autumn_2024$ python3 -m build + * Creating isolated environment: venv+pip... + * Installing packages in isolated environment: + - hatchling + * Getting build dependencies for sdist... + * Building sdist... + * Building wheel from sdist + * Creating isolated environment: venv+pip... + * Installing packages in isolated environment: + - hatchling + * Getting build dependencies for wheel... + * Building wheel... + Successfully built bacsim-1.0.1.tar.gz and bacsim-1.0.1-py3-none-any.whl + ``` + +Now there will be files in the `dist` folder: + +???- question "How does that look like?" + + ```bash + richel@richel-N141CU:~/GitHubs/programming_formalisms_project_autumn_2024$ ls dist/ + bacsim-1.0.1-py3-none-any.whl bacsim-1.0.1.tar.gz + ``` + +Well done, you've just created the package distribution files! + +#### Exercise 2.2: Upload our package distribution + +Last step is to upload our package distribution files +to [https://test.pypi.org](https://test.pypi.org): + +Install `twine`: + +```bash +python3 -m pip install --upgrade twine --break-system-packages +``` + +After registering to [https://test.pypi.org]( https://test.pypi.org), you +have the API token be allowed to upload to testPyPI. Upload: + +```bash +python3 -m twine upload --repository testpypi dist/* +``` + +???- question "How does that look like?" + + ```bash + richel@richel-N141CU:~/GitHubs/programming_formalisms_project_autumn_2024$ python3 -m twine upload --repository testpypi dist/* + Uploading distributions to https://test.pypi.org/legacy/ + Enter your API token: + Uploading bacsim-1.0.1-py3-none-any.whl + 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 24.8/24.8 kB • 00:00 • 72.3 MB/s + Uploading bacsim-1.0.1.tar.gz + 100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.6/1.6 MB • 00:00 • 8.5 MB/s + + View at: + https://test.pypi.org/project/bacsim/1.0.1/ + ``` + +Indeed, the package can now be found at [https://test.pypi.org/project/bacsim/1.0.1/](https://test.pypi.org/project/bacsim/1.0.1/). + +???- question "How does that look like?" + + ![bacsim on PyPI](bacsim_on_testpypi.png) diff --git a/docs/package/bacsim_on_testpypi.png b/docs/package/bacsim_on_testpypi.png new file mode 100644 index 000000000..63cceef77 Binary files /dev/null and b/docs/package/bacsim_on_testpypi.png differ diff --git a/docs/project/issues.md b/docs/project/issues.md index b0ce59949..4a8b82e45 100644 --- a/docs/project/issues.md +++ b/docs/project/issues.md @@ -70,7 +70,6 @@ In any project, you should create a shared "to-do" list, such as an issue tracker `[Wilson et al, 2017]`. - English |Issue |Describe ------------------------|-------------------------------|---------------------------------------- This needs to be done! |Create an issue |Why and what needs to be done @@ -260,11 +259,11 @@ For that, a [kanban board](kanban_board.md) is used instead. "The social nature of issue tracking in software engineering." University of Calgary (2009). - `[Bugzilla, 2009]` Bugzilla (2009). Life Cycle of a Bug. - Retrieved October 30, 2009 from + Retrieved October 30, 2009 from - `[Gunderloy, 2007]` Gunderloy, Mike, ed. Painless project management with FogBugz. Berkeley, CA: Apress, 2007. - `[Wilson et al, 2017]` Wilson, Greg, et al. - "Good enough practices in scientific computing." - PLoS computational biology 13.6 (2017): e1005510. + "Good enough practices in scientific computing." + PLoS computational biology 13.6 (2017): e1005510. [here](https://doi.org/10.1371/journal.pcbi.1005510) diff --git a/docs/schedule.md b/docs/schedule.md index a7f79d088..a3752998a 100644 --- a/docs/schedule.md +++ b/docs/schedule.md @@ -20,10 +20,10 @@ Monday |15:40-16:00|Lars |Confidence and retrospect ||||| Tuesday |09:00-10:00|Lars |[Software development life cycle](./introductions/sdlc.md) Tuesday |10:15-11:00|Richel |[Issues](project/issues.md) and [kanban board](project/kanban_board.md) and [team roles](project/team_roles.md) -Tuesday |11:15-12:00|Richel |[assert](algorithms/assert.md), [TDD](tdd/README.md) +Tuesday |11:15-12:00|Richel |[assert](algorithms/assert.md) Tuesday |13:00-14:00|Richel |[TDD](tdd/README.md) Tuesday |14:15-15:00|Richel |[TDD](tdd/README.md) -Tuesday |15:00-15:40|Richel |[formal testing framework](testing/testing_framework.md) +Tuesday |15:00-15:40|Richel |[Formal testing framework](testing/testing_framework.md) Tuesday |15:40-16:00|Lars |Confidence and retrospect ||||| Wednesday|09:00-10:00|Björn |[Formal git workflow, branches](./git/branches.md) @@ -31,7 +31,7 @@ Wednesday|10:15-11:00|Björn |[Formal git workflow, merge](./git/merge.md) Wednesday|11:15-12:00|Björn |[Formal git workflow, contribute](./git/contribute.md) & [Social coding and sharing](./social_coding/social_coding.md) Wednesday|13:00-14:00|Richel |[Pair programming](pair_programming/README.md) Wednesday|14:15-15:00|Richel |[Pair programming](pair_programming/README.md) -Wednesday|15:15-15:40|Richel |[formal testing framework](testing/testing_framework.md) +Wednesday|15:15-15:40|Richel |[Formal testing framework](testing/testing_framework.md) Wednesday|15:40-16:00|Lars |Confidence and retrospect ||||| Thursday |09:00-10:00|Lars |[Object-oriented design](design_develop/OO_development.md) @@ -46,8 +46,8 @@ Friday |09:00-10:00|Richel |[Implement the project as a package](package/READM Friday |10:15-11:00|Richel |[Optimisation misconceptions](optimisation/misconceptions.md), [Big O](optimisation/big_o.md), [runtime speed profiles](optimisation/runtime_speed_profiles.md) Friday |11:15-13:30|Björn |[Deployment](deployment/deploy.md) Friday |13:30-15:00|Björn |[Documentation](deployment/documentation.md) -Friday |15:15-15:40|Richel |Wrap-up -Friday |15:40-16:00|Richel |Confidence and retrospect +Friday |15:15-15:40|Richel |[Wrap-up](misc/wrap_up.md) +Friday |15:40-16:00|Lars |Confidence and retrospect diff --git a/docs/social_coding/social_coding.md b/docs/social_coding/social_coding.md index 9b5af217d..c9e2b7169 100644 --- a/docs/social_coding/social_coding.md +++ b/docs/social_coding/social_coding.md @@ -194,7 +194,7 @@ you would like to reuse, you may look at the following things to determine its reusability: !!! note - + This can be now reconnected to question 4 (above). - Date of last code change diff --git a/docs/testing/testing_framework.md b/docs/testing/testing_framework.md index c5432f0d8..ca7e92fca 100644 --- a/docs/testing/testing_framework.md +++ b/docs/testing/testing_framework.md @@ -472,6 +472,6 @@ In this course, you've written some functions yourself. learning, and improve the quality of your team’s research." American Journal of Epidemiology 190.10 (2021): 2172-2177. - `[Wilson et al, 2017]` Wilson, Greg, et al. - "Good enough practices in scientific computing." - PLoS computational biology 13.6 (2017): e1005510. + "Good enough practices in scientific computing." + PLoS computational biology 13.6 (2017): e1005510. [here](https://doi.org/10.1371/journal.pcbi.1005510) diff --git a/evaluations/2024_autumn/20241118.md b/evaluations/2024_autumn/20241118.md new file mode 100644 index 000000000..ff5871f6a --- /dev/null +++ b/evaluations/2024_autumn/20241118.md @@ -0,0 +1,59 @@ +# Programming formalisms — Shared document Nov 2024 + +- 2024-11-18 +- Distilled from shared document of same date + +## What helped us learn (let us move forward) + +- A: Good discussions in breakout rooms, great support, diverse experience of audience, frequent breaks +- A: Discussion +- A: Discussions in breakout rooms +- A: Really well developed documentation with instructions and examples, hints etc +- A: Discussions +- A: The explanations and discussions +- A: Answering quickly on the team sessions to questions +- A: Having clear example on what to do help us to finish and understand the exercises better +- A: Discussions on real-life situations +- A: Having access to examples of done documents. +- A: Interactive discussions, input from everyone. + +## What stopped us from learning (What held us back) + +- A: In some cases lack of concrete examples, the project itself wasn't that integrated into some of the exercises, sometimes not clear how to apply to research, often topics are more applicable to rly large projects, lecture closely matched course document +- A: +- A:Short times in the breakout rooms +- A: Sometimes goals werent super clear (ie how to write requirements from scratch) +- A:Clearer documentation in some points +- A:Not getting used to the abbreviations quick enough and then not knowing what was being discussed +- A: course content in the website changing when it was already needed +- A:Unclear instructions on the assignments +- A: No clear instruction on what to do. Having example will help. +- A:Unclear directions +- A: For some discussions there was very limited time in breakout rooms +- A: Limited time +- A: Not accurate information (links, instructions) in the course documents. + +## What could we do to improve learning (What can we invent) + +- A:Write a clearer documentation in some points and perhaps a "dictionary" for main terms +- A:More examples +- A:Write tasks more clearly (for example "Task 1: Do this or that") +- A: More hidden hints with correct answers +- A: Have a terminology section where abbreviations or more technical terms are defined in a clear and easy to find manner +- A:Separate presentation and course document, more info on how to apply to 1-person research (esp. risk section), Prepare a gold-standard requirements file so all participants can be on same page +- A: Since we are a small group, we could work independently and share with everyone, instead of breakout rooms +- A: Hints with instructions and directions for technical parts and possible issues +- A: Make a concrete example not specifically related to the exercise, especially given a limited time to do it. +- A:Phrase the exercises concisely already in the course website +- A:Give an example before move into the assignment + +## What will we do(Act) [Teachers only] + +- [Lars] - Go back to separate Lecture and Website documentation +- [Lars] - Double check Formatting of website markdown +- [Lars] - Add examples directly into hints. +- [Lars] - Clear tasks with hidden do a, then b then c. +- [Lars] - clearer links to example documentation gold-standard project. +- [Lars] add examples of how this helps if you are a solo developer.(Long term, as current examples are more team focused) +- [Lars] relate to more concrete resarch focused examples. +- [Lars] Examples don't need to read the text. diff --git a/evaluations/2024_autumn/20241119.md b/evaluations/2024_autumn/20241119.md new file mode 100644 index 000000000..a956f9c7c --- /dev/null +++ b/evaluations/2024_autumn/20241119.md @@ -0,0 +1,54 @@ +# Programming formalisms — Shared document Nov 2024 + +- 2024-11-19 +- Distilled from shared document of same date + +## What helped us learn (let us move forward) + +- A: Was interesting to discuss and read more, and figure it out by ourselves. +- A: Teamwork and discussions was good +- A: Having practical example really help and discuss it. Video helps too. +- A: +- A: Examples in the form of screenshots +- A: Examples in the documentation, the interaction activity between teacher and student, the discussion. +- A: +- A: Working together on problems +- A: Having examples in the information pages, and answers +- A: Better examples and clearer instructions + +## What stopped us from learning (What held us back) + +- A: A very fast pace, at times there was too much info to absord (ie unit testing) +- Having to juggle both doing something for the project and also focusing on the exercises at the same time +- A: Lack of time to complete the exercises. +- A:Not knowing form the start exactly what to do during the exercises +- A: Little time to work on exercises after understanding all the info +- A: Laggy teaching video +- A: From simple example to applying it to project design in a short period of time is quiet challenging. +- A: Not knowing where to find certain things (kambam board, the correct learners folder etc) +- A: Not knowing from where to start and to where to go +- A: Not enough time for the exercises, not knowing the time limit for the exercises. +- A: Teaching video not working properly, wasn't able to see the code properly because of this. + +## What could we do to improve learning (What can we invent) + +- A: Give more time to absorb information before having to apply it on a big project +- A: Either focus on simpler exercises and learning or focus on project work +- A: More clear tasks +- A: Focusing on less topics and working on those more deeply and with more time +- A: take into account the time that these feedback sessions need (second day that the last exercise session is cut short) +- A: In the teaching video show both the code and where it is being copied from, for clarity +- A: Give more time +- A: Maybe more time or simpler(focused) exercises. +- A: +- A: Tell us how much time we have for completing all exercises. Helps us to not spend too much time on just one of the exercises and then the time is up without us knowing. + +## What will we do(Act) [Teachers only] + +- [ ] [Fix video](https://github.com/UPPMAX/programming_formalisms/issues/98) +- [ ] More time (in multiple forms): + - [Discuss with team: should I/we reduce my/own content and/or remove the project?](https://github.com/UPPMAX/programming_formalisms/issues/99) + - RB: I volunteer to reduce content and suggest to keep the project +- [ ] Mix of simple exercises and project work: + - [Discuss with team: should I/we remove the project or schedule it as project hours?](https://github.com/UPPMAX/programming_formalisms/issues/100) + - RB: I volunteer to schedule some of my hours as project hours diff --git a/evaluations/2024_autumn/20241120.md b/evaluations/2024_autumn/20241120.md new file mode 100644 index 000000000..1d26e386d --- /dev/null +++ b/evaluations/2024_autumn/20241120.md @@ -0,0 +1,47 @@ +# Programming formalisms — Shared document Nov 2024 + +- 2024-11-20 +- Distilled from shared document of same date + +## What helped us learn (let us move forward) + +- A: More time to finish exercises +- A: Working in pairs and doing exercises together +- A: Taking a longer time to do exercises and learn and understand what we are doing +- A:Very nice graphics for helping do exercises today +- A:Getting clearer examples on the formal testing +- A:Clear instructions and more time to finish. +- A:Appropriate time to complete the exercises and having goos resources by hand to check theory and examples. +- A: Having enough time to understand and to work together the exercise really help a lot to understand and finish the task. +- A: Working together, discussion, exercises. +- A: Pair programming exercise was really nice, testing documentation was great + +## What stopped us from learning (What held us back) + +- A: Testing could've been a bit deeper. Covering things like mocking. No idea how good pair programming is supposed to look like in practice (only in theory). +- A: Such lack in code knowledge. +- A: Didn't know exactly how to do the formal testing in pycharm +- A: Certain knowledge gaps when it comes to python coding +- A: Unit testing being a difficult concept +- A: the pull request exercise and the pretend code review exercise were very similar. +- A: VS code not cooperating with the testing module +- A: Some exercises was a bit confusing (ex Exercise 2: put example code to fit the testing framework) +- A: Coding knowledge influence the speed to do the exercises and how much we understan. +- A: The morning lectures seem didn't explain clearly + +## What could we do to improve learning (What can we invent) + +- A: Maybe perform a quick round of pair programming with the teachers, to me it was not clear how to behave as navigator and I felt like I was micromanaging and being a bad navigator. Refer to online documents for further research in testing (maybe I just missed it). Distribute a cheat sheet after each day summarizing most important? +- A: Include tutorial link or something to get testing to work in another IDE than vs code, instead of just saying "try to get it to work in your IDE". +- A: +- A: More examples for each topic +- A: If possible simplify things even further, or expand on rationale behind each step not just "big picture" +- A: Maybe have a example on testing the code. +- A:Having "extra" exercises that are more difficult that one can try when done with the regular exercises. +- A: Make the lecture clear and concise. Better to give a practical examples than just explain the concept. +- A: Give more practical examples of git forking and branching and when it is appropriate to use them. +- A: Maybe more practical examples. + +## What will we do(Act) [Teachers only] + +- See Richel's reflection of the day diff --git a/evaluations/2024_autumn/20241121.md b/evaluations/2024_autumn/20241121.md new file mode 100644 index 000000000..cd3871691 --- /dev/null +++ b/evaluations/2024_autumn/20241121.md @@ -0,0 +1,60 @@ +# Programming formalisms + +- 2024-11-21 +- Distilled from shared document of same date + +## What helped us learn (let us move forward) + +- A: Good with range in difficulty. Group exercises are great! +- A: Bigger range in difficulty of exercises +- A: Group learning is always fun. Frequent brakes. The reading for a few minutes into discussion is nice if you call someone out! + otherwise it drags a bit bc no one dares to speak first +- A: The tips and code snippets for helping do exercises +- A: Range of difficulties help assess first the things you understand. Pair programming really help. +- A: Designated time for reading is good! + +## What stopped us from learning (What held us back) + +- A: Not following schedule is a bit confusing, I think we worked on thursday, tuesday and wednesday today. +- A: felt like some topics were almost skipped over (obviously due to time). + But if we dont have time for them maybe we do not need to bring them up. +- A: The concepts themselves being very abstract and difficult +- A: Some of the topics are hard to learn while not actually applying them. + E.g. while I think I have a good grasp of what modular programming is + I'm not sure I could recognize it. +- A: Applying the lesson directly to the field that you are not familiar with + kinda need more time. Additionally, just watching lecture video for a + specific topic to learn sometimes is not helpful cause there are concept + introduce that was not mentioned in class. +- A: Starting the day with the most difficult part of the day + (before properly waking up haha) +- A: The youtube lecture was a bit hard to follow, + could be better with more examples and images. + +## What could we do to improve learning (What can we invent) + +- A: Maybe use the workflow: individual reading -> discussion + -> exercises in group for stuff like modular programming. + Also be more clear with the schedule + I got lost a few times today after zoning out. +- A: Give more concrete examples for the abstract concepts + (like what are objects in the programming world) +- A: The function design discussion was nice, + maybe follow that format more. +- A: Maybe have a table of definitions and their equivalent names in + object oriented programming and non-object-oriented, including the + relationsnhips between them. (classes, methods, functions etc) +- A: Give code examples of modular programming and refactoring + +#### What will we do(Act) [Teachers only] + +- Changing schedule is a problem + - [ ] Explain we do student-centered learning on Day 1 of the course + [#111](https://github.com/UPPMAX/programming_formalisms/issues/111) +- [ ] Make list of definitions [#112](https://github.com/UPPMAX/programming_formalisms/issues/112) +- [ ] More code examples [#113](https://github.com/UPPMAX/programming_formalisms/issues/113) +- [ ] Remove YouTube video for modular programming + [#114](https://github.com/UPPMAX/programming_formalisms/issues/114) +- [ ] Give more concrete examples for the abstract concepts in OOP + [#115](https://github.com/UPPMAX/programming_formalisms/issues/114) + diff --git a/evaluations/2024_autumn/20241122.md b/evaluations/2024_autumn/20241122.md new file mode 100644 index 000000000..eb7f74c4d --- /dev/null +++ b/evaluations/2024_autumn/20241122.md @@ -0,0 +1,34 @@ +# Programming formalisms + +- 2024-11-21 +- Distilled from shared document of same date + +## What helped us learn (let us move forward) + +- A: Great references for future use +- A: Exercises, group work +- A: Having the code snippets up on the course website to use and those snippets having explanations too. +- A: The exercises help me understand the lectures. Working in groups is really good. +- A: Working in groups to test out the theory was super useful +- A: Working in groups, the examples and discussions. +- A: Group work + +## What stopped us from learning (What held us back) + +- A: Windows code snippets not working, took a lot of time from the exercises +- A: Not all the commands working on Windows +- A: Not knowing where to make the exercise files, was not specified in instructions +- A: Some of the provided commands did not seem to work for windows. Had to improvise. +- A: Felt like the goals were not as clear today. Difficult to transfer the topics from today in a lecture. Felt like the project was not complex/functional enough to write proper documentation +- A: Unclear guide in the exercises (specifically in the documentation) +- A: Some things were very fast for me. + + +## What could we do to improve learning (What can we invent) + +- A: Have a more functional project for which writing documentation actually provides worth. Installation/requirements/etc were not extensive enough for the exercises imo. Also maybe resetting the state of the project Github so everyone is on same page? +- A: Adding commands that work on windows as well as mac/linux +- A: Put everything practical that we are supposed to do within the exercises. It's a bit confusing when some parts are in the "theory part" with code that we are supposed to use and some parts are in "exercises" +- A: Have more realizable project. Make the guide much clearer. +- A: Early on ask about experience level amongst the group and group people based on their experience to enable more difficult exercises to be done. +- A: More clear exercises, specifying some points such as direction, folder etc. Something like step-by-step as well as in some examples and exercises. diff --git a/evaluations/2024_autumn/teacher_comments.csv b/evaluations/2024_autumn/teacher_comments.csv new file mode 100644 index 000000000..6e4cb5f06 --- /dev/null +++ b/evaluations/2024_autumn/teacher_comments.csv @@ -0,0 +1,5 @@ +Timestamp,What did Richèl do well,What could Richèl Improve,What did Björn do well,What could Björn Improve,What did Lars do well,What could Lars Improve +11/22/2024 15:29:10,"I think Richèl carry this course. He explained well his lectures and give very good exercises. He asked good questions that challenges our thinking. He seems very prepare everyday and always there to help. Additionally, he listens to comments and give really good insight. ",He is really good already. Just continue it. ,I like his lecture in git and giving nice exercise on that. ,I think next time avoid just reading the page. Simplify things and asks questions and encourage student to answer.,Lars really give good insight most of the time while in lecture or even in the side. ,"I think the exercises, maybe make it more understandable and assess the time needed to accomplish it. Also, there is a room for improvement in the lecture. " +11/22/2024 15:39:39,Involving everyone with the discussions,Clearer exercises. This became clearer as the course went along,Clear theory parts on the subjects,Clearer exercises,Giving helpful tips when needed,Clearer exercises +11/22/2024 15:43:41,Explain everything super well and be very positive about everything,Remake the video that was in one of the days that lagged,Explain very vague concepts in an understandable way,"When asking questions, make them more specific so that people are more apt to answer",Give a lot of extra knowledge that was not always in the website,"Give a lot more real-life practical examples when explaining concepts, that would help a lot" +11/22/2024 16:47:08,Really great engagement and explanations. Calling people out for discussion greatly improved flow. Really felt like his heart was in the course.,Tbh I'm really not finding anything.,Good help during the exercises.,"Was at points difficult to follow the lectures, because he just read the course material out loud. Could benefit from a more free style of lecturing! ","Great knowledge, really helpful. ",Feel like it would be great to see him do a pair-programming exercise together with another lecturer. Got the impression that he's someone who can showcase how to be a navigator. diff --git a/evaluations/2024_autumn/teacher_comments.ods b/evaluations/2024_autumn/teacher_comments.ods new file mode 100644 index 000000000..6ed52d40f Binary files /dev/null and b/evaluations/2024_autumn/teacher_comments.ods differ diff --git a/lesson_plans/2024_autumn/20241121_richel.md b/lesson_plans/2024_autumn/20241121_richel.md index ad9eb4f0e..bcc9de013 100644 --- a/lesson_plans/2024_autumn/20241121_richel.md +++ b/lesson_plans/2024_autumn/20241121_richel.md @@ -121,7 +121,7 @@ I checked Lars' material, I think the current order will work :-) - I can give a function a proper name - I can criticise functions - I can write a class to express what the data it contains -- I inderstand difference between composition and aggregation +- I understand difference between composition and aggregation - I understand the type of relation 'composition' is - I understand the type of relation 'inheritance' is - I can write a class that is composed of another class diff --git a/lesson_plans/2024_autumn/20241122_richel.md b/lesson_plans/2024_autumn/20241122_richel.md new file mode 100644 index 000000000..17a2fa83a --- /dev/null +++ b/lesson_plans/2024_autumn/20241122_richel.md @@ -0,0 +1,40 @@ +# Lesson plan Autumn 2024 + +- Author: Richel +- Date: 2024-10-22 + +## Some questions for Friday evaluation: + +- git from command line or git from VS Code? +- name a maximal of 3 topics you want us to discuss to be removed +- name a maximal of 3 topics you want us to discuss to put more time in +- more theory or more exercises? +- more theory or more work on learners' project? + +## Status + +- Implement the project as a package 4/10 +- Optimisation misconceptions 3/10 +- Big O 3/10 +- Runtime speed profiles 3/10 +After lunch: +- Wrap-up +- Confidence and retrospect + +So 4 things before 8:30, let's plan: + +- [x] 6:15-6:45 Implement the project as a package 6/10 + +I want to add to upload our package to test PyPi, but no time. + +- [x] 6:45-7:15 Optimisation misconceptions 6/10 +- [x] 7:15-7:45 Big O 5/10 +- [x] 7:45-8:15 Runtime speed profiles 6/10 +- [ ] 8:15-8:30 check pages + + +- I understand how to methodically optimize the runtime speed of my code +- I understand what Big O is +- I can create a Big O profile of my project +- I can read a runtime speed profile +- I can create a runtime speed profile diff --git a/lesson_plans/README.md b/lesson_plans/README.md index 5c11e137b..45f23e5cc 100644 --- a/lesson_plans/README.md +++ b/lesson_plans/README.md @@ -1,4 +1 @@ # Lesson plans - -* [2023 summer](2023_summer/README.md) -* [2023 autumn](2023_autumn/README.md) diff --git a/meeting_notes/20241129.md b/meeting_notes/20241129.md new file mode 100644 index 000000000..feddef1ca --- /dev/null +++ b/meeting_notes/20241129.md @@ -0,0 +1,12 @@ +# Meeting 2024-11-29 + +Goal: to determine what needs to be discussed in future meetings. +If we know what to do, we can agree on doing those things. + +- R: suggest: for next time, we should have all gone through the issues + and gave our opinions +- R: suggest: what about we schedule a day/half-day to work on the course? + + + + diff --git a/mkdocs.yaml b/mkdocs.yaml index 7d0594d1b..0002e67f2 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -29,10 +29,9 @@ nav: - Issues: project/issues.md - Kanban board: project/kanban_board.md - Team roles: project/team_roles.md - - Test-driven development: tdd/README.md - assert: algorithms/assert.md + - Test-driven development: tdd/README.md - Using a formal testing framework: testing/testing_framework.md - - Continuous integration: continuous_integration/README.md - Summary of day: tuesday_summary.md - Wednesday: - Intro: wednesday_intro.md @@ -41,38 +40,41 @@ nav: - Contributing with code review: git/contribute.md - Sharing and social coding: social_coding/social_coding.md - Pair programming: pair_programming/README.md - - Function design: function_design/README.md + - Using a formal testing framework: testing/testing_framework.md - Summary of day: wednesday_summary.md - Thursday: - Intro: thursday_intro.md - Object Oriented development: design_develop/OO_development.md - - Class design: data_structures/class_design.md - - A 'has-a' relation: data_structures/has_a_relation.md + - Function design: function_design/README.md - Expressive data types: data_structures/expressive_data_type.md - Modular programming: modularity/modular.md - - Implement the project as a package: package/README.md + - A 'has-a' relation: data_structures/has_a_relation.md + - Class design: data_structures/class_design.md + - Continuous integration: continuous_integration/README.md - Summary of day: thursday_summary.md - Friday: - Intro: friday_intro.md + - Implement the project as a package: package/README.md - Optimisation misconceptions: optimisation/misconceptions.md - Big-O: optimisation/big_o.md - Runtime speed profiles: optimisation/runtime_speed_profiles.md - Deploy: deployment/deploy.md - Documentation: deployment/documentation.md + - Wrap-up: misc/wrap_up.md - Summary of day: friday_summary.md - Summary of week: summary_week.md - Misc: - Feedback: misc/feedback.md + - Definitions: misc/definitions.md - Extra material (Earlier Intro day materials): extra.md - Project workflows: misc/project_workflows.md - Learn UML with mermaid: misc/uml_with_mermaid.md - git workflow: misc/git_workflow.md - Reading material: reading/README.md - FAQ: misc/faq.md - - Exercise procedure: misc/exercise_procedure.md - Functions to practice TDD: misc/functions.md - Retrospective: misc/retrospective.md - - Richèl: misc/richel.md + - Wrap-up: misc/wrap_up.md theme: name: material diff --git a/mlc_config.json b/mlc_config.json index bf1f217c6..c2eedf235 100644 --- a/mlc_config.json +++ b/mlc_config.json @@ -3,6 +3,10 @@ "ignorePatterns": [ { "pattern": "https://www.sciencedirect.com/science/article/pii/S0308521X01000543" + }, + { + "pattern": "https://www.tutorialspoint.com/sdlc/index.htm" } + ] } diff --git a/reflections/2024_autumn/20241121_richel.md b/reflections/2024_autumn/20241121_richel.md index 63dd289c9..d4f1ff2ee 100644 --- a/reflections/2024_autumn/20241121_richel.md +++ b/reflections/2024_autumn/20241121_richel.md @@ -3,3 +3,120 @@ - Date: 2024-11-21 - Author: Richel +I enjoyed the day a lot, I enjoyed working with our learners. +I do notice that the learners are getting tired. +Same for me: I should sleep ... + +But first, let's go through the retrospect: + +## What helped us learn (let us move forward) + +- A: Good with range in difficulty. Group exercises are great! + +Yay! + +- A: Bigger range in difficulty of exercises + +Yay! + +- A: Group learning is always fun. Frequent brakes. + The reading for a few minutes into discussion is nice if you call someone out! + otherwise it drags a bit bc no one dares to speak first + +Yup, he/she is right. I should also mention that I will do so before +the reading. + +- A: The tips and code snippets for helping do exercises + +If applies to me: yay! + +- A: Range of difficulties help assess first the things you understand. + Pair programming really help. + +Yay! + +- A: Designated time for reading is good! + +Yay! + +## What stopped us from learning (What held us back) + +- A: Not following schedule is a bit confusing, + I think we worked on thursday, tuesday and wednesday today. + +Learners is right: I adapted it to the learners' pace + +- A: felt like some topics were almost skipped over (obviously due to time). + But if we dont have time for them maybe we do not need to bring them up. + +I did move things, but not have skipped anything yet. + +- A: The concepts themselves being very abstract and difficult + +Unsure if this applies to me. + +- A: Some of the topics are hard to learn while not actually applying them. + E.g. while I think I have a good grasp of what modular programming is + I'm not sure I could recognize it. + +Does not apply to me. + +- A: Applying the lesson directly to the field that you are not familiar with + kinda need more time. Additionally, just watching lecture video for a + specific topic to learn sometimes is not helpful cause there are concept + introduce that was not mentioned in class. + +Does not apply to me. + +- A: Starting the day with the most difficult part of the day + (before properly waking up haha) + +Does not apply to me. + +- A: The youtube lecture was a bit hard to follow, + could be better with more examples and images. + +Does not apply to me. + +## What could we do to improve learning (What can we invent) + +- A: Maybe use the workflow: individual reading -> discussion + -> exercises in group for stuff like modular programming. + Also be more clear with the schedule + I got lost a few times today after zoning out. + +This is great! + +- A: Give more concrete examples for the abstract concepts + (like what are objects in the programming world) + +I feel this does not appy to me. + +- A: The function design discussion was nice, + maybe follow that format more. + +I feel encouraged here :-) + +- A: Maybe have a table of definitions and their equivalent names in + object oriented programming and non-object-oriented, including the + relationsnhips between them. (classes, methods, functions etc) + +I volunteered to do so. + +- A: Give code examples of modular programming and refactoring + +I feel this does not appy to me. + +## What will we do(Act) [Teachers only] + +- Changing schedule is a problem + - [ ] Explain we do student-centered learning on Day 1 of the course + [#111](https://github.com/UPPMAX/programming_formalisms/issues/111) +- [ ] Make list of definitions [#112](https://github.com/UPPMAX/programming_formalisms/issues/112) +- [ ] More code examples [#113](https://github.com/UPPMAX/programming_formalisms/issues/113) +- [ ] Remove YouTube video for modular programming + [#114](https://github.com/UPPMAX/programming_formalisms/issues/114) +- [ ] Give more concrete examples for the abstract concepts in OOP + [#115](https://github.com/UPPMAX/programming_formalisms/issues/114) + + diff --git a/reflections/2024_autumn/20241122_richel.md b/reflections/2024_autumn/20241122_richel.md new file mode 100644 index 000000000..d11fad491 --- /dev/null +++ b/reflections/2024_autumn/20241122_richel.md @@ -0,0 +1,164 @@ +# Reflection + +- Date: 2024-11-22 +- Author: Richel + +I was happy to be with the learners, but too tired to +enjoy it. I did not like talking so much: I'd prefer +to have have done an exercise instead. I decided to go through the +theory, but I could have re-organize the content, +making it more exercise focussed. + +- [ ] Make more exercise-focussed + +I also could have done better: the speed optimization misconceptions +could be done in small groups and discussed. + +Also, the references +to the literature are too diffuse/sprinked: +I want to see big lists everywhere :-) + +- [ ] Copy refs + +Also, I am unconvinced about the use of Big O in its current +form: it should have been about predictions. +It should be scheduled after run-time speed optimization. + +- [ ] Schedule big O after run-time speed optimization + +I predicted I would be tired at the end of the course and I predicted +these would be my worst lectures, as I felt the same in earlier +iterations of the course. + +## Whole course + +I feel I did a reasonable job. +We all (teachers and learners) helped create a warm atmosphere in the course. + +My favorite improvement was my exercises: thanks to the Retrospect at day 1, +I suddenly understood what was needed. 'No plan surives first contact with +the enemy', they say, for me it was more that the retrospect made me +prioritize better. + +I would now say that a good exercise is: + +- Clearly described what to do +- Has a worked-out solution +- If possible: has multiple skill levels + +I want to have this in all my exercises, before next course iteration. + +- [ ] Make all exercises like that + +I enjoyed the team of teachers. My favorite is how we can flat-out +disagree, without any drama. + +The course is a complex beast, with many dependencies between lessons. +I wonder why we do not have written a script to check if our schedule holds? + +- [ ] Make stub of script, to be used in CI + +I've added domain-specific knowledge, in the form of biology. +I think it should be general things we have exercises of + +- [ ] Remove biology things + +I think the project should be worked on more and be simplified. +Maybe start with a proper/pre-fab requirements list. +Branch of from the main function more. + +## Evaluation results + +### What did Richel do well? + +- I think Richèl carry this course. He explained well his lectures and give very good exercises. He asked good questions that challenges our thinking. He seems very prepare everyday and always there to help. Additionally, he listens to comments and give really good insight. +- Involving everyone with the discussions +- Explain everything super well and be very positive about everything +- Really great engagement and explanations. Calling people out for discussion greatly improved flow. Really felt like his heart was in the course. + +### What could Richèl Improve + +- He is really good already. Just continue it. +- Clearer exercises. This became clearer as the course went along +- Remake the video that was in one of the days that lagged +- Tbh I'm really not finding anything. + +Uhhh, are they too friendly? Let's compare: + +### What did Björn do well + +- I like his lecture in git and giving nice exercise on that. +- Clear theory parts on the subjects +- Explain very vague concepts in an understandable way +- Good help during the exercises. + +### What could Björn Improve + +- I think next time avoid just reading the page. Simplify things and asks questions and encourage student to answer. +- Clearer exercises +- When asking questions, make them more specific so that people are more apt to answer +- Was at points difficult to follow the lectures, because he just read the course material out loud. Could benefit from a more free style of lecturing! + +### What did Lars do well + +- Lars really give good insight most of the time while in lecture or even in the side. +- Giving helpful tips when needed +- Give a lot of extra knowledge that was not always in the website +- Great knowledge, really helpful. + +### What could Lars Improve + +- I think the exercises, maybe make it more understandable and assess the time needed to accomplish it. Also, there is a room for improvement in the lecture. +- Clearer exercises +- Give a lot more real-life practical examples when explaining concepts, that would help a lot +- Feel like it would be great to see him do a pair-programming exercise together with another lecturer. Got the impression that he's someone who can showcase how to be a navigator. + +Ah, the learners can indeed be critical. Let's go back to mine: + +### Again: What did Richel do well? + +- I think Richèl carry this course. + He explained well his lectures and give very good exercises. + He asked good questions that challenges our thinking. + He seems very prepare everyday and always there to help. + Additionally, he listens to comments and give really good insight +- Involving everyone with the discussions +- Explain everything super well and be very positive about everything +- Really great engagement and explanations. + Calling people out for discussion greatly improved flow. + Really felt like his heart was in the course. + +That is some heartwarming feedback. + +I am happy to read I came across as prepared, even though it was a +wild ride to do so. I am happy that this group does enjoy to be called +out. + +### Again: What could Richèl Improve + +- He is really good already. Just continue it. +- Clearer exercises. This became clearer as the course went along +- Remake the video that was in one of the days that lagged +- Tbh I'm really not finding anything. + +I am happy to learn my exercises improved! +And indeed, the lagging video is on my todo list :-) + +I took a closer look at the intake form: + +Column |Verdict +--------------------------------------------------------------|------------ +Timestamp |Automatic, hence keep +Your name |Vital +Your email |Vital +Affiliation |Not worth it +Which scripting and programming languages do you use? |Not worth it +Briefly describe your background and experience in programming|Not worth it +What do you expect to learn from this course? |Not worth it +How did you learn about this course? |Not worth it +Do you plan to follow the entire course? |Not worth it +Email address |Duplicate + +I will suggest to keep only the name and email. I feel it is not worth +to bother the learners with things that are not essential. + diff --git a/reflections/README.md b/reflections/README.md index 01a366f66..b7f63211b 100644 --- a/reflections/README.md +++ b/reflections/README.md @@ -1,6 +1,3 @@ # Reflections Reflections are the thoughts of teachers looking back. - -* [Autumn 2023](2023_autumn/README.md) -* [Summer 2023](2023_summer/README.md) diff --git a/scripts/check_schedule.R b/scripts/check_schedule.R new file mode 100755 index 000000000..e28688611 --- /dev/null +++ b/scripts/check_schedule.R @@ -0,0 +1,94 @@ +#!/bin/env Rscript +# +# Checks if the schedule follows all constraints +# +# Usage: +# +# ./scripts/check_schedule.R + + +if (stringr::str_count(string = getwd(), pattern = "scripts")) { + setwd("..") +} + +if (stringr::str_count(string = getwd(), pattern = "scripts")) { + stop( + "FATAL ERROR. \n", + "Please run the script from the project root. \n", + "Present working director: ", getwd(), " \n", + " \n", + "Tip: like this \n", + " \n", + " ./scripts/check_schedule.R \n", + " \n" + ) +} + +get_schedule_filename <- function() { + schedule_filename <- "docs/schedule.md" + if (!file.exists(schedule_filename)) { + stop( + "Cannot find '", schedule_filename, "'. \n", + "Current working directory: ", getwd() + ) + } + schedule_filename +} + + +read_schedule_from_file <- function() { + schedule_filename <- get_schedule_filename() + testthat::expect_true(file.exists(schedule_filename)) + all_lines <- readr::read_lines(file = schedule_filename) + schedule_lines_with_header <- stringr::str_subset(all_lines, pattern = ".+\\|.+\\|.+\\|") + header_line <- schedule_lines_with_header[1] + schedule_lines <- schedule_lines_with_header[-(1:2)] + schedule_strs <- stringr::str_split_fixed(schedule_lines, "\\|", n = 4) + t_schedule <- tibble::as_tibble(schedule_strs) + testthat::expect_equal(ncol(t_schedule), 4) + names(t_schedule) = c("day","time","teacher","subject") + t_schedule$day <- stringr::str_trim(t_schedule$day) + t_schedule$time <- stringr::str_trim(t_schedule$time) + t_schedule$teacher <- stringr::str_trim(t_schedule$teacher) + t_schedule$subject <- stringr::str_trim(t_schedule$subject) + t_schedule +} + + + +create_constraints <- function() { + tibble::tribble( + ~topic, ~prerequisite, + "TDD", "assert" + ) +} + +# Will stop with an error if not +check_constraints <- function() { + schedule <- read_schedule_from_file() + constraints <- create_constraints() + for (constraint_index in seq_len(nrow(constraints))) { + constraint <- constraints[constraint_index, ] + topic <- constraint$topic + topic_indices <- stringr::str_which(schedule$subject, pattern = topic) + # A topic may be taught multiple hours + topic_index <- topic_indices[1] + testthat::expect_true(topic_index > 0) + + prerequisite <- constraint$prerequisite + prereq_indices <- stringr::str_which(schedule$subject, pattern = prerequisite) + # A prereq may be taught multiple hours + prereq_index <- prereq_indices[1] + testthat::expect_true(prereq_index > 0) + + if (prereq_index > topic_index) { + stop( + "Incorrect order detected: \n", + "Topic: ", topic, " at row ", topic_index, " \n", + "Prerequisite: ", prerequisite, " at row ", prereq_index, " \n" + ) + } + } +} + +check_constraints() diff --git a/shared_documents/2024_autumn/20241121.md b/shared_documents/2024_autumn/20241121.md new file mode 100644 index 000000000..a4e860177 --- /dev/null +++ b/shared_documents/2024_autumn/20241121.md @@ -0,0 +1,96 @@ +# Programming formalisms — Shared document Nov 2024 + +- Zoom: + - Passcode: 195328 + +- Course material: + - +- Shared project: + - + +### Retrospect + +##### What helped us learn (let us move forward) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + +##### What stopped us from learning (What held us back) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + + +##### What could we do to improve learning (What can we invent) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + +#### What will we do(Act) [Teachers only] + + + +## Thursday +### Retrospect + +##### What helped us learn (let us move forward) + +- A: Good with range in difficulty. Group exercises are great! +- A:Bigger range in difficulty of exercises +- A: Group learning is always fun. Frequent brakes. The reading for a few minutes into discussion is nice if you call someone out! otherwise it drags a bit bc no one dares to speak first. +- A: +- A: The tips and code snippets for helping do exercises +- A: Range of difficulties help assess first the things you understand. Pair programming really help. +- A:Designated time for reading is good! +- A: +- A: + +##### What stopped us from learning (What held us back) + +- A: Not following schedule is a bit confusing, I think we worked on thursday, tuesday and wednesday today. +- A: felt like some topics were almost skipped over (obviously due to time). But if we dont have time for them maybe we do not need to bring them up. +- A: The concepts themselves being very abstract and difficult +- A: Some of the topics are hard to learn while not actually applying them. E.g. while I think I have a good grasp of what modular programming is I'm not sure I could recognize it. +- A: Applying the lesson directly to the field that you are not familiar with kinda need more time. Additionally, just watching lecture video for a specific topic to learn sometimes is not helpful cause there are concept introduce that was not mentioned in class. +- A: Starting the day with the most difficult part of the day (before properly waking up haha) +- A: The youtube lecture was a bit hard to follow, could be better with more examples and images. +- A: +- A: + + +##### What could we do to improve learning (What can we invent) + +- A: Maybe use the workflow: individual reading -> discussion -> exercises in group for stuff like modular programming. Also be more clear with the schedule I got lost a few times today after zoning out. +- A: Give more concrete examples for the abstract concepts (like what are objects in the programming world) +- A: The function design discussion was nice, maybe follow that format more. +- A: Maybe have a table of definitions and their equivalent names in object oriented programming and non-object-oriented, including the relationsnhips between them. (classes, methods, functions etc) +- A: +- A: Give code examples of modular programming and refactoring +- A: +- A: +- A: + +#### What will we do(Act) [Teachers only] + + diff --git a/shared_documents/2024_autumn/20241122.md b/shared_documents/2024_autumn/20241122.md new file mode 100644 index 000000000..09209d68a --- /dev/null +++ b/shared_documents/2024_autumn/20241122.md @@ -0,0 +1,98 @@ +# Programming formalisms — Shared document Nov 2024 + +- Zoom: + - Passcode: 195328 + +- Course material: + - +- Shared project: + - + +### Retrospect + +##### What helped us learn (let us move forward) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + +##### What stopped us from learning (What held us back) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + + +##### What could we do to improve learning (What can we invent) + +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: +- A: + +#### What will we do(Act) [Teachers only] + +## Friday + +### Retrospect + +##### What helped us learn (let us move forward) + +- A: Great references for future use +- A: Exercises, group work +- A: Having the code snippets up on the course website to use and those snippets having explanations too. +- A: +- A: The exercises help me understand the lectures. Working in groups is really good. +- A: Working in groups to test out the theory was super useful +- A: Working in groups, the examples and discussions. +- A: Group work +- A: + +##### What stopped us from learning (What held us back) + +- A: Windows code snippets not working, took a lot of time from the exercises +- A: Not all the commands working on Windows +- A: Not knowing where to make the exercise files, was not specified in instructions +- A: Some of the provided commands did not seem to work for windows. Had to improvise. +- A: Felt like the goals were not as clear today. Difficult to transfer the topics from today in a lecture. Felt like the project was not complex/functional enough to write proper documentation +- A: Unclear guide in the exercises (specifically in the documentation) +- A: +- A: Some things were very fast for me. +- A: + + +##### What could we do to improve learning (What can we invent) + +- A: Have a more functional project for which writing documentation actually provides worth. Installation/requirements/etc were not extensive enough for the exercises imo. Also maybe resetting the state of the project Github so everyone is on same page? +- A: +- A: Adding commands that work on windows as well as mac/linux +- A: +- A: Put everything practical that we are supposed to do within the exercises. It's a bit confusing when some parts are in the "theory part" with code that we are supposed to use and some parts are in "exercises" +- A: Have more realizable project. Make the guide much clearer. +- A: Early on ask about experience level amongst the group and group people based on their experience to enable more difficult exercises to be done. +- A: More clear exercises, specifying some points such as direction, folder etc. Something like step-by-step as well as in some examples and exercises. +- A: + +### Teacher improvment google form + https://forms.gle/wf8ohmsgSEBJc93c6 +### Certification **Will not be published on Github** +follow this link and add your full name and email and if you also need a discription with your course [certificate](https://docs.google.com/document/d/1eTueJR4Zn2FNnzz1zypD7Z6QG9ayHIrZldCyaoaS8sA/edit?usp=sharing). + +#### What will we do(Act) [Teachers only] diff --git a/shared_documents/README.md b/shared_documents/README.md index 84fab5f0a..4cb869fe6 100644 --- a/shared_documents/README.md +++ b/shared_documents/README.md @@ -1,6 +1,3 @@ # Shared documents These are the shared documents used in the course - -* 2024 courses here -* [2023 autumn](2023_autumn/README.md)