From bdae9fac5e04c47df26bb683c6c6d3301ee2f893 Mon Sep 17 00:00:00 2001 From: toravest Date: Sun, 30 Mar 2025 21:46:47 +0200 Subject: [PATCH] add documentation, markdown, and files to .gitignore --- .gitignore | 3 ++- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++- data/README.md | 16 +++++++-------- notebooks/README.md | 15 ++++++++++++++- resources/README.md | 29 +++++++++++++++++++++++++++- src/README.md | 17 +++++++++++++++- tests/README.md | 9 ++++++++- 7 files changed, 121 insertions(+), 15 deletions(-) diff --git a/.gitignore b/.gitignore index 701031c..a733132 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ /venv/ .env /data/output*/ -old_* \ No newline at end of file +old_* +.DS_Store \ No newline at end of file diff --git a/README.md b/README.md index d5c10d8..827bc63 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,28 @@ # Anvendt mappe +## Installering +- For å starte må man aktivere venv-en. Dette gjøres på følgende måte: + 1. Skriv en av disse i terminalen, dette kan variere fra pc og operativsystem: + - `python3 -m venv venv` + - `python -m venv venv` + 2. Aktiver vevn, det gjøres på en av følgende måter: + **Mac/linux**: `source venv/bin/activate` + **Windows**: `./venv/Scripts/activate` + 3. Installere nødvendige biblioteker, med en av disse: + - `pip3 install -r requirements.txt` + - `pip install -r requirements.txt` + +## Oversikt +Her kommer oversikt over strukturen i prosjektet: +- `data` denne mappen inneholder output data +- `docs` denne mappen inneholder dokumentasjon +- `notebooks` denne mappen inneholder notebookene med all funksjonalitet +- `resources` denne mappen inneholder våre kilder +- `src` denne mappen inneholder python filene +- `tests` denne mappen inneholder våre unittester + +Det kan leses mer om disse i deres tilhørende `README.md` filer. + ### Mappe del 1 #### Vår visjon av oppgaven @@ -32,6 +55,10 @@ Ettersom ingen av de fra MET funket etter vårt ønske, søkte vi videre på net - [OpenWeatherMap API](https://openweathermap.org/) - Denne inneholder forecast data, men det er også mulig å hente historiske data. - Med en student profil, får vi gratis tilgang på masse data. Dermed vil vi kunne requeste historiske data fra API-en. + - Det finnes også flere ulike API-er, som vil hjelpe oss å oppnå vår visjon. Blant annet: + - [Current Data](https://openweathermap.org/current): for å hente ut data fra ønsket sted på nåværende tidspunkt. + - [History API](https://openweathermap.org/history): for å hente data fra ønsket sted og tidsperiode (inntil 7 dager). + - [Statistic Historical Data](https://openweathermap.org/api/statistics-api): for å hente statistisk historisk data som kan brukes til regresjon. Den tar utganspunkt i all historisk data og oppsummerer det for hver dag i løpet av et år. ##### Henting av data For å hente data fra OpenWeatherMap API-en har vi skrevet en funskjon som tar inn stedsnavn, startdato og sluttdato, den legger da ønskede verdier inn i url-en og requester for ønsket sted og tidsperiode, sammen med API-key som er lagret i en env-fil og importert. @@ -47,7 +74,25 @@ Funksjonen returnerer en print setning når dataen er skrevet, og legger ved fil ##### Hente data fra fil +For å hente data fra json-fil, bruker vi pandas sin innebygde funksjon _read_json_, for deretter å lagra dataene i en pandas dataframe. + +#### Oppgave 3 - Databehandling +Vi har hele tiden fokusert på å forstå dataen vi har, derfor har vi lagret den i en json fil for å lettere kunne lese ut hvilke verdier vi har, og hvilke vi kanskje ikke trenger. De kolonnene vi mener vi ikke trenger har vi da fjernet. Så har vi sjekket etter feil og mangler i dataen, både med 'NaN' verdier, manglende kolonner eller ekstremverdier. +##### Metoder for å identifisere og håndtere manglende data +Metoder vi har brukt  er for eksempel pd.json_normalize, df.drop_duplicates og df.drop(columns = «name»). Ved json.normalize har vi fått konvertert dataene våre til en tabell, DataFrame, fordi det er lettere å manipulere. Df.drop_duplicates bruker vi for å enkelt håndtere duplikatene i datasettet. Vi har også kolonner som inneholder informasjon som ikke er relevant til det vi ønsker å finne og da bruker vi df.drop(column= «name») og setter inn kolonnenavnet i parentes bak, eksempel: df = df.drop(columns = «base») eller df = df.drop(columns = «visability»). Denne metoden er nyttig for å rydde opp i datasettet og håndtere fjerning av kolonner som ikke er relevant, og dermed blir det mer oversiktlig og ryddig å jobbe med. +Vi har også brukt missingno.matrix for å visualisere hvilke kolonner som mangler data, før vi har brukt enten fillna(0) for å endre 'NaN' verider til 0, eller fillna('obj.ffill()) for å bruke forrige lagret data. -#### Oppgave 3 - Databehandling +##### List comprehensions +I den ene koden til statistic_data_notebook er et eksempel på hvor vi har brukt list comprehension for å manipulere data. Vi bruker den til å manipulere temperaturene til celsius og lagre det resultatet i en ny kolonne, temp.mean_celsius. Vi har gjort dette fordi den metoden er mer effektiv å bruke enn for eksempel en direkte for-løkke.  + +Dette er også brukt i statistic_data_notebook for å lage en kolonne bestående av måned og dag. + +##### Pandas SQL vs tradisjonell Pandas +Pandas-syntaks kan være noe kompleks og da kan man for eksempel med sqldf, bruke SQL-spørringer på Pandas DataFrames. Dette kan gi en enkel måte å filtrere, transformere og gruppere data på, på en mindre kompleks måte. SQL-spørringer kan også være enklere å lese og vedlikeholde enn Pandas-operasjoner, når man jobber med komplekse datasett. Man kan også bruke effektive og enklere SQL-kommandoer som for eksempel JOIN og GROUP BY.  + +##### Uregelmessigheter i dataene +Uregelmessigheter vi kan forvente å møte på er blant annet manglende verdier. For å håndtere disse kan vi bruke metoder som for eksempel fillna(), som fyller manglende verdier med en standardverdi. Eller så kan vi bruke dropna(), som fjerner radene med manglende verdi. Vi kan også møte på ufullstendige datoer eller datoer i ukjent format. Da kan vi bruke pd.to_datetime() for å sikre at datoene blir riktig konvertert til datetime format.  + +Vi kan også møte ekstremverdier, som vi kan fjerne ved å sjekke om de er "uteliggere" ved å ligge mer enn tre standardavvik i fra gjennomsnittet. Da kan vi bruke verdien før med fillna('obj.ffill()') eller bruke interpolate linear metoden for å få den mest "smoothe" overgangen mellom manglende verdier. Da den "gjetter" seg frem til manglende verdier. \ No newline at end of file diff --git a/data/README.md b/data/README.md index 401b18a..2721585 100644 --- a/data/README.md +++ b/data/README.md @@ -1,13 +1,11 @@ # Data-description -### Possible API -- **API from openweathermap** -[API_OPEN_WEATHER_MAP](https://openweathermap.org/) +Her vil det opprettes ulike mapper som et resultat av dataene som lagres gjennom kjøringen av de ulike notebookene. -- **API from meterologisk institutt** -[API_FROST](https://frost.met.no/index.html) - -### Possible dataset -- **Natural Disasters:** -[DATASET_1](https://www.kaggle.com/datasets/brsdincer/all-natural-disasters-19002021-eosdis) +Funksjonen er bygd slik at den først sjekker om det eksisterer en mappe, før den eventuelt lager. Alle mapper som starter med output (altså output data) er lagt til i `.gitignore`. Dette for å ikke laste opp masse unødvendig til github, men også for at brukere ikke 'deler' data. Mine kjøringer vil være mine, og dine vil kun vises hos deg. +Dette er eksempel på noen av mappene: +- `output_current_data` lagrer dataen for ønsket sted, kjørt fra `notebook_current_data.ipynb` +- `output_fig` lagrer grafer, kjørt fra `notebook_statistic_data.ipynb` +- `output_record` lagrer rekord data fra ønsket sted, kjørt fra `notebook_statistic_data.ipynb` +- `output_statistikk` lagrer dataen for ønsket sted, kjørt fra`notebook_statistic_data.ipynb` \ No newline at end of file diff --git a/notebooks/README.md b/notebooks/README.md index 8c1d051..23f68fb 100644 --- a/notebooks/README.md +++ b/notebooks/README.md @@ -1 +1,14 @@ -# Notebook - description \ No newline at end of file +# Notebook - description + +Her finnes informasjon om de ulike notebookene og deres innhold. + +- [Current data](notebook_current_data.ipynb) + Denne notebooken er for å hente, skrive og vise nåværende data for ønsket lokasjon. +- [One day data](notebook_one_day_data.ipynb) + Denne notebooken henter data fra ønsket dag og sted, skriver til fil. Visualiserer manglende verdier, retter opp manglende verdier, og visualisere og lagrer data fra plot. +- [One week data](notebook_one_week_data.ipynb) + Denne notebooken henter data fra ønsket periode (inntil 7-dager) og sted, skriver til fil. Visualiserer manglende verdier, retter opp manglende verdier, og visualisere og lagrer data fra plot. +- [Statistic year data](notebook_statistic_data.ipynb) + Denne notebooken henter data fra en API som samler alle historiske data for ønsket sted, å regner ut statistiske verdier for alle dagene i året. Vi fjerner uønskede kolonner, utelukker ekstremverdier og visualiserer data gjennom plotter. +- [Test notebook](test_notebook.ipynb) + Dette er bare en test notebook, for å se om venv funker og det å importere funksjoner fra packager. \ No newline at end of file diff --git a/resources/README.md b/resources/README.md index 142fb2d..ec71c31 100644 --- a/resources/README.md +++ b/resources/README.md @@ -1 +1,28 @@ -# Resources - description \ No newline at end of file +# Resources - description + +Kilden til våre API-er er: [Open Weather](https://openweathermap.org/) + +Her finner vi API-er for: +- Current Data (Now) +- Historical Data (7 days) +- Statistic Historical Data (A year) + +For å benytte denne API-en må man lage en bruker, og som student for man tilgang på en del "ekstra" ressurser gratis. Her kommer en oversikt over hvordan lage bruker: +1. Du kan registrere bruker [HER](https://home.openweathermap.org/users/sign_up?student=true) +2. Når du logger inn trykker du til din profil å finner fanen 'API keys' +3. Kopier koden +4. Gå inn i `src/my_package/setup.py` kjør funksjonen, og du kan lime inn mail og API-key i terminalen +5. Finn en notebook, og kjør kode! +6. Du skal nå få data fra API-en + +### Possible API +- **API from openweathermap** +[API_OPEN_WEATHER_MAP](https://openweathermap.org/) + +- **API from meterologisk institutt** +[API_FROST](https://frost.met.no/index.html) + +### Possible dataset +- **Natural Disasters:** +[DATASET_1](https://www.kaggle.com/datasets/brsdincer/all-natural-disasters-19002021-eosdis) + diff --git a/src/README.md b/src/README.md index 42a797b..fca3fd8 100644 --- a/src/README.md +++ b/src/README.md @@ -1 +1,16 @@ -# Src - description \ No newline at end of file +# Src - description + +Mye av funksjonaliteten og funksjonener er skrevet i en vanlig `.py` fil, før de er importert til notebooken og kjøres der. + +`my_package` med en `__init__.py` gjør at funksjonene funker som 'moduler' og blir mulig å importere til videre bruk. + +Her kommer en kjapp forklaring av de ulike filene og deres funksjoner: +- `date_to_unix.py` bruker innebygde moduler som datetime og time, for å gjøre om datoer og tider til unix timestamp, sekunder fra 1. januar 1970. +- `fetch_current_data.py` funksjon for å hente nåværende data for ønsket sted fra API-en. Sender feilkode dersom statusen ikke har 200, altså ok. +- `fetch_data.py` henter data for ønsket sted, fra ønsket starttid til sluttid. Sender feilkode dersom statusen ikke har 200, altså ok. +- `get_record.py` brukt i `notebook_statistic_data.ipynb` for å finne rekord-målinger som høyeste og laveste målte temperatur. +- `setup.py` funskjon for å hjelpe brukeren å lage en .env fil for å lagre API-key og email. +- `test_module.py` en test funksjon for å sjekke at venv og implementering til notebook funker som det skal. +- `util.py` inneholder funksjoner for å erstatte nordiske (æøå) og å omgjøre temperaturer fra kelvin til celsius. Altså funksjoner som bare er en enkel del av noe større. +- `write_data.py` lagrer data i json-format, med ønsket filnavn til en 'passende' mappe basert på hvor funksjonen brukes. +- `year_data.py` henter statistisk værdata basert på historikk for ønsket sted. Sender feilkode dersom statusen ikke har 200, altså ok. \ No newline at end of file diff --git a/tests/README.md b/tests/README.md index aa1174a..69f95b0 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1 +1,8 @@ -# Test - description \ No newline at end of file +# Test - description + +Her har vi lagd noen enkle tester for å sjekke deler av funksjonaliteten. Det skal legges til at det gjøres flere 'tester' av koden inne i koden, som `try and except`, `if-else` og `raise Error`. Dette sørger for å raskere oppfatte feil når man kjører koden. + +Her er litt info om testene: +- `test_letter_one_day.py` Tester at man får samme data av et sted med stor og liten bokstav. +- `test_one_day.py` Tester at funksjonaliteten for å gjøre om fra unix-timestamp blir den samme som input date. +- `test_test.py` Bare en første test for å sjekke at unittest funker. \ No newline at end of file