Skip to content

A web application framework to manage and analyse river data.

Notifications You must be signed in to change notification settings

riveranalyst/software

Repository files navigation

River Analyst User Manual

River Analyst is a database application framework built with the Django web application framework (Python) to leverage fast river ecosystem analyses.

Installation

Linux

  • Clone this repository:

    git clone https://github.com/beatriznegreiros/river-analyst.git
  • Make sure to have pip3 and virtualenv installed by:

    sudo apt update
    sudo apt install python3-pip
    pip3 install virtualenv
  • Create new virtual environment:

    python3.9 -m venv /path/to/new/virtual/environment
  • Activate new virtual environment:

    source /path/to/new/virtual/environment/bin/activate
  • Install dependencies:

    pip3 install -r requirements.txt

Windows

  • Clone this repository:

    git clone https://github.com/beatriznegreiros/river-analyst.git
  • Make sure to have Anaconda installed.

  • Create conda environment:

    conda create --name [env_name] python=3.9
  • Activate conda environment:

    conda activate [env_name]
  • Install dependencies:

    pip3 install -r requirements.txt 

Usage

Database architecture

RA database structure is composed of several tables (data models) such as IDO (Interstitial Dissolved Oxygen), which is linked to a MeasPosition (measurement positions) via a foreign key. The figure below illustrates the database architecture through an Entity-Relationship diagram:

River Analyst database architecture

Figure 2 and 3 provide detailed descriptions of the several attributes within each of RA data models described above.

Database attributes Part 1

Database attributes Part 2

Running the app

  • Go to repository directory

    cd path/to/river-analyst

  • Make migrations (optional)

    python3 manage.py migrate Obs.: Migrations are in principle python commands wrapped around SQL passed from the Django framework to the sql database.

  • Run the server locally

    python3 manage.py runserver

  • Create superuser for having full admin rights over the app:

    python3 manage.py createsuperuser

Initializing a new database with template CSVs

  • Add data to the csv templates under the path riveranalyst/river-analyst/media/
  • cd to the riveranalyst/utils directory cd riveranalyst/utils
  • Execute scripts to initialize targeted data models
    • It is important to begin with populating the MeasPosition model, which is where all data models connect:
      • Here, it is crucial that the field meas_position is unique and contains no typos. This field will be used to generate foreign keys to link data models. python fill_measpositions_tab.py
    • Then, any data model can be populated afterwards, for instance:
      • the field meas_position needs to match the names given in the MeasPosition data model.
        • python fill_surf_tab.py for filling the SurfaceSed data model
        • python fill_subsurf_tab.py for the SubSurfaceSed data model
        • python fill_kf_tab.py for the Kf (Riverbed Hydraulic Conductivity) data model
        • python fill_do_tab.py for the IDO (Interstitial Dissolved Oxygen) data model
        • python fill_hydraulics_tab.py for the Hydraulics data model

Django cheat sheet (interacting with the Database via Python)

You can create a new Django object by:

obj = ModelName(field_name=value)
obj.save()

Querying the database is very simple:

ModelName.objects.all() # get all objects

# get objects with field_name = value
ModelName.objects.filter(field_name=value) 

# get a single object with field_name = value
ModelName.objects.get(field_name=value) 

To create a new Django model, you need to define a class in one of your Django app's models.py file that inherits from Django's built-in models.Model class. Here is an example model class that defines a Book model with fields for title, author, and publication date:

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=200)
    pub_date = models.DateField()

Connecting the project with a database file stored in the cloud (Example for AWS RDS)

  • Install the psycopg2 library: Since AWS RDS supports PostgreSQL, you will need to install the psycopg2 library, which is a PostgreSQL adapter for Python, by running the following command:
pip install psycopg2-binary
  • Configure the Django project settings: In your Django project's settings.py file, you will need to configure the database settings to connect to your AWS RDS instance. Here is an example configuration for a PostgreSQL database:
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your-db-name',
        'USER': 'your-db-username',
        'PASSWORD': 'your-db-password',
        'HOST': 'your-db-endpoint.aws-region.rds.amazonaws.com',
        'PORT': '5432',
    }
}

In the above configuration, you will need to replace your-db-name, your-db-username, and your-db-password with your own values, and replace your-db-endpoint and aws-region with the endpoint and region of your AWS RDS instance, respectively. You can find your RDS instance's endpoint in the RDS console.

  • Migrate the Django project: Once you have configured your database settings, you will need to run the following commands to migrate the Django project to the database:
python manage.py makemigrations
python manage.py migrate

These commands will create the necessary tables and columns in your database.

  • Test the connection: Finally, you can test the connection to your AWS RDS instance by running the following command:
python manage.py dbshell

This command will open a PostgreSQL shell that connects to your database. If the connection is successful, you should see a prompt that looks like this:

psql (13.4, server 13.3)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
Type "help" for help.

your-db-name=>