151 lines
11 KiB
Markdown
151 lines
11 KiB
Markdown
# 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](https://github.com/conda-forge/miniforge).
|
|
3. [`VSCode`](https://code.visualstudio.com/) (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](https://www.geeksforgeeks.org/python/pythonpath-environment-variable-in-python/)).
|
|
|
|
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](https://peps.python.org/pep-0257/) 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.
|
|
2. `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.
|
|
3. `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`](https://matplotlib.org/) 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](https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/creating-projects.html)'
|
|
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](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
|
|
|
|
|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](https://git-scm.dev/doc).
|
|
|
|
### 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
|
|
``` |