RUŌOD Lab

Mastery course · Software and Computational Perfumery

Mastery Project: A Reproducible Computational Record

The computational course project: a normalized record of one formula, a tested script that reproduces the app's figures, a version diff and a model critique.

Mastery 40 min study By the RUŌOD Lab team Updated

In short

This project closes the computational course. Take one formula of your own through at least four versions and hold its whole development as data: normalized tables, a tested script that reproduces the app's figures, a diff of each version pair with its reasons, a descriptor table of its single-molecule materials, and a critique of one odor-prediction claim relevant to it. The test of the project is whether someone else, given only the folder, can recalculate everything.

What you will learn

  • Hold one formula's development as normalized, sourced data that someone else could reuse
  • Show by tests that two independent calculations agree, and explain every difference
  • Pair a structural analysis of the formula's materials with an honest statement of what it cannot predict

Before this lesson: A Data Model for Formulas and Materials, Fragrance Calculations in Python, Checked, Diffing Formula Versions, Molecular Descriptors for Odorants, Validating Odor-Prediction Models, RUŌOD Lab Tutorial: Versions, History, Reports and Exports

The folder

  • materials.csv, stocks.csv, formulas.csv, versions.csv, lines.csv, and dictionary.md defining every column.
  • calculate.py with its assertions, and output.txt from running it.
  • comparison.md: every figure of the final version from the script, from the RUŌOD Lab app (or a spreadsheet) and from a hand calculation of three lines, with each difference explained.
  • diffs/: one diff per consecutive version pair, each change linked to its reason.
  • descriptors.csv: SMILES with sources and computed descriptors for the formula's single molecules.
  • critique.md: the structured critique from the validation lesson.
  • README.md: what the formula is for, how to rerun everything, what is confidential, and what the record does not establish.

Standards the record must meet

  1. Stable ids everywhere; no row refers to anything by name.
  2. Every external value sourced and dated: limits, costs, CAS numbers, SMILES.
  3. No derived value stored by hand; percentages come from the script.
  4. Tests written from hand values first.
  5. Plain formats that open in ten years.

Choosing the formula

Use a formula you own outright and can make, with at least eight lines, two of them diluted, one free solvent line and at least three single-molecule materials (so the descriptor work has something to describe). If the formula is confidential, keep a private folder for yourself and build a second, shareable folder from an illustrative formula that exercises the same calculations; label each clearly. The skill being assessed is the record, not the formula.

A sensible order of work

Build the tables first and calculate from them before you open the app, so that the app cannot shape your records. Then enter the same formula in the app, version it by Duplicate as you develop it, and export each version. Diffs and the comparison come next, and the descriptor table and critique last, once you know which materials matter most to the result. Keep a short log of each working session in the README; it is what lets the other person follow your path.

Why this matters beyond the course

Formulas outlive the tools they were written in. A perfumer who can hand over a formula as checked, sourced, versioned data — to a manufacturer, a safety assessor, a successor or a future self — has removed the most common cause of irreproducible fragrance work, which is not chemistry but record-keeping. The professional practice course returns to this when it discusses specifications and handover.

Practical exercise: The computational course project

About 1200 minutes · You will have: a folder of CSV tables, a tested script with its output, diffs of every version pair, a descriptor table, a model critique and a README of about 1,500 words

Build the folder, then give it to someone else with no explanation beyond the README, and ask them to rerun the script and reproduce one diff.

Assess yourself against these criteria:

  • The other person reproduced the figures and a diff from your files alone.
  • Every disagreement between calculations is explained.
  • Every external value has a source and a date.
  • The README states plainly that the record verifies arithmetic and history, not safety, compliance or quality.

Common mistakes

  • A README written for yourself. Write it for the person who has never seen the formula.
  • Untested scripts. A script without assertions is a claim, not a check.
  • Mixing illustrative and real data without saying which is which.

Knowledge check

1. What makes the record reproducible?
Show the answer

Someone else can recalculate every figure from your files and get your numbers. Reproducibility is a test someone else can run, not a format.

2. Your script and the app disagree in the fourth decimal on one line. What belongs in the README?
Show the answer

The difference and its cause, such as rounding order. Explained differences are part of a verified record; unexplained ones are open questions.

3. Should the project folder include confidential formulas if you share it?
Show the answer

Only what you are entitled to share; a shared record can use an illustrative or permitted formula. FAIR data are usable by whoever is entitled to them; confidentiality is a choice you record, not a reason for poor records.

Sources

  • Wilkinson MD, et al. The FAIR Guiding Principles for scientific data management and stewardship. Scientific Data 3:160018, 2016 — Findable, accessible, interoperable, reusable

Further reading and materials

Written and reviewed by the RUŌOD Lab team. This is general education, not legal, regulatory, medical or safety advice. Example dilutions and exercises are for learning, are not validated products, and have not been safety-assessed. Completing a lesson confers no qualification. How we check these lessons.