X2_GeneratingTimestampedFilenames/X2_GeneratingTimestampedFilenames.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "416049d7",
   "metadata": {},
   "source": [
    "# `X2`: Extra Content 2: Generating Timestamped Filenames\n",
    "\n",
    "A common requirement of sensor systems is that they write measurements to data files. This extra content describes why+how data files are typically named with timestamps.\n",
    "\n",
    "---\n",
    "\n",
    "All sensor practicals (`S1-S4`) in the PBL course involve writing data files. Anything you see here should be considered part of the sensor practical.\n",
    "\n",
    "> ℹ️ **Example**: `S2` contains a step where you need to write IMU data to a CSV file. Consequently, it recommends reading `X2` (this material, to name the file) and `X1` (to write CSV data to the file). The rest of `S2` then assumes you are familiar with all of the content in `X1` and `X2`.\n",
    "\n",
    "\n",
    "## Why Use Timestamped Filenames?\n",
    "\n",
    "It might be tempting to call a data file something like `IMU_data.csv`. However, using that naming convention will cause problems when the system needs to store *multiple* measurements. If each measurement (e.g. a participant walking around a lab) produces a data file with the same name (e.g. `IMU_data.csv`), then data may be lost because your script may overwrite older data with the same name. For example, when you run `open(\"IMU_data.csv\", \"w\")` a second time, it will delete the old `IMU_data.csv`.\n",
    "\n",
    "One \"pure\" way to avoid this problem is to generate a uniformly random name (e.g. `xyOm2qP_IMU_data.csv`). However, that's impractical to work with because random strings don't neatly sort in any relevant way (they're random), and they are impossible to match up with external measurement records (e.g. camera footage, phone clocks, lab notes, and other sensors).\n",
    "\n",
    "The most common--and practical--way to generate unique filenames is to add a timestamp prefix/suffix to the name (e.g. `2022-01-02T11301113_IMU_data.csv`). This convention typically generates a unique-enough filename that is sortable and can be cross-linked with other data/measurements/notes.\n",
    "\n",
    "\n",
    "## Using the `datetime` Module\n",
    "\n",
    "Here, we will make our filenames unique by having them contain the date and time that the data was acquired. To do this, we will use python's in-built `datetime` library. To explore what `datetime` does, you can run the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b14b2c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime\n",
    "\n",
    "x = datetime.now()\n",
    "print(x.__class__)  # datetime.now() returns a `datetime` object\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "809cef43",
   "metadata": {},
   "source": [
    "The `datetime` object returned by `datetime.now()` stores a timestamp that identifies the year, month, day, hour, minute, second, and microsecond. `print`ing a `datetime` object prints all of this information.\n",
    "\n",
    "However, the information might not be in the format that you need. E.g. for your data files, you will want a different format. To handle that, the `datetime` module also provides `strftime` ([Python docs](https://docs.python.org/3/library/datetime.html?highlight=strftime#strftime-and-strptime-behavior)), which reformats a `datetime` as a string with a caller-defined format ([Python docs](https://docs.python.org/3/library/datetime.html?highlight=strftime#strftime-and-strptime-format-codes)). For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2d93ef1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime\n",
    "\n",
    "datetime.now().strftime(\"%Y is a great year\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fcff8d8",
   "metadata": {},
   "source": [
    "Notice that `%Y` as substituted for the current year. See the [official python documentation](https://docs.python.org/3/library/datetime.html?highlight=strftime#strftime-and-strptime-format-codes) for a full list of possibilities.\n",
    "\n",
    "> 🏆 **Challenge `X2.a`**: Write the necessary python code to create a datetime string in a format like so: `20220404-114200` (i.e. year,month,day - hour,minute,second).\n",
    ">\n",
    "> This is important, because you will be using the string in your data file names later (e.g. `data/output_20220404-114200.csv`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6a973faf",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime \n",
    "\n",
    "# 🏆 write your code here: example output: `20220404-114200`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "279d0c7f",
   "metadata": {},
   "source": [
    "> 🏆 **Challenge `X2.b`**: Write the necessary python code to combine the timestamp string generated above with the appropriate suffixes and extensions you need for your output file\n",
    ">\n",
    "> Hints:\n",
    ">\n",
    "> - `strftime` produces a string\n",
    "> - Python provides a variety of methods for combining strings. E.g. `\"hello, \" + \"world!\"`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "601e704e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime \n",
    "\n",
    "# 🏆 write your code here: example output: `20220404-114200_IMU_data.csv`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f54e9364",
   "metadata": {},
   "source": [
    "> ❓ **Test Yourselves**:\n",
    ">\n",
    "> - Do you understand each line of Python in this extra material?\n",
    "> - Could you use the [Python documentation](https://docs.python.org/3/library/datetime.html?highlight=strftime#strftime-and-strptime-format-codes) to create a different type of timestamp?\n",
    "> - This extra material only covers generating a string, not a file. How would you use the timestamped filename string you generated to create a file with that name?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}