# SONIC

## Initializing the Database

The database is initialized using the following command:

```python
from sonicdb import sonic 

db = sonic.Database("database_name.db")
```

This creates a SQLite database file named `database_name.db` and initializes the required tables. Accessing the database can be done using [SQLAlchemy](https://docs.sqlalchemy.org/en/20/index.html) commands. The database is designed to be flexible and extendable, allowing users to retrofit it to their use cases while maintaining foundational models and methods for managing audio data.

## Models

The following models make up the default database schema.

### File 

The File model stores the metadata of the audio files. The table below describes the columns, and properties, of the File model.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| filepath | String | Path to the audio file |
| filename | String | Name of the audio file |
| extension | String | File extension (e.g., `.wav`) |
| sample_rate | Integer | Sampling rate of the audio file |
| start | DateTime | Start time of the audio file |
| end | DateTime | End time of the audio file |
| duration | Float | Duration of the audio file in seconds |

Accessing the File model is done using the following command:

```python
from sonicdb import sonic, models

db = sonic.Database("database_name.db")

file = db.session.query(models.File).first()
```

The audio for the file can be accessed using the `get_audio()` method:

```python
audio = file.get_audio()
```

This will return a `sonicdb.audio.Audio` object that contains methods for analyzing the audio waveform, extracting features, generating spectrograms, and more.

### Sensor

The Sensor model represents the sensors used to capture audio data.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| name | String | Name of the sensor |
| subname | String | Subname or additional identifier for the sensor |

The sensor model can be searched using the following command:

```python
from sonicdb import sonic, models

sensor = db.session.query(models.Sensor).filter(models.Sensor.name == "Sensor Name").first()
```

### Channel

The Channel model represents the audio channels associated with a sensor.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| number | Integer | Channel number |
| sensor_id | Integer | Foreign key referencing the Sensor model |

Channels can be found using their ids but a more common use case is to find them using the sensor they are associated with. This can be done using the following command:

```python
from sonicdb import sonic, models   

channel = sensor.channels[0]
```

### Subject

The Subject model represents the subjects associated with the audio data.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| name | String | Name of the subject |
| events | list | List of events associated with the subject | samples | list | List of samples associated with the subject |

Just like the sensor model, the subject model can be searched using the following command:

```python
from sonicdb import sonic, models

subject = db.session.query(models.Subject).filter(models.Subject.name == "Subject Name").first()
```

### Event

The Event model represents specific events captured in the audio data.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| name | String | Name of the event |
| description | String | Description of the event |
| start | DateTime | Start time of the event |
| end | DateTime | End time of the event |
| subject | models.Subject | Subject associated with the event |
| samples | list | List of samples associated with the event |

An event can be found through the associated subjects through the following command:

```python
from sonicdb import sonic, models   

events = subject.events

event = events[0]

# get the audio from the first channel of the sensor
audio = event.get_audio(sensor=sensor, channel_number=1)
# this can also be done using the following command:
audio = event.get_audio(channel=channel)
```

### Sample

The Sample model represents audio samples extracted from the files.

| Column | Type | Description |
| --- | --- | --- |
| id | Integer | Primary key |
| datetime | DateTime | Timestamp of the sample |
| file_id | Integer | Foreign key referencing the File model |
| sensor_id | Integer | Foreign key referencing the Sensor model |
| channel_id | Integer | Foreign key referencing the Channel model |

Samples are generated by the user through the `sonic.generate_samples` function  where they can choose the duration of the sample, overlap, and choose whether to save audio from the sample to a file. 

```python
from sonicdb import sonic, models

sample = db.session.query(models.Sample).first()

audio = sample.get_audio()
```