13 KiB

Raw Blame History

AGENTS.md

Projektin yleiskatsaus

Data Science for Beginners on Microsoft Azure Cloud Advocatesin luoma kattava 10 viikon, 20 oppitunnin opetusohjelma. Tämä repositorio on oppimisresurssi, joka opettaa perustavanlaatuisia datatieteen käsitteitä projektipohjaisten oppituntien avulla, mukaan lukien Jupyter-muistikirjat, interaktiiviset visailut ja käytännön tehtävät.

Keskeiset teknologiat:

Jupyter-muistikirjat: Pääasiallinen oppimisväline Python 3:lla
Python-kirjastot: pandas, numpy, matplotlib datan analysointiin ja visualisointiin
Vue.js 2: Visailusovellus (quiz-app-kansio)
Docsify: Dokumentaation sivustogeneraattori offline-käyttöön
Node.js/npm: JavaScript-komponenttien pakettien hallinta
Markdown: Kaikki oppituntien sisältö ja dokumentaatio

Arkkitehtuuri:

Monikielinen opetusrepositorio laajoilla käännöksillä
Jäsennelty oppituntimoduuleihin (1-Introduction - 6-Data-Science-In-Wild)
Jokainen oppitunti sisältää README:n, muistikirjat, tehtävät ja visailut
Erillinen Vue.js-visailusovellus oppituntien arviointiin ennen ja jälkeen
GitHub Codespaces ja VS Code -kehityskonttien tuki

Asennuskomennot

Repositorion asennus

# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners

Python-ympäristön asennus

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

Visailusovelluksen asennus

# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint

Docsify-dokumentaatiopalvelin

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

Visualisointiprojektien asennus

Visualisointiprojekteille, kuten meaningful-visualizations (oppitunti 13):

# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint

Kehitystyön kulku

Työskentely Jupyter-muistikirjojen kanssa

Käynnistä Jupyter repositorion juurihakemistossa: jupyter notebook
Siirry haluttuun oppituntikansioon
Avaa .ipynb-tiedostot harjoitusten tekemistä varten
Muistikirjat ovat itsenäisiä ja sisältävät selityksiä sekä koodisoluja
Useimmat muistikirjat käyttävät pandas-, numpy- ja matplotlib-kirjastoja - varmista, että ne on asennettu

Oppituntien rakenne

Jokainen oppitunti sisältää yleensä:

README.md - Pääsisältö teoriaa ja esimerkkejä varten
notebook.ipynb - Käytännön Jupyter-muistikirjaharjoituksia
assignment.ipynb tai assignment.md - Harjoitustehtäviä
solution/-kansio - Ratkaisumuistikirjat ja koodi
images/-kansio - Tukimateriaalit

Visailusovelluksen kehitys

Vue.js 2 -sovellus, jossa on hot-reload kehityksen aikana
Visailut tallennetaan quiz-app/src/assets/translations/-kansioon
Jokaisella kielellä on oma käännöskansio (en, fr, es jne.)
Visailujen numerointi alkaa 0:sta ja jatkuu 39:ään (yhteensä 40 visailua)

Käännösten lisääminen

Käännökset sijoitetaan translations/-kansioon repositorion juurihakemistossa
Jokaisella kielellä on täydellinen oppituntirakenne, joka peilaa englanninkielistä
Automaattinen käännös GitHub Actionsin kautta (co-op-translator.yml)

Testausohjeet

Visailusovelluksen testaus

cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve

Muistikirjojen testaus

Muistikirjoille ei ole olemassa automaattista testauskehystä
Manuaalinen validointi: Suorita kaikki solut järjestyksessä varmistaaksesi, ettei virheitä esiinny
Varmista, että datatiedostot ovat saatavilla ja tulokset luodaan oikein
Tarkista, että visualisoinnit renderöityvät oikein

Dokumentaation testaus

# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation

Koodin laadun tarkistukset

# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors

Koodityyliohjeet

Python (Jupyter-muistikirjat)

