Merge pull request #40 from AndreHauschild/devel

Re-organized data section

.github/workflows/test.yml

@@ -20,26 +20,26 @@ jobs:
         with:
           python-version: '3.10'
 
-      - name: Install dependencies from cssrlib-data repository
-        run: pip install -r requirements.txt
-
       - name: Get branch name
         id: get_branch_name
-        run: echo "branch_name=$(basename $GITHUB_REF)" >> $GITHUB_OUTPUT       
+        run: echo "branch_name=$(basename $GITHUB_REF)" >> $GITHUB_OUTPUT
 
-      - name: Clone cssrlib repository
-        run: git clone -b ${{ steps.get_branch_name.outputs.branch_name }} https://github.com/${{ github.actor }}/cssrlib.git
-
-      - name: Install dependencies from cssrlib repository
+      - name: Install cssrlib base repository
+        run: pip install -U git+https://github.com/${{ github.actor }}/cssrlib.git@${{ steps.get_branch_name.outputs.branch_name }}
+
+      - name: Install dependencies for cssrlib-data repository
+        run: pip install -r requirements.txt
+
+      - name: Download IGS files
         run: |
-          cd cssrlib
-          pip install -r requirements.txt
- 
+          cd ./samples
+          python ./igs_download.py
+
       - name: Execute Python scripts
         run: |
-          export PYTHONPATH="../cssrlib/src:$PYTHONPATH"
           cd ./samples
           for file in $(find . -name "*.py"); do
+            if [ "$file" == "./igs_download.py" ]; then continue; fi
             echo "# Execute $file"
             echo "#"
             python "$file" > /dev/null

README.md

@@ -1,29 +1,160 @@
-# cssrlib-data
-Sample scripts and dataset for CSSRlib
-Pre-installation of CSSRlib is required.
+# CSSRlib-data
+
+Sample scripts and datasets for **CSSRlib**. The scripts require an installation of the **CSSRlib** package.
 
 ## Prerequisites:
 
-Additional python packages are required as prerequisites and can be installed via the following command
+Pre-installation of **CSSRlib** is required. Install the [officially released package](https://pypi.org/project/cssrlib/) with `pip` using
 
+```bash
+pip install cssrlib
 ```
+
+Additional python packages are required as prerequisites and can be installed via the following command
+
+```bash
 pip install -r requirements.txt
 ```
 
+It is recommended to use a virtual environment to avoid version conflicts with the system-wide python installation.
+
+## Installation in Virtual Environment
+
+Create a virtual environment `cssrlib-venv` in the current directory with
+
+```bash
+python3 -m venv cssrlib-venv
+
+```
+Activate the environment with
+
+```bash
+source cssrlib-venv/bin/activate
+```
+
+To make the base **CSSRlib** module available in the virtual environment, there are several options:
+
+***1. Install the official package***
+
+Install the [officially released package](https://pypi.org/project/cssrlib/) with `pip`
+
+```bash
+pip install cssrlib
+```
+
+This will be sufficient for most cases, but typically the version from the github repository is more up-to-date.
+
+***2. Install from github repository***
+
+Install `cssrlib` from the `main` branch of the [github repository](https://github.com/hirokawa/cssrlib.git) with this command
+
+```bash
+pip install -U git+https://github.com/hirokawa/cssrlib.git@main
+```
+
+If you like to use the development branch with the most recent changes, substitute `@main`with `@devel`.
+
+*IMPORTANT*: make sure to always use consistent branches for `cssrlib` and `cssrlib-data`!
+
+***3. Install a local copy of the github repository***
+
+For this installation guide, it is assumed that the **CSSRlib** base repository has been cloned to a folder `cssrlib` in the same directory as the samples repository `cssrlib-data`.  The command `ls | grep cssrlib` should then return
+
+```bash
+cssrlib
+cssrlib-data
+cssrlib-venv
+```
+
+Install the local module in editing mode using the `-e` flag:
+
+```bash
+pip install -e ./cssrlib
+```
+
+***4. Make a local copy available without installation***
+
+*NOTE:* this is not necessary if the `cssrlib` package has been installed with `pip` through one of the steps above!
+
+Make sure the path to the `src` folder of the `cssrlib` base repository appears in the python path.
+
+```bash
+echo $PYTHONPATH
+```
+
+If not, add it with the following export command, where `<path-to-cssrlib>` must be replaced with the full path to **CSSRlib** base repository.
+
+```bash
+export PYTHONPATH="$PYTHONPATH:<path-to-cssrlib>/src"
+```
+
+## Check **CSSRlib** base package installation
+
+Check if the package inclusion works with
+
+```bash
+python -c "import cssrlib; print(cssrlib.__version__); print(cssrlib.__file__)"
+```
+
+If the `cssrlib` package was installed with `pip`, you can display the installation details with
+
+```bash
+pip show cssrlib
+```
+
+## Install dependencies for data repository
+
+Install the dependencies from the `requirements.txt` file of `cssrlib-data`:
+
+```bash
+pip install -r cssrlib-data/requirements.txt
+```
+
+## Data download from IGS
+
+Most sample scripts require IGS data for processing. The data can be downloaded with a script, which must be called before the scripts can be executed:
+
+```bash
+cd ./cssrlib-data/samples
+python3 igs_download.py
+```
+
+## Handling Warnings from the PySolid module
+
+The module `pysolid` is used for the computation of solid Earth tides. It contains a hard-coded leap second table with an expiration date, which is set to the next possible injection date of a leap second at the time of the last update. The table is frequently updated by the package maintainers. The following warning is issued when the expiration date is exceeded:
+
+> Mild Warning -- time crossed leap second table boundaries.  Boundary edge value used instead
+
+If you encounter this warning when executing **CSSRlib** scripts, it can most likely be removed by updating `pysolid` to the most recent version using
+
+```bash
+pip install --upgrade pysolid
+```
+
+If the warnings persist, installing the latest version from the repository can help
+
+```bash
+pip install -U git+https://github.com/insarlab/PySolid.git@main
+```
+
 ## Ephemeris: RINEX/TLE
+
 - test_eph.py reading/plotting ephemeris from RINEX 3
 - test_tlesim.py reading/plotting TLE orbit
 
 ## Model
+
 - test_trop.py tropospheric delay model
 - cacode.py GPS/QZSS C/A code simulation
 
 ## Positioning: Static
+
 - test_pntpos.py Standalone positioning
 - test_rtk.py RTK positioning
 - test_ppprtk.py PPP-RTK positioning
 
 ## Positioning: Kinematic
+
 - test_pntpos2.py Standalone positioning
 - test_rtk2.py RTK positioning
 - test_ppprtk2.py PPP-RTK positioning
@@ -35,5 +166,3 @@ pip install -r requirements.txt
 - [ ] Add residual output
 - [ ] Add check for observations, first two observations must be on different frequencies
 - [ ] Number of frequencies `nav.nf` should be set automatically depending on specified signals
-- [x] Check triple-frequency processing for PPP
-- [x] Code/phase error ratio `nav.erratio` should also work for > 2 signals

data/.gitignore

@@ -0,0 +1,4 @@
+/igs/
+/antex/
+/brdc/
+/doy*/*.log