code/README.md

Not so fast! Read this!

Hello! This is the read-me file with information for the code project. Please take some time to read it before going on, as it contains detailed description of code and methods used. So don't be hasty, and have a good look!

Setup

Make sure the following things are installed on your system:

1. git
2. python and the package manager conda, available through miniforge.
3. VSCode (in principal, this is not required, but it makes things much easier...)

Then, open a terminal and cd into the desired directory and run

git clone git@gitea.psi.ch:tschan_d/Master_Thesis.git

Then cd into the created directory via cd Master_Thesis and create the conda environment from the provided environment.yml file:

conda create --name MA --file environment.yml

Lastly, make sure that VSCode is selecting the created interpreter by configuring the settings.json. The important line is currently set to "python.defaultInterpreterPath": "C:/Users/tschan_d/AppData/Local/miniforge3/envs/MA/python". Adapt this setting so that the path points to the conda environment you just created.

Tip

Importantly, it may be necessary to add the current folder to the PYTHONPATH system variable in order for the code to run. For this, add the current directory to the PYTHONPATH system variable (there are several options to do this, one of the is shown here).

Detailed descriptions of how to use conda and git are available below.

Code Structure and Documentation

This code project is structured as follows:

Master_Thesis
├───.git
|   └───...
├───.vscode
|   ├───settings.json
|   └───launch.json
├───defs
|   ├───__init__.py
|   ├───BTOF.py
|   ├───LabDevices.py
|   └───OFR.py
├───doc
|   └───defs
|       ├───index.html
|       ├───BTOF.html
|       ├───LabDevices.html
|       └───OFR.html
├───run
|   ├───__init__.py
|   └───OFR_Analysis
|       ├───20260612_SET02_EXP01
|       |   └───202607023_OFR_Analysis_01.ipynb
|       └───20260729_SET02_EXP02         
├───.env
├───.gitignore
├───.mplstyle
├───environment.yml
├───get_doc.bat
├───main.py
└───README.md

You are currently reading README.md, where the structure of this oroject is explained. Here is an explanation of what each folder contains:

Auxilliary directories ./.git and ./.vscode

1. .git contains all files related to version control via git. These files are usually not interesting, unless you need to go back to old commits or want to know more details. Best leave this alone.
2. .vscode contains all files relevant for environment setup to run this project in VSCode. These files are:
   1. settings.json: the setup file to set up VS Code in the desired configuration. Feel free to change these as you like.
   2. launch.json: the launch configuration file for the project, in which it is specified how VSCode should behave when you launch a job: that is, when you want to run a file or debug it. Adapt them as needed.

Directories ./defs and ./doc

1. ./defs contains source code for data analysis. This includes:
   1. __init__.py is a file to structure the project like a package. This file contains just a docstring and is empty otherwise. The docstring contains the description of the module in the code documentation (see below). This file is needed so that relative imports work properly.
   2. BTOF.py contains all classes and methods necessary to analyse the BTOF output data. These methods are only for fully calibrated and processed BTOF data that result from IGOR/Tofwerk workflows.
   3. LabDevices.py contains the classes and methods required to analyse the data from devices in the lab. Those devices are the Teledyne CO2 monitor as well as the RH/T sensor.
   4. OFR.py contains the classes and methods required to analyse data from the OFR.

Note

proper code documentation for this "package" (it is not a package, but it is structured like one) is available under ./doc/defs/index.html. Double-click on that file to open a static webpage in your browser that displays technical code documentation.

Directory run and its subdirectories

1. __init__.py is an empty file required to import functions from this module (to be checked).
2. ./run/OFRAnalysis contains subdirectories such as ./run/OFRAnalysis/20260612_SET02_EXP01/ that in turn contain pyhton notebookes such as ./run/OFRAnalysis/20260612_SET02_EXP01/202607023_SET02_EXP01.ipynb where the data analysis is executed and visualised.

Other files

1. .env is a setup file used by VSCode to adjust the PYTHONPATH variable (to be checked).
2. .gitignore is a file helping to maintain cleanliness in the git remote repository on the server. This file excludes certain file types, such as .pdf or .svg files (that are created when compiling figures), from being tracked by git.
3. .mplstyle is a style sheet for matplotlib to ensure that all figures look alike.

