audit-labs/tutorials

Learn how to perform data analysis, scripting, automation, and more! data-analysis learning scripting tutorials

Commit 54aaa07bf2

54aaa07bf2603bff25047ce786e9fa4783e395e6

parent: 89f799ea58

Unsigned

cmc <hello@cleberg.net> · 2026-01-27 22:15 UTC 

Add README, environment files, CI workflow, CONTRIBUTING and Code of Conduct

Layout: unified · split

README.md added +135
@@ -0,0 +1,135 @@
1# audit-labs/tutorials
2
3Learn how to perform data analysis, scripting, automation, and more using reproducible Jupyter Notebooks.
4
5[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/audit-labs/tutorials/HEAD)
6[![Notebooks](https://img.shields.io/badge/notebooks-Jupyter-orange.svg)]()
7[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)]()
8
9Table of contents
10- [Project overview](#project-overview)
11- [Who this is for](#who-this-is-for)
12- [What's included](#whats-included)
13- [Getting started](#getting-started)
14 - [Prerequisites](#prerequisites)
15 - [Quick start — using Binder (no local setup)](#quick-start---using-binder-no-local-setup)
16 - [Run locally (recommended)](#run-locally-recommended)
17 - [Run in Google Colab](#run-in-google-colab)
18 - [Run with Docker](#run-with-docker)
19 - [Run headless / export notebooks](#run-headless--export-notebooks)
20- [Best practices for notebooks](#best-practices-for-notebooks)
21- [Contributing](#contributing)
22- [License & Code of Conduct](#license--code-of-conduct)
23- [Contact / Support](#contact--support)
24
25## Project overview
26This repository contains interactive tutorials and example notebooks designed to teach practical skills in data analysis, scripting, automation, and related topics using Jupyter Notebooks. Each notebook demonstrates concepts through hands-on examples so you can follow along and adapt the patterns to your own projects.
27
28## Who this is for
29- Data analysts and engineers learning reproducible workflows.
30- Developers who want to prototype automation or analysis in notebooks.
31- Students and instructors seeking ready-made examples for teaching.
32
33## What's included
34- A collection of Jupyter Notebook tutorials (look in the repository root or `notebooks/` folder for .ipynb files).
35- Guidance and examples that demonstrate common patterns for data ingestion, transformation, visualization, and basic automation.
36
37(If your repo has a specific folder layout or important notebooks, consider adding a short list here with links to the most important notebooks.)
38
39## Getting started
40
41### Prerequisites
42- Python 3.10+ (3.10 recommended)
43- Git (to clone the repo)
44- JupyterLab or Jupyter Notebook (for local development)
45
46Optional:
47- Conda (recommended for reproducible environments)
48- Docker (for containerized runs)
49
50This repository is licensed under the GNU General Public License v3.0 (GPL-3.0). See the included LICENSE file for details.
51
52### Quick start — using Binder (no local setup)
53To run the notebooks in your browser with no local install, use Binder:
54
55- Launch Binder: https://mybinder.org/v2/gh/audit-labs/tutorials/HEAD
56
57Binder will respect `environment.yml` or `requirements.txt` if present; this repository includes an `environment.yml` to produce a reproducible environment.
58
59### Run locally (recommended)
60
611. Clone the repository
62 ```bash
63 git clone https://github.com/audit-labs/tutorials.git
64 cd tutorials
65 ```
66
672. Create and activate an environment
68
69 Using conda (recommended):
70 ```bash
71 conda env create -f environment.yml
72 conda activate audit-tutorials
73 ```
74
75 Or with pip and virtualenv:
76 ```bash
77 python -m venv venv
78 source venv/bin/activate # macOS / Linux
79 venv\Scripts\activate # Windows
80 pip install --upgrade pip
81 pip install -r requirements.txt
82 ```
83
843. Install JupyterLab (if not already)
85 ```bash
86 pip install jupyterlab
87 jupyter lab
88 ```
89 Or run the classic notebook server:
90 ```bash
91 jupyter notebook
92 ```
93
944. Open the notebooks in the browser and follow the cells.
95
96### Run in Google Colab
97To open a notebook in Colab:
98- Navigate to the notebook file on GitHub, then use "Open in Colab" or open via:
99 https://colab.research.google.com/github/audit-labs/tutorials/blob/HEAD/path/to/notebook.ipynb
100- Colab will run in the cloud; you may need to pip-install extra dependencies at the top of the notebook using `!pip install ...`.
101
102### Run with Docker
103You can run the notebooks inside a Docker container using Jupyter's base images:
104```
105docker run -p 8888:8888 -v "$(pwd)":/home/jovyan/work jupyter/base-notebook:latest
106```
107Then open `http://localhost:8888` and navigate to `work/`.
108
109### Run headless / export notebooks
110To execute notebooks and export them programmatically:
111```
112pip install nbconvert nbclient
113jupyter nbconvert --to html --execute path/to/notebook.ipynb
114```
115This is useful for CI pipelines and automated report generation.
116
117## Best practices for notebooks
118- Keep notebooks focused: one concept or analysis per notebook.
119- Include a short README or top-level markdown cell describing purpose and inputs.
120- Avoid long-running data downloads inside notebooks—prefer referencing local sample data or scripts.
121- Use version control: commit notebooks regularly. Consider tools like `nbstripout` or `nbdime` to manage diffs.
122- Parametrize notebooks for reproducibility (e.g., use papermill for parameterized runs).
123
124## Contributing
125See CONTRIBUTING.md for contribution guidelines.
126
127## License & Code of Conduct
128This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See [LICENSE](./LICENSE) for details.
129
130Please review CODEOFCONDUCT.md for expected behavior when contributing.
131
132## Contact / Support
133For questions or help, open an issue in this repository or contact the maintainers listed in the repository settings.
134
135---\ No newline at end of file