flicker/README.md

# Return to Ritherdon: Flicker

This a Python 3 project which provides a breakdown of the data
produced by 'Personal Flash in Real-Time' artwork. The data analysis
provided by Flicker is for the health and safety assessment concerns
regarding epilepsy -- when the artwork is exhibited in a public
(I.E. art gallery) setting. This code base has no immediate bearing on
the 'Personal Flash in Real-Time' artwork and its various
components. This is strictly data analysis (for health and safety).

'Personal Flash in Real-Time' is an artwork which consists of three
smaller projects. They are:

- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter)
- [Relay](https://git.abbether.net/return-to-ritherdon/relay)
- [Midpoint](https://git.abbether.net/return-to-ritherdon/midpoint)
- [Personal Flash in Real-Time Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs) (This provides documentation for the whole project/artwork)

The data Flicker breaks down is the SQLite database used by the
Midpoint project. Light Meter is responsible for taking and sending
light readings (in the various welding booths in Ritherdon) and
sending them to Midpoint -- where they are stored. Relay is
responsible for requesting those light readings (from Midpoint) and
controlling the lights connected to it/them in the art gallery
(I.E. Castlefield) based on those light readings.

For the health and safety assessment, please use the following link:

- [Health and Safety Assessment](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/health-and-safety/photosensitive_epilepsy.md)

The assessment goes through and explains **how to interpret the
data** -- which is outside the scope of this document. 

## Project Set-up

This assumes you are using Linux, specifically Debian or Ubuntu, and
have Python 3 already installed. Other environments have not been
tested.

After you can cloned the repository, you will need to set-up a Python
virtual environment and install its requirements.

```bash
git clone http://git.abbether.net/return-to-ritherdon/flicker.git
cd flicker

# Adjust the location for your 'venv' to whatever you prefer. This is
# just a default example.
python3 -m venv venv

# Activate the virtual environment.
source venv/bin/activate

# Install the projects requirements.
pip install -r requirements.txt
```

From there, you should already have the data which needs
processing. Because of the nature of this repository, I have
transferred the data to it manually. There is no automated way to get
the latest version of the data. I do not have any plans to add this as
a feature.

The project structure should look something like the following,

```console
flicker/
├── LICENSE
├── README.md
├── requirements.txt
└── src
    ├── data
    │   ├── test-data.csv
    │   └── test-data-lite.csv
    ├── flicker.py
    └── services
        ├── data_services.py
        ├── io_services.py
        └── log_services.py
```

**Note: You will need to create the `results` folder and its 'result
files' separately.** This is because they are included in the
`.gitignore` file -- so the commit history does not get clogged-up.

To finalise setting up the project and begin the analysis, run the
following commands,

```bash
# Make sure you have activated the virtual environment. Can ignore if
# you already have.
# cd flicker
source venv/bin/activate

# These files are used for intermediate storage whilst processing the
# data. The 'final' results are stored in 'filtered_flicker_entries.csv'
mkdir data/results
touch readings-per-sec.csv
touch readings_above_threshold.csv
touch flicker_list.csv
touch filtered_flicker_entries.csv

# To start the data processing -- which might take a while...
python src/flicker.py
```

For how the analysis is done, read the `flicker.py` file (I.E. the
'main'/entry-point file). Each stage is separated and documented
within it. You can quickly jump to said file by clicking the link
below:

- [flicker.py](https://git.abbether.net/return-to-ritherdon/flicker/src/branch/master/src/flicker.py)

Essentially, this is just a glorified script but I have separated out
the logic into various files and directories because that's just how I
like to roll. Was this necessary? Not really. It is what it is,
though. How the files are connected are shown in the diagram below.

![System Overview](attachments/system-overview.png)

The main reason for separating out the code like this was because I
felt like it aided in explaining what the code was doing in
`flicker.py` via the use of comments. I could document things at a
high level in `flicker.py` and you could dig down into the various
function calls if you need/want to.