Note

: the .mplstyle file uses LaTeX to render text in figures. If this is not available on your machine, do not use the .mplstyle style. It is used by including the line of code plt.style.use(.mplstyle) in your code when you have imported import matplotlib.pyplot as plt in yout python code. If not using this style sheet, ensure that axis labels, legend entries, text and titles to not include any TeX!

4. environment.yml the file containing all information on the python virtual environment used in this project, see also creating environments from .yml files'
5. get_doc.bat is a Windos batch file to that can be run in a terminal through Start-Process get_dic.bat. For this, first cd into the project home directory, and then execute the batch script. This batch job calls pdoc to compile code documentation from provided docstrings. The resulting .html files can be found in the directory .doc/defs/. If you compiled the project python environment from the provided environment.yml file, pdoc is automatically installed with it.
6. main.py is a file used to debug code or to create a script that may be used for analysis. It is included to maintain the "package"-like structure of the code, but it may be used for whatever purpose you need it for!
7. README.md - this file. Iy you're reading this right now, I guess there's no need to explain this further...

Overview over conda

Extensive documentation is available on docs.conda.io.

Command	Description
conda info --envs or conda env list	Get info on your conda environments
conda list --name my_env	List all the installed packages in the environment my_env
conda activate my_env	Activate environment my_env
conda install --name my_env package1 package2	Install packages package1 and package2 into the environment my_env (this works for arbitrarily many packages). If environment is activated, there is no need to add --name my_env. Note: when there are activation problems with the environment, packages will be installed into base and your interpreter may not see them. Package versions may be specified like this numpy=3.4.2
conda update --name <my_env> package	Update package package in environment my_env
conda update python	Update python itself
conda update conda	Update conda itself
conda deactivate	Deactivate environment
conda remove --name my_env package	Remove package package from my_env
conda create --name my_env	Create new conda environment called my_env. Adding the flag package=1.2.3 directly installs the desired packages into the environment. This also works to specify the python version used in this environment via python=3.1.3 for instance
conda create --name my_env --file env.yml	Create conda environment named my_env from .yml file env.yml
conda env export --name my_env --file=eny.yml	Export environment my_env into a .yml file
conda update --name my_env	Update the conda environment my_env
conda env update --file environment.yaml --prune	Update the environment associated with the .yml file, where --prune removes any unused dependencies
conda config --prepend channels new_channel	Add channel new_channel to channel list. Note: for licensing reasons, only use conda-forge channel. This is specified in the environment.yml file
	Pinning a package: add a file named pinned to the conda-meta directory of the environment. Adding the line package 1.7.* restricts package to remain in the 1.7 series when updating. Adding the line package==1.5.4 forces the package to remain at exactly the specified version. The pinning may be overrun by conda update package --no-pin

Overview over git

Extensive documentation is available at git-scm.dev.

Using git:

Prerequisites:

1. Ensure that there is a connection to the psi network, either by being on the PSI network, or by using the vpn with domain vpn.psi.ch.
2. Ensure there is a valid ssh key under C:/Users/username/.ssh/. If there is no valid key, follow the instructions to create a ssh key on the PSI Intranet.
3. Ensure that the private key is added to your ssh-agent and that the oublic key is pointing to the remote repository. You can check the connection via ssh -T git@gitea.psi.ch

Then git operates as follows:

Command	Description
git clone git@gitea.psi.ch:username/repo	initialises a git repo in your current directory (else cd into the deisred one), creates a remote origin and checks out the default branch
git fetch	Fetch changes from remote
git merge	Merge changes from remote on top of local checked-out branch
git pull	Execute fetch and merge in a single command
git add file.ext	Stage changes in file.ext if it has been modified
git add .	Stage changes of all modified files in git repo
git commit -m "Message"	Commit the staged changes with the pertaining commit message "Message"
git push -u origin main	Push changes to remote on branch main. Normally it suffices to just run git push, but specifying the branches is required when there are several of them...

To remove files from the remote repository which are not desired (i.e. wrong entry in the gitignore file), update the gitignore file and then run

git add *
git commit -m "Some commit message"
git push
git rm -r --cached
git add * 
git commit -m "Some new commit message where the undesired files are now no longer there..."
git push