Noudata PEP 8 -tyyliohjeita Python-koodissa
Käytä selkeitä muuttujanimiä, jotka kuvaavat analysoitavaa dataa
Sisällytä markdown-solut selityksillä ennen koodisoluja
Pidä koodisolut keskittyneinä yksittäisiin käsitteisiin tai operaatioihin
Käytä pandas-kirjastoa datan käsittelyyn ja matplotlib-kirjastoa visualisointiin

Yleinen tuontimalli:

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

JavaScript/Vue.js

Noudata Vue.js 2 -tyyliopasta ja parhaita käytäntöjä
ESLint-konfiguraatio quiz-app/package.json-tiedostossa
Käytä Vue-yksittäistiedostokomponentteja (.vue-tiedostot)
Säilytä komponenttipohjainen arkkitehtuuri
Suorita npm run lint ennen muutosten lähettämistä

Markdown-dokumentaatio

Käytä selkeää otsikkohierarkiaa (# ## ### jne.)
Sisällytä koodilohkot kielimäärityksillä
Lisää kuville alt-teksti
Linkitä liittyviin oppitunteihin ja resursseihin
Pidä rivin pituudet kohtuullisina luettavuuden vuoksi

Tiedostojen organisointi

Oppituntisisältö numeroiduissa kansioissa (01-defining-data-science jne.)
Ratkaisut omissa solution/-alikansioissaan
Käännökset peilaavat englanninkielistä rakennetta translations/-kansiossa
Datatiedostot data/-kansiossa tai oppituntikohtaisissa kansioissa

Rakentaminen ja käyttöönotto

Visailusovelluksen käyttöönotto

cd quiz-app

# Build production version
npm run build

# Output is in dist/ folder
# Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.)

Azure Static Web Apps -käyttöönotto

Visailusovellus voidaan ottaa käyttöön Azure Static Web Appsissa:

Luo Azure Static Web App -resurssi
Yhdistä GitHub-repositorioon
Määritä rakennusasetukset:
- Sovelluksen sijainti: quiz-app
- Tulosteen sijainti: dist
GitHub Actions -työnkulku ottaa käyttöön automaattisesti pushin yhteydessä

Dokumentaatiosivusto

# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify

GitHub Codespaces

Repositorio sisältää kehityskonttien konfiguraation
Codespaces asentaa automaattisesti Python- ja Node.js-ympäristön
Avaa repositorio Codespacessa GitHubin käyttöliittymän kautta
Kaikki riippuvuudet asennetaan automaattisesti

Pull Request -ohjeet

Ennen lähettämistä

# For Vue.js changes in quiz-app
cd quiz-app
npm run lint
npm run build

# Test changes locally
npm run serve

PR-otsikon muoto

Käytä selkeitä, kuvaavia otsikoita
Muoto: [Komponentti] Lyhyt kuvaus
Esimerkkejä:
- [Oppitunti 7] Korjaa Python-muistikirjan tuontivirhe
- [Visailusovellus] Lisää saksankielinen käännös
- [Dokumentaatio] Päivitä README uusilla vaatimuksilla

Vaaditut tarkistukset

Varmista, että kaikki koodi toimii ilman virheitä
Tarkista, että muistikirjat suorittavat kokonaan
Varmista, että Vue.js-sovellukset rakentuvat onnistuneesti
Tarkista, että dokumentaatiolinkit toimivat
Testaa visailusovellus, jos sitä on muokattu
Varmista, että käännökset säilyttävät yhtenäisen rakenteen

Osallistumisohjeet

Noudata olemassa olevia koodityylejä ja -malleja
Lisää selittäviä kommentteja monimutkaiselle logiikalle
Päivitä asiaankuuluva dokumentaatio
Testaa muutokset eri oppituntimoduuleissa, jos sovellettavissa
Lue CONTRIBUTING.md-tiedosto

Lisähuomautuksia

Yleisesti käytetyt kirjastot

pandas: Datan käsittely ja analysointi
numpy: Laskennallinen matematiikka
matplotlib: Datan visualisointi ja kaavioiden luonti
seaborn: Tilastollinen datan visualisointi (joissakin oppitunneissa)
scikit-learn: Koneoppiminen (edistyneet oppitunnit)

Työskentely datatiedostojen kanssa

Datatiedostot sijaitsevat data/-kansiossa tai oppituntikohtaisissa hakemistoissa
Useimmat muistikirjat odottavat datatiedostoja suhteellisissa poluissa
CSV-tiedostot ovat ensisijainen datamuoto
Joissakin oppitunneissa käytetään JSON-tiedostoja ei-relationaalisen datan esimerkkeinä

Monikielinen tuki

Yli 40 kielen käännökset automaattisesti GitHub Actionsin kautta
Käännöstyönkulku .github/workflows/co-op-translator.yml-tiedostossa
Käännökset translations/-kansiossa kielikoodeilla
Visailukäännökset quiz-app/src/assets/translations/-kansiossa

Kehitysympäristön vaihtoehdot

Paikallinen kehitys: Asenna Python, Jupyter, Node.js paikallisesti
GitHub Codespaces: Pilvipohjainen välitön kehitysympäristö
VS Code Dev Containers: Paikallinen konttipohjainen kehitys
Binder: Käynnistä muistikirjat pilvessä (jos konfiguroitu)

Oppituntisisällön ohjeet

Jokainen oppitunti on itsenäinen, mutta rakentuu aiempien käsitteiden päälle
Ennakkovisailut testaavat aiempaa tietämystä
Jälkivisailut vahvistavat oppimista
Tehtävät tarjoavat käytännön harjoitusta
Sketchnotes tarjoaa visuaalisia yhteenvetoja

Yleiset ongelmatilanteet

Jupyter-ytimen ongelmat:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

npm-asennuksen epäonnistumiset:

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Tuontivirheet muistikirjoissa:

Varmista, että kaikki tarvittavat kirjastot on asennettu
Tarkista Python-version yhteensopivuus (suositus: Python 3.7+)
Varmista, että virtuaaliympäristö on aktivoitu

Docsify ei lataudu:

Varmista, että palvelin toimii repositorion juurihakemistosta
Tarkista, että index.html-tiedosto on olemassa
Varmista oikea verkkoyhteys (portti 3000)

Suorituskykyhuomautukset

Suuret datatiedostot voivat kestää aikaa latautua muistikirjoissa
Visualisointien renderöinti voi olla hidasta monimutkaisille kaavioille
Vue.js-kehityspalvelin mahdollistaa nopean iteroinnin hot-reloadin avulla
Tuotantoversiot ovat optimoituja ja pienennettyjä

Tietoturvahuomautukset

Älä tallenna arkaluontoisia tietoja tai tunnuksia
Käytä ympäristömuuttujia pilvioppituntien API-avaimille
Azureen liittyvät oppitunnit saattavat vaatia Azure-tilin tunnuksia
Pidä riippuvuudet ajan tasalla tietoturvapäivitysten varalta

Osallistuminen käännöksiin

Automaattiset käännökset hallinnoidaan GitHub Actionsin kautta
Manuaaliset korjaukset ovat tervetulleita käännösten tarkkuuden parantamiseksi
Noudata olemassa olevaa käännöskansiota
Päivitä visailulinkit sisältämään kieliparametri: ?loc=fr
Testaa käännetyt oppitunnit varmistaaksesi oikean renderöinnin

Liittyvät resurssit

Pääopetusohjelma: https://aka.ms/datascience-beginners
Microsoft Learn: https://docs.microsoft.com/learn/
Student Hub: https://docs.microsoft.com/learn/student-hub
Keskustelufoorumi: https://github.com/microsoft/Data-Science-For-Beginners/discussions
Muut Microsoftin opetusohjelmat: ML for Beginners, AI for Beginners, Web Dev for Beginners

Projektin ylläpito

Säännölliset päivitykset sisällön ajantasaisena pitämiseksi
Yhteisön panokset ovat tervetulleita
Ongelmia seurataan GitHubissa
PR:t tarkistetaan opetusohjelman ylläpitäjien toimesta
Kuukausittaiset sisällön tarkistukset ja päivitykset

Vastuuvapauslauseke:
Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua Co-op Translator. Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset voivat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäisellä kielellä tulisi pitää ensisijaisena lähteenä. Kriittisen tiedon osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa väärinkäsityksistä tai virhetulkinnoista, jotka johtuvat tämän käännöksen käytöstä.

13 KiB Raw Blame History