Research Logging

9. Research Logging#

9.1. Why Research Logs Matter#

A research log is the working memory of a research project. It does not need to be polished, but it does need to be useful.

Research usually involves many small steps: reading background material, downloading and cleaning data, writing or editing code, changing parameters, making plots, finding and fixing mistakes, asking questions, meeting with a mentor, trying approaches that do not work, and returning later to continue the work.

Without a research log, these steps blur together. After a few days, it becomes difficult to remember what you tried, what files you used, what parameters you changed, or why you made a particular decision.

A good research log helps you answer practical questions later: What was I trying to do? Why was I trying to do it? What files, code, data, or papers did I use? What did I change? What happened? What confused me? What should I do next?

A research log is not just for your mentor. It is mainly for your future self. You may think you will remember what you did, but you probably will not. Research projects often stretch across weeks, months, or years. A detail that seems obvious today may be completely unclear two weeks from now.

A research log is useful because it supports reproducibility by making the work traceable to data, code, assumptions, and choices; memory by protecting you from rediscovering what you already learned; troubleshooting by showing what changed when something breaks; mentoring by helping your mentor see what you tried and where you got stuck; writing by becoming raw material for posters, talks, papers, theses, and final reports; progress tracking by showing that the project is moving even before the final result is complete; and efficiency by preventing you from repeating the same test, rerunning the same broken code, or losing the useful result.

9.1.1. What Counts as Research Work?#

New researchers sometimes think they should only write in the log when they get a successful result. That is not correct. You should write a log entry whenever you do work that changes your understanding of the project.

Research work includes reading a paper or documentation, meeting with your mentor, downloading data, checking whether data exist, writing or editing code, running a simulation, changing a parameter, making a plot, comparing two results, finding or fixing a mistake, getting an error message, realizing that an approach will not work, and deciding what to try next.

A failed attempt still belongs in the log. In research, a failed attempt often teaches you something important.

Examples worth logging include the following:

I tried to download data for this target, but no TESS light curve was available.

I changed the simulation timestep from 0.01 to 0.001. The result looked more stable, but the run time increased by about a factor of 10.

I do not understand why the plot has a gap near day 1350. Next time I need to inspect the data-quality flags.

Research logs are not only for success. They are for keeping track of the full path of the project.

9.2. Setting Up a Research Project#

9.2.1. Project Startup Checklist#

Before beginning a research project, set up the basic structure that will help you keep the work organized. You do not need everything to be perfect on day one, but you should know where notes, code, data, and figures will go.

Start-of-project checklist

Before starting serious work, make sure you have a project folder; places for daily logs, notebooks, scripts, raw data, processed data, and figures; a backup or sync plan; a way to track tasks; and a place to save paper notes and citations.

A good project setup prevents confusion later. Most research projects become messy because students start saving files wherever it is convenient in the moment. That works for one afternoon. It does not work for a project that lasts weeks, months, or years.

At the beginning of a project, ask your mentor where project files should be stored, which files should be shared, which files should not be uploaded to GitHub, whether large data files should be stored somewhere else, whether you should use Google Drive, GitHub, institutional storage, or another system, how often you should update your research log, and how often you should send progress summaries.

9.2.2. Recommended folder structure#

Keep the research log close to the project files, but do not mix notes, raw data, generated figures, and code randomly.

A simple project structure is:

research-project/
├── README.md
├── logs/
│   ├── 2026-05-18.md
│   ├── 2026-05-19.md
│   └── 2026-05-20.md
├── notebooks/
│   ├── 01_download_data.ipynb
│   └── 02_plot_lightcurve.ipynb
├── scripts/
│   └── analyze_lightcurve.py
├── data/
│   ├── raw/
│   └── processed/
└── figures/
    └── 2026-05-18_lightcurve.png

Use each folder for a specific purpose: logs/ contains daily notes and research decisions; notebooks/ contains exploratory calculations, plots, and analysis; scripts/ contains reusable Python code; data/raw/ contains original data that should not be edited; data/processed/ contains cleaned or derived data products; and figures/ contains saved plots, diagrams, and images.

Raw data and processed data should be separated when possible. Raw data means the original files you downloaded, received, or collected. Do not casually edit these files. If you need to clean or modify the data, save the result as a new file in data/processed/.

Rule of thumb

If you create a new file, your log should say where it is and why it exists.

9.2.3. File Naming Conventions#

Use filenames that help you understand what the file is without opening it. A good filename usually includes the date, the target or system name, the type of file, a short description, and sometimes a version number.

Examples:

2026-05-18_tic123456789_lightcurve.png
2026-05-18_tic123456789_sector17_cleaned.csv
2026-05-18_rebound_ebin0p2_ap3p0_summary.txt
2026-05-18_meeting-notes.md

Avoid vague filenames:

plot.png
new_plot.png
final_plot.png
final_final_plot.png
data.csv
notes.md
test.ipynb

Vague filenames create problems later because you cannot tell which file matters.

Rule of thumb

A filename should answer at least two questions:

What is this file?
When or why was it created?

For dates, use the format:

YYYY-MM-DD

For example:

2026-05-18

This keeps files sorted in chronological order and avoids confusion between month/day/year and day/month/year.

9.2.4. Project README Files#

A README.md file explains what a project folder or repository contains. The README is usually the first file someone should read when opening the project. A simple research project README should include the project title, a short project description, people involved, folder structure, instructions for running the main notebooks or scripts, notes about where data are stored, important warnings, and a contact person or mentor.

9.2.4.1. Simple README template#

# Project Title

## Project description

Briefly describe the goal of the project.

## People

- Student:
- Mentor:
- Collaborators:

## Folder structure

- `logs/`: daily research logs and meeting notes
- `notebooks/`: exploratory analysis notebooks
- `scripts/`: reusable Python scripts
- `data/raw/`: original data files
- `data/processed/`: cleaned or derived data files
- `figures/`: saved plots and diagrams

## How to run the analysis

1. Open `notebooks/01_download_data.ipynb`.
2. Run the cells in order.
3. Open `notebooks/02_plot_lightcurve.ipynb`.
4. Check that the output figure appears in `figures/`.

## Data notes

Describe where the data came from and whether large files are stored somewhere else.

## Important warnings

List anything a new person should know before using the files.

9.3. Writing Useful Log Entries#

9.3.1. The Minimum Useful Log Entry#

Every research work session should leave behind a log entry. A useful entry does not need to be long, but it should include enough information that you can restart the work later without guessing. At minimum, include the date, goal, actions, result, and next step.

Minimum research log entry

If you only have five minutes to write your log, write these five things:

Date: When did I do this work?
Goal: What was I trying to accomplish?
Actions: What did I actually do?
Result: What happened?
Next step: What should I do next?

9.3.1.1. Date#

The date matters because research projects are cumulative. You may need to compare today’s work with something you did last week or last month. Use a clear date format:

2026-05-18

This format avoids confusion between month/day/year and day/month/year.

9.3.1.2. Goal#

The goal is what you intended to accomplish during the work session. A weak goal is:

Work on project.

A better goal is:

Download the available TESS light curves for TIC 123456789 and make an initial plot.

The goal does not need to be ambitious. It just needs to be specific.

9.3.1.3. Actions#

The actions are what you actually did. This may be different from the goal. That is normal. Research often changes direction during a work session.

Include commands you ran, notebooks you opened, files you edited, parameters you changed, data you downloaded, plots you made, and papers or documentation you read.

9.3.1.4. Result#

The result is what happened. A result can be successful:

The light curve downloaded successfully and shows a possible transit-like dip.

A result can be unsuccessful:

The query returned no available data products.

A result can be uncertain:

The plot shows a feature near day 1350, but I do not know whether it is astrophysical or instrumental.

9.3.1.5. Next step#

The next step is one of the most important parts of the log. Write it as if you will forget everything before your next work session.

A weak next step is:

Keep going.

A better next step is:

Inspect the quality flags and remake the plot after removing flagged data points.

Write for future you

Assume that future you is tired, busy, and has not thought about this project for two weeks. Write enough detail that future you can restart without guessing.

9.3.2. Daily log template#

Copy this template at the start of each work session.

# Research Log: YYYY-MM-DD

## Goal

- 

## What I did

- 

## Files, code, or data used

- Notebook/script:
- Data files:
- Output files:
- Git commit, if relevant:

## Results

- 

## Problems or questions

- 

## Next steps

-

9.3.2.1. Example filled entry#

# Research Log: 2026-05-18

## Goal

- Download and inspect a TESS light curve.
- Make a first plot of flux versus time.

## What I did

- Used `lightkurve.search_lightcurve()` to search for available TESS data.
- Downloaded the first available light curve.
- Removed NaN values.
- Made a quick plot.

## Files, code, or data used

- Notebook: `notebooks/01_download_tess_lightcurve.ipynb`
- Figure: `figures/2026-05-18_tess_lightcurve.png`
- Package: `lightkurve`

## Results

- Found available TESS data.
- The light curve shows several gaps.
- The target may require additional cleaning before period analysis.

## Problems or questions

- I need to inspect the data-quality flags.
- I need to compare available sectors.

## Next steps

- Check the `quality` flags.
- Save a cleaned version of the light curve.
- Ask whether this target is suitable for period analysis.

9.3.3. Examples of Weak and Strong Log Entries#

The examples below show the difference between entries that are too vague and entries that are useful.

9.3.3.1. Example 1: Downloading data#

Weak entry:

Downloaded data. It worked.

This is not useful because it does not say what data were downloaded, what tool was used, where the data were saved, or what should happen next.

Stronger entry:

Used lightkurve.search_lightcurve() to search for TESS light curves for TIC 123456789. Found data from Sectors 17 and 18. Downloaded the Sector 17 light curve and saved the notebook as notebooks/01_download_tess_lightcurve.ipynb. The light curve contains several gaps, so the next step is to inspect the quality flags and compare with Sector 18.

9.3.3.2. Example 2: Running code#

Weak entry:

Fixed the code.

This is not useful because it does not say what was wrong or how it was fixed.

Stronger entry:

The plotting script failed because the time and flux arrays had different lengths after removing NaN values from only one array. I fixed this by creating a single mask and applying it to both arrays. The corrected script is scripts/plot_lightcurve.py. Next time, add a short check that prints the array lengths before plotting.

9.3.3.3. Example 3: Simulation work#

Weak entry:

Ran more simulations.

This is not useful because it does not identify the model, parameters, runtime, or result.

Stronger entry:

Ran three REBOUND simulations with binary eccentricity e_bin = 0.2 and planet semimajor axes a_p = 2.8, 3.0, and 3.2 AU. The a_p = 2.8 AU case became unstable before 10^4 binary periods. The a_p = 3.0 AU and 3.2 AU cases survived to 10^5 binary periods. Output files are saved in data/processed/2026-05-18_stability_tests/. Next step: run intermediate values between 2.8 and 3.0 AU.

9.3.3.4. Example 4: Being confused#

Weak entry:

I am confused.

This is honest, but not actionable.

Stronger entry:

I do not understand why the folded light curve has two dips instead of one. Possible explanations are: the period is wrong, the system is an eclipsing binary, or I accidentally folded the data at half the true period. Next step: compare the period with the catalog value and replot using twice the current period.

9.3.3.5. Example 5: Reading a paper#

Weak entry:

Read a paper about circumbinary planets.

This is too vague. It does not say which paper, what you learned, or how it connects to the project.

Stronger entry:

Read the introduction and methods section of a paper on circumbinary planet stability. The main idea I need to remember is that binary eccentricity changes the inner stability boundary for circumbinary planets. I saved the paper citation in Zotero and added notes in logs/paper_notes.md. Next step: ask whether the stability criterion from this paper should be compared with my REBOUND simulations.

9.4. Research Notes Beyond the Daily Log#

9.4.1. Meeting Notes#

Mentor meetings, group meetings, and research check-ins should be logged because a meeting can change the direction of a project. Meeting notes do not need to be a transcript. They should record what was discussed, what decisions were made, what questions remain, what tasks were assigned, and what you should do next.

9.4.1.1. Meeting notes template#

# Meeting Notes: YYYY-MM-DD

## People present

- 

## Main topics discussed

- 

## Decisions made

- 

## Questions or confusion

- 

## Tasks assigned to me

- 

## Tasks assigned to others

- 

## Next meeting or deadline

- 

## Next steps before the next meeting

-

9.4.1.2. Example meeting notes#

# Meeting Notes: 2026-05-18

## People present

- Student
- Research mentor

## Main topics discussed

- Whether TIC 123456789 is a good target for light-curve analysis.
- Whether to use Sector 17 or Sector 18 TESS data.
- How to handle data-quality flags.

## Decisions made

- Start with Sector 17 because it has fewer gaps.
- Remove flagged data points before interpreting possible dips.
- Save both the raw downloaded light curve and the cleaned version.

## Questions or confusion

- I am not sure which quality flags should always be removed.
- I need to ask whether scattered-light flags matter for this target.

## Tasks assigned to me

- Inspect the quality column.
- Make a plot before and after removing flagged points.
- Save the cleaned light curve in `data/processed/`.

## Next steps before the next meeting

- Finish the quality-flag comparison.
- Bring both plots to the next meeting.

Important

Do not rely on memory after a mentor meeting. Write down decisions and tasks before you forget the details.

9.4.2. Paper Reading Notes#

Reading papers is part of research work. It belongs in the research log. Do not try to write a perfect summary of every paper. Instead, record what the paper is, why you read it, what you learned, and how it affects your project.

Reading research papers

You are not expected to understand every part of a research paper the first time you read it. On a first pass, focus on the problem the paper is trying to solve, the method the authors used, the main result, the part that matters for your project, and the questions you should ask your mentor.

9.4.2.1. What to record when reading a paper#

For each important paper, record the full citation or link, why you are reading it, the main research question, the data or methods used, the main result, one or two details that matter for your project, questions you have, and whether you need to return to the paper later.

9.4.2.2. Paper notes template#

# Paper Notes: Short Title or First Author Year

## Citation

- 

## Why I am reading this paper

- 

## Main question of the paper

- 

## Methods or data used

- 

## Main result

- 

## Details relevant to my project

- 

## Terms or concepts I need to look up

- 

## Questions for my mentor

- 

## How this paper affects my next step

-

9.4.2.3. Example paper notes#

# Paper Notes: Example et al. 2020

## Citation

- Example et al. 2020, Journal Name, Volume, Page

## Why I am reading this paper

- This paper discusses stability limits for circumbinary planets.
- My project involves testing planet stability around binary stars using numerical simulations.

## Main question of the paper

- How close can a planet orbit to a binary star and remain stable?

## Methods or data used

- The authors ran numerical simulations over a range of binary eccentricities and planet semimajor axes.

## Main result

- The inner stability boundary moves outward when the binary eccentricity increases.

## Details relevant to my project

- I should compare my simulated stability boundary with the published empirical criterion.
- I need to record binary eccentricity carefully because it strongly affects the expected stability limit.

## Terms or concepts I need to look up

- Mean-motion resonance
- Critical semimajor axis
- Integration time

## Questions for my mentor

- Should I reproduce one of the paper's test cases before running my own grid?
- How long should my simulations run before I call an orbit stable?

## How this paper affects my next step

- Run a small test grid at fixed binary eccentricity before expanding to the full parameter range.

Common mistake

Do not write only “read paper.” Record what the paper changes about what you understand or what you will do next.

9.4.3. Using AI Tools as Part of a Research Workflow#

AI tools can help you understand code, summarize documentation, brainstorm next steps, prepare for mentor meetings, and search across a large set of research notes. However, an AI tool should not replace your own research record. The research log is still the authoritative record of what you did, what files changed, what results you found, and what you verified.

The most productive way to use AI in research is to treat it as a thinking assistant that works from your notes, code, data descriptions, and instructions. The quality of the output depends heavily on the quality of the context you provide. A vague prompt usually produces a vague answer. A specific prompt with role, context, task, constraints, and output format usually produces something more useful.

Basic rule

Use AI to help you think, search, summarize, debug, and plan. Do not use AI as a substitute for recording what actually happened in the project.

9.4.3.1. Why good research logs make AI more useful#

A good research log does more than help your future self. It also creates a source base that AI tools can use. If your logs are dated, specific, and organized, you can later ask an AI tool to help search across them, summarize progress, identify unresolved questions, or prepare a meeting agenda.

For example, a folder of Markdown logs can help answer questions like these:

Which targets had missing or poor-quality data?

What simulation parameters have already been tested?

What questions did I need to ask my mentor but have not resolved yet?

Summarize my progress from the last two weeks and list the next actions.

These questions only work well if the logs contain useful details. If the logs only say “worked on code” or “made plot,” then an AI tool will not have enough information to reconstruct what happened.

9.4.3.2. Using NotebookLM with research logs#

NotebookLM is useful when you have many notes, logs, papers, summaries, or project documents that you want to search and query together. For a research project, you can treat NotebookLM as a source-grounded assistant for your project notes.

A practical workflow is:

Keep daily logs, meeting notes, paper notes, and project summaries in a consistent format.
Export or save important notes as Markdown, PDF, Google Docs, or another source type supported by the tool you are using.
Add the logs, README file, meeting notes, paper notes, and important project documents to a NotebookLM notebook.
Ask questions that require NotebookLM to synthesize across the uploaded sources.
Check the cited source passages before trusting the answer.
Add new logs or summaries as the project grows.

NotebookLM is most useful when the sources are clean and specific. A well-organized set of research logs can become a searchable project memory. A messy set of vague logs will produce vague answers.

Important

NotebookLM can help you query your notes, but it does not replace checking the original source. Use its answers as a guide back to the relevant log entries, papers, or files.

Useful NotebookLM prompts for research logs include:

Summarize the major progress in these research logs. Group the summary by data work, coding work, simulation work, and unresolved questions.

Find all places where I mentioned a problem with quality flags, missing data, or suspicious gaps in the light curve. Quote or cite the relevant notes.

Create a meeting agenda for my next mentor meeting using the unresolved questions and next steps in these logs.

List every file, figure, or dataset mentioned in these logs. Organize them by folder and explain what each one was used for.

Based only on the uploaded logs, what are the next three actions I should take?

9.4.3.3. Keeping a prompt log#

If a prompt works well, save it. Prompt writing is part of the research workflow because a good prompt can be reused for future logs, paper notes, code reviews, meeting preparation, and summaries.

Create a file such as:

logs/prompt-log.md

or

prompts/research-prompts.md

A prompt log should record the prompt, the purpose, what worked, what did not work, and the reusable version.

9.4.3.3.1. Prompt log template#

# Prompt Log

## Prompt name

Date:
- 

Tool used:
- 

Purpose:
- 

Prompt text:
```text

```

Input or sources provided:
- 

Output used:
- 

What worked well:
- 

What did not work:
- 

Reusable version:
```text

```

Cautions:
- 

9.4.3.3.2. Example prompt log entry#

## Prompt name

Weekly research-log summary

Date:
- 2026-05-18

Tool used:
- NotebookLM

Purpose:
- Summarize one week of research logs before a mentor meeting.

Prompt text:
```text
Using only the uploaded research logs, summarize my progress from this week. Organize the summary into completed work, unresolved problems, files created, and questions for my mentor. Do not invent progress that is not supported by the logs.
```

Input or sources provided:
- Daily logs from 2026-05-12 through 2026-05-18
- Project README
- Meeting notes from 2026-05-13

Output used:
- Used the "questions for my mentor" section to prepare for the weekly meeting.

What worked well:
- The prompt forced the AI to separate completed work from unresolved problems.
- The output was easier to check because it was organized by category.

What did not work:
- It missed one figure that was mentioned only briefly.

Reusable version:
```text
Using only the uploaded research logs, summarize my progress from [date range]. Organize the summary into completed work, unresolved problems, files created, and questions for my mentor. Do not invent progress that is not supported by the logs.
```

Cautions:
- Check the file list manually before assuming it found every output file.

Rule of thumb

If you expect to ask a similar question again, save the prompt.

9.4.3.4. Prompt structure: persona, context, task, constraints, output#

A useful research prompt usually has five parts.

Part	What it does	Example
Persona	Tells the AI what role to play	“You are a research mentor helping an REU student.”
Context	Gives background information	“I am analyzing TESS light curves for possible eclipsing binaries.”
Task	States what you want done	“Summarize the unresolved problems in these logs.”
Constraints	Sets limits or rules	“Use only the uploaded notes. Do not invent missing details.”
Output format	Tells the AI how to organize the answer	“Return a table with columns for problem, evidence, file, and next step.”

A weak prompt is:

Summarize my research.

A stronger prompt is:

You are a research mentor helping an REU student prepare for a weekly meeting. I am analyzing TESS light curves and have uploaded my daily research logs, meeting notes, and project README. Using only those sources, summarize my progress from the past week. Organize the response into completed work, unresolved problems, files created, and questions I should ask my mentor. If something is not supported by the notes, say that it is unclear rather than guessing.

The stronger prompt works better because it defines the role, gives context, states the task, sets boundaries, and specifies the output structure.

9.4.3.5. Prompt iteration#

Prompt engineering is usually an iterative process. The first prompt is rarely the best prompt. You should expect to revise the prompt after seeing the first answer.

A useful workflow is:

Start with persona, context, task, constraints, and output format.
Read the answer critically.
Identify what is missing, vague, too long, too short, or unsupported.
Revise the prompt with a clearer instruction.
Repeat until the output is useful.
Save the final prompt in your prompt log.

For example, suppose the AI gives a summary that is too vague. Do not simply accept it. Add a more precise instruction:

Revise the summary so that every claim is connected to a specific log date or file mentioned in the sources.

If the AI gives a response that is too long, add:

Condense this into a meeting agenda with no more than five main discussion items.

If the AI guesses or fills gaps, add:

Use only the provided logs. If the logs do not say something clearly, write "not specified in the logs."

Important

AI output should be checked against the original notes, code, data, or paper. A confident answer is not the same thing as a verified answer.

9.4.3.6. Rule summarization at the end of an AI session#

When an AI session produces a useful result, end by asking the AI to summarize the rules that made the session work. This turns a one-time conversation into a reusable workflow.

Good end-of-session prompts include:

Summarize the prompt instructions that led to the best output in this session. Write them as a reusable prompt template.

What rules did I give you during this conversation that I should save for future research-log summaries?

Convert the final version of this workflow into a reusable prompt I can paste into a future AI session.

Then copy the result into your prompt log. This is especially useful when you had to correct the AI several times. Instead of repeating the same corrections in every future session, save the corrected instructions as a reusable prompt.

9.4.3.7. Documenting AI use in the research log#

When AI meaningfully affects your research work, record how it was used. This does not mean you need to log every small grammar suggestion, but you should document AI assistance that changes your code, analysis, interpretation, project plan, or written research notes.

A useful AI-use entry should include the tool, the question asked, the useful suggestion, what you checked, what changed, and what concerns remain.

9.4.3.7.1. Example AI-use log entry#

## AI assistance

Tool used:
- ChatGPT

Question asked:
- Why does my matplotlib plot fail when the time and flux arrays have different lengths?

Useful suggestion:
- The AI suggested checking whether I removed NaN values from only one array.

What I checked:
- I printed the lengths of the time and flux arrays.
- The arrays had different lengths.

What I changed:
- I created a single mask and applied it to both arrays.

Result:
- The plot now runs without an array-length error.

Remaining concern:
- I still need to verify that the masking did not remove valid data points.

Final rule for AI use

Use AI to accelerate the work, not to hide the work. Record what you asked, what you used, what you checked, and what changed.

9.5. Choosing the Right Tool for the Job#

9.5.1. Jupyter Notebook or Markdown?#

Use a Jupyter notebook when the log entry needs code, plots, equations, or quick calculations. Use a Markdown file when you are writing notes, recording decisions, summarizing progress, or tracking commands. For many projects, a good setup is daily notes in logs/YYYY-MM-DD.md, exploratory calculations in notebooks/, reusable code in scripts/, and generated plots in figures/. Do not rely on notebook output alone. If a plot or table matters, save it as a file and mention it in the log.

9.5.1.1. When to use a Jupyter notebook#

A notebook is useful when you are actively working with data or code. Use a notebook when you need to test Python commands, make plots, inspect data tables, try calculations, document an analysis step by step, or combine explanation, code, and output in one place.

A notebook should not be only code cells. Add Markdown cells that explain what you are doing and what happened. A good notebook usually has this rhythm: state the goal, load packages and data, run one analysis step, write down what happened, save important outputs, and write the next step.

9.5.1.2. When to use a Markdown file#

A Markdown file is useful for notes that do not need live code. Use a Markdown file when you need to keep a daily research log, summarize a meeting, list tasks, record decisions, write paper notes, document commands, or draft text for a report or poster.

Markdown is plain text, so it works well with GitHub and version control.

9.5.1.3. Linking to a saved figure in Markdown#

A saved figure can be linked inside a Markdown log entry:

![Light curve of TIC 123456789](../figures/2026-05-18_tic123456789_lightcurve.png)

The text inside the square brackets should describe the figure. The path inside the parentheses should point to the saved image file.

9.5.2. Optional Videos and Tutorials#

The sections above are enough to get started, but the resources below give more background if you are new to research logs, Markdown, Jupyter notebooks, or GitHub. You do not need to watch all of these before starting. Use them when you get stuck or when you want a slower walk-through.

9.5.2.1. Research logs and lab notebooks#

These videos focus on the habit of recording research work. Some examples may come from wet-lab science, but the basic ideas also apply to astronomy, physics, coding, simulations, and data analysis.

When watching these, focus on the main habit: write down what you did, when you did it, what happened, and what you should try next.

9.5.2.2. Markdown and Jupyter notebooks#

These resources are useful if you are new to writing formatted notes or working in notebooks.

Markdown is the formatting language used in many research logs, README files, GitHub issues, and Jupyter notebook text cells. Jupyter notebooks also use Markdown cells for explanatory text.

9.5.2.3. GitHub and GitHub Desktop#

These resources are useful if you are new to GitHub. GitHub can be confusing at first because it uses words like repository, commit, branch, push, and pull. You do not need to master everything immediately.

Start with these:

GitHub Skills is not a video, but it is a guided hands-on exercise. That may be more useful than passively watching a video.

9.6. Logging Data and Computational Work#

9.6.1. Data Provenance#

Data provenance means keeping track of where data came from and what happened to it. A data file by itself is not enough. You also need to know where the data came from, when you downloaded or received it, whether it was raw or processed, what processing steps were applied, what version of the file you used, and what assumptions or filters were applied.

A good research log should make the history of a data file clear.

9.6.1.1. Data provenance template#

## Data Provenance

Dataset:
- 

Source:
- 

Date accessed or downloaded:
- 

Original filename:
- 

Local filename:
- 

Local storage location:
- 

Raw or processed:
- 

Processing steps applied:
- 

Software or code used:
- 

Important filters or selection criteria:
- 

Known problems or limitations:
- 

9.6.1.2. Example data provenance entry#

## Data Provenance

Dataset:
- TESS light curve for TIC 123456789, Sector 17

Source:
- MAST archive, accessed through Lightkurve

Date accessed or downloaded:
- 2026-05-18

Original filename:
- downloaded automatically by Lightkurve

Local filename:
- `data/raw/tic123456789_sector17_lc.fits`

Local storage location:
- `data/raw/2026-05-18_tic123456789/`

Raw or processed:
- Raw downloaded light curve product

Processing steps applied:
- Removed NaN values
- Removed flagged data points
- Normalized flux by median flux

Software or code used:
- `notebooks/01_download_tess_lightcurve.ipynb`
- `notebooks/02_clean_tess_lightcurve.ipynb`

Important filters or selection criteria:
- Used Sector 17 only
- Used short-cadence light curve product

Known problems or limitations:
- Several gaps remain in the time series
- Need to verify which quality flags were removed

Rule of thumb

A plot is only as useful as your record of the data used to make it.

9.6.2. Logging Python Work#

When logging Python work, record enough information that you can rerun the analysis later: the notebook or script name, input data file, package or tool used, important parameter values, output file, and a short interpretation of the result. Do not paste an entire long script into the log. Record the important command, function, loop, or setting.

9.6.2.1. What to record when using Python#

A good Python-related log entry should answer these questions: What notebook or script did I run? What data file did I use? What packages did I use? What parameters did I choose? What output did the code create? Did the code run successfully? Did the result make physical or scientific sense? What should I check next?

9.6.2.2. Example: recording package versions#

When a result depends on a Python package, record the package version.

import sys
import numpy as np
import matplotlib
import astropy

print(f"Python version: {sys.version}")
print(f"NumPy version: {np.__version__}")
print(f"Matplotlib version: {matplotlib.__version__}")
print(f"Astropy version: {astropy.__version__}")

This information helps you reproduce the result later, especially if a package changes behavior after an update.

9.6.2.3. Example: saving a figure with a useful filename#

import matplotlib.pyplot as plt
import numpy as np

time = np.linspace(0, 10, 200)
flux = 1.0 + 0.01 * np.sin(2 * np.pi * time / 2.5)

fig, ax = plt.subplots(figsize=(6, 4))
ax.plot(time, flux, ".")
ax.set_xlabel("Time [days]")
ax.set_ylabel("Relative flux")
ax.set_title("Example Light Curve")

fig.savefig("../figures/2026-05-18_example_lightcurve.png", dpi=200, bbox_inches="tight")

In the log entry, record the figure filename and explain what the plot shows.

9.6.2.4. Example log entry for Python work#

## Python analysis notes

Goal:
- Make an initial plot of relative flux versus time.

Code:
- Notebook: `notebooks/02_plot_lightcurve.ipynb`

Input:
- Data file: `data/processed/tic123456789_sector17_cleaned.csv`

Important choices:
- Removed NaN values.
- Plotted time on the x-axis and normalized flux on the y-axis.
- Saved the plot at 200 dpi.

Output:
- Figure: `figures/2026-05-18_tic123456789_sector17_lightcurve.png`

Result:
- The light curve has several gaps.
- There may be a dip near the middle of the time series, but I need to check quality flags before interpreting it.

Next step:
- Inspect the quality column and remake the plot after removing flagged points.

Common mistake

Do not write only “I made a plot.” Record the filename, the data used, and what the plot shows.

9.6.3. Reproducibility Checklist#

A result is reproducible if you or someone else can repeat the work and get the same result, or at least understand why the result changed. For computational work, record enough information to rerun the analysis.

Computational reproducibility checklist

For important results, record the notebook or script used, the input data file, the output file, the important parameter values, the Python version, important package versions, the date the analysis was run, whether random numbers were used, and the random seed, if relevant.

9.6.3.1. Random seeds#

Some simulations or data-analysis procedures use random numbers. If random numbers are used, record the random seed.

Example:

import numpy as np

rng = np.random.default_rng(seed=12345)

Then write in the log:

Random seed used: `12345`

This helps you reproduce the same test later.

9.6.3.2. Saving parameters#

For simulations or repeated analyses, it is often useful to save parameters in one place.

Example:

params = {"target": "TIC 123456789","sector": 17,"remove_nans": True,
          "remove_quality_flags": True,"normalization": "median"}
print(params)

In larger projects, parameters may be saved in a .json, .yaml, or .toml file.

9.7. Logging Specialized Research Work#

9.7.1. Logging Simulation Runs#

For a numerical simulation, the log should contain enough information to rerun the same calculation. This is especially important because simulation results depend on choices that may not be obvious later. Small changes in parameters, timestep, integration time, or initial conditions can change the result. Record the physical system being modeled, the code or notebook used, the initial conditions, important parameter values, the integration time, the timestep or accuracy settings, output files, the main result, and any warnings, crashes, or suspicious behavior.

9.7.1.1. Questions your simulation log should answer#

A useful simulation log should answer these questions: What system did I simulate? What code did I run? What parameters and initial conditions did I use? How long did the simulation run? What output files were created? Did the simulation finish? Did anything unstable, strange, or suspicious happen? What should I run next?

9.7.1.2. Example simulation log entry#

## Simulation Run: Circumbinary stability test

Date: 2026-05-18

Goal:
- Test whether a planet remains stable near the inner edge of the circumbinary stability limit.

Code:
- `scripts/run_rebound_binary_planet.py`

Initial conditions:
- Binary semimajor axis: `a_bin = 1.0 AU`
- Binary eccentricity: `e_bin = 0.2`
- Planet semimajor axis: `a_p = 3.0 AU`
- Planet eccentricity: `e_p = 0.0`
- Planet inclination: `i_p = 0 deg`

Integrator settings:
- Package: REBOUND
- Integrator: WHFast
- Integration time: `1e5 binary periods`
- Output cadence: every `100 binary periods`

Output:
- `data/processed/run_2026-05-18_a3p0_ebin0p2.csv`
- `figures/2026-05-18_semimajor_axis_timeseries.png`

Result:
- The planet survived the full integration.
- The planet semimajor axis oscillated but did not show long-term drift.

Questions:
- Need to test nearby values of `a_p` to estimate the stability boundary.

9.7.1.3. Example parameter table#

For several related simulation runs, a small table is often clearer than a paragraph.

| Run | `e_bin` | `a_p` [AU] | Integration time | Result |
|---|---:|---:|---:|---|
| 1 | 0.2 | 2.8 | `1e5` binary periods | unstable before `1e4` periods |
| 2 | 0.2 | 3.0 | `1e5` binary periods | survived |
| 3 | 0.2 | 3.2 | `1e5` binary periods | survived |

Rule of thumb

If changing a number could change the result, record that number.

9.7.2. Logging Observations#

For telescope observations, the log should make it possible to understand what was requested, what was actually observed, and where the data went. Observation logs are important because observing conditions, timing, instrument settings, and data locations can all matter later.

9.7.2.1. Observation log template#

## Observation Log

Target:
- Name:
- RA:
- Dec:

Observation time:
- Requested window, UTC:
- Actual start/end time, UTC:

Telescope/instrument:
- Telescope:
- Instrument:
- Filter(s):
- Exposure time(s):
- Number of exposures:
- Binning:
- Readout mode:

Conditions:
- Airmass:
- Seeing:
- Moon phase/separation:
- Weather notes:

Data:
- Raw filenames:
- Archive location:
- Local storage location:
- Calibration files:

Notes:
- 

Next steps:
- 

9.7.2.2. Example observation log entry#

## Observation Log

Target:
- Name: TIC 123456789
- RA: 12:34:56
- Dec: +12:34:56

Observation time:
- Requested window, UTC: 2026-05-18 04:00--08:00
- Actual start/end time, UTC: 2026-05-18 04:15--07:50

Telescope/instrument:
- Telescope: Example 0.6 m telescope
- Instrument: CCD imager
- Filter(s): Sloan r'
- Exposure time(s): 60 s
- Number of exposures: 180
- Binning: 2x2
- Readout mode: standard

Conditions:
- Airmass: started near 1.2, ended near 1.8
- Seeing: variable
- Moon phase/separation: check later
- Weather notes: thin clouds near the end of the sequence

Data:
- Raw filenames: `tic123456789_*.fits`
- Archive location: observatory archive
- Local storage location: `data/raw/2026-05-18_tic123456789/`
- Calibration files: bias, dark, and flat frames available

Notes:
- Several images near the end of the sequence may have lower quality due to clouds.

Next steps:
- Inspect image quality.
- Remove bad frames.
- Begin differential photometry.

Warning

Astronomy uses several time systems. Do not simply write “time” without saying what kind of time is being used.

Examples include:

UTC
JD_UTC
MJD_UTC
BJD_TDB
BTJD_TDB

Observation timestamps are often recorded in UTC. Processed space-telescope light curves may use barycentric time systems. Record the time format and time scale used by the data product.

9.7.2.3. Example: converting an observation time with Astropy#

from astropy.time import Time

# Observation time recorded in UTC
t_utc = Time("2026-05-18 04:30:00", scale="utc")

print(f"ISO UTC time: {t_utc.iso}")
print(f"Julian Date UTC: {t_utc.jd}")
print(f"Julian Date TDB: {t_utc.tdb.jd}")

The log should state which time value was used in the analysis.

9.8. Logging Problems, Errors, and False Starts#

Do not erase failed attempts from the log. Failed attempts are part of the research record. Research is not a straight path: you will try things that do not work, misunderstand something, break code, find missing data, and make plots that look wrong. These are not signs that the log has failed. These are exactly the kinds of things the log is supposed to record. Useful details include the exact error message, the file or notebook where the problem happened, the command or code cell that caused it, what you tried, what fixed it, if anything, and what question remains.

9.8.1. Example: code error#

## Problem

While processing FITS images from `2026-05-18 UTC`, my script crashed with a `MemoryError`.

## Cause

I was loading all FITS images into memory at once.

## Attempted fix

Changed the script to process one image at a time.

## Result

The script completed without crashing.

## Next step

Check whether the output images match the earlier test case.

9.8.2. Example: confusing result#

## Problem

The folded light curve shows two dips instead of one.

## Possible causes

- The period may be wrong.
- The object may be an eclipsing binary.
- I may have folded the light curve at half the true period.
- Bad data points may not have been removed.

## What I tried

- Replotted the light curve using the catalog period.
- Replotted using twice the catalog period.
- Checked whether the dips have similar depths.

## Result

Using twice the original period gives one primary dip and one weaker secondary dip.

## Next step

Ask whether this target is more likely an eclipsing binary than a transiting planet candidate.

9.8.3. Example: no data found#

## Problem

I searched for TESS data for TIC 123456789 but did not find any available light curves.

## What I tried

- Searched by TIC ID.
- Searched by coordinates.
- Checked whether the target falls on a TESS sector footprint.

## Result

No light curve products were returned.

## Next step

Ask whether this target should be removed from the sample or whether I should search for full-frame image data instead.

Important

Do not delete confusing or failed attempts just because they did not lead to a final result. A failed attempt can save you or someone else from repeating the same mistake later.

9.9. Syncing, Backing Up, and Version Control#

At the end of a work session, your log should be saved somewhere that will not disappear if your computer fails. Good options include Google Drive for shared folders and Colab notebooks, GitHub for Markdown files, scripts, notebooks, and version history, and institutional storage if your project uses shared research directories. A log that only exists on one computer is not safely backed up.

9.9.1. Using Google Drive or shared cloud storage#

Google Drive is useful when you are working in Google Colab, your mentor shares files through Drive, your group uses shared folders, or you want automatic syncing.

Even when using Drive, keep your folders organized. Do not dump all files into one shared folder.

A reasonable structure might be:

Research Project/
├── logs/
├── notebooks/
├── data/
├── figures/
└── reports/

9.9.2. Using GitHub Without the Command Line#

Many beginning researchers do not know how to use Git from the command line. That is okay. You can still use GitHub through the browser or through GitHub Desktop.

For this guide, the goal is not to become a Git expert. The goal is to keep your research log, notebooks, scripts, and figures backed up in an organized place.

There are three common ways to use GitHub. GitHub in the browser is best for editing Markdown logs, README files, and uploading a few small files. GitHub Desktop is best for working on a project folder on your computer and syncing changes without typing Git commands. Command-line Git is useful later, but it is not required to start keeping a research log.

This course will focus on the first two.

Basic vocabulary

A repository, often called a repo, is a project folder stored on GitHub. A commit is a saved snapshot of your changes. A commit message is a short note explaining what changed. A push sends changes from your computer to GitHub. A pull brings newer changes from GitHub down to your computer.

9.9.3. Option 1: Using GitHub in the Browser#

The browser method is the easiest way to start. Use it when you need to create or edit a simple Markdown log file.

9.9.3.1. Creating a new research log file in the browser#

Go to the GitHub repository for your project.
Open the logs/ folder.
Click Add file.
Choose Create new file.
Name the file using the date.

For example:

logs/2026-05-18.md

Type or paste your research log entry.
Scroll down to the Commit changes section.
Write a short commit message.

For example:

Add research log for 2026-05-18

Click Commit changes.

Your log entry is now saved in the GitHub repository.

9.9.3.2. Editing an existing log file in the browser#

Go to the GitHub repository.
Open the file you want to edit.
Click the pencil icon or Edit this file button.
Make your changes.
Use the Preview tab if you want to check the rendered Markdown.
Scroll down to Commit changes.
Write a short commit message.
Click Commit changes.

Good commit messages are short but specific.

Weak commit messages:

update
changes
stuff

Better commit messages:

Add notes from mentor meeting
Update TESS light curve notes
Fix typo in observation log
Add next steps for simulation runs

9.9.3.3. Uploading small files in the browser#

Use the browser to upload small files such as a Markdown file, a small figure, or a short notebook.

Go to the GitHub repository.
Open the folder where the file should go.
Click Add file.
Choose Upload files.
Drag the file into the browser window, or click choose your files.
Write a commit message.
Click Commit changes.

For example, if you made a figure, upload it to the figures/ folder and use a commit message like:

Add light curve figure for TIC 123456789

Then mention that figure in your research log.

Figure saved as `figures/2026-05-18_tic123456789_lightcurve.png`.

Browser method: best use

Use the browser method for small edits, daily Markdown logs, README files, and a few small uploads.

If you are regularly changing notebooks, scripts, folders, and figures, use GitHub Desktop instead.

9.9.4. Option 2: Using GitHub Desktop#

GitHub Desktop is usually better once you are working with a full project folder on your computer. Use GitHub Desktop when you are editing Jupyter notebooks, Python scripts, multiple log files, figures, small processed data files, or project README files. GitHub Desktop lets you review changes, write a commit message, and sync with GitHub without typing Git commands.

9.9.4.2. Step 2: Clone the project repository#

Cloning means copying the GitHub repository to your computer.

Go to the repository page on GitHub.
Click the green Code button.
Choose Open with GitHub Desktop.
Choose where the project folder should live on your computer.
Click Clone.

After cloning, you will have a normal folder on your computer containing the project files.

9.9.4.3. Step 3: Work in the project folder#

Open the cloned folder on your computer. Then work normally.

For example, you might create a new file in logs/, edit a notebook in notebooks/, save a figure in figures/, or modify a Python script in scripts/. Keep the folder structure organized, and do not save everything to the top-level project folder.

9.9.4.4. Step 4: Review changes in GitHub Desktop#

After you edit files, open GitHub Desktop.

GitHub Desktop will show a list of changed files.

Before committing, look through the changed files, make sure the changes are intentional, and make sure you are not accidentally committing large data files, temporary files, or private information. Files that usually should not be committed include huge raw datasets, passwords, API keys, private notes unrelated to the project, temporary files, and automatically generated cache folders.

9.9.4.5. Step 5: Commit your changes#

In GitHub Desktop:

Write a short summary of the change.
Add a longer description if useful.
Click Commit to main or Commit to [branch name].

Example commit summaries:

Add research log for 2026-05-18
Update light curve plotting notebook
Add cleaned TESS light curve figure
Fix NaN masking in plotting script
Add simulation run summary

A commit should represent one clear unit of work. Do not wait until you have changed twenty unrelated files.

9.9.4.6. Step 6: Push your changes to GitHub#

After committing, click Push origin.

This sends your committed changes from your computer to GitHub.

If you forget to push, the changes are committed on your computer but not yet backed up to GitHub.

Important

A commit saves a snapshot on your computer. A push sends that snapshot to GitHub. For backup purposes, you usually need to do both.

9.9.4.7. Step 7: Pull before starting work#

If you work across multiple computers, or if your mentor or another student may have changed the repository, start each work session by opening GitHub Desktop and clicking Fetch origin or Pull origin.

This brings the newest version from GitHub to your computer.

Good habit

At the start of a work session, pull changes from GitHub. At the end of a work session, commit and push your changes.

9.9.5. When to Use the Browser vs. GitHub Desktop#

Task	Recommended method
Edit a daily Markdown log	Browser or GitHub Desktop
Create a new Markdown note	Browser or GitHub Desktop
Upload one small figure	Browser
Work with notebooks and scripts	GitHub Desktop
Upload several files or folders	GitHub Desktop
Review many changed files before saving	GitHub Desktop
Learn full Git commands	Command line, later

For most new students, a good starting workflow is:

Use the browser for quick Markdown edits.
Use GitHub Desktop for real project work.
Learn command-line Git later if your project requires it.

9.9.6. Using `.gitignore`#

A .gitignore file tells Git which files to ignore.

This is useful because research projects often create temporary files that should not be saved in the repository.

Common examples include:

.ipynb_checkpoints/
__pycache__/
*.pyc
.DS_Store

The .gitignore file should usually be placed in the main project folder.

Example:

research-project/
├── .gitignore
├── README.md
├── logs/
├── notebooks/
├── scripts/
├── data/
└── figures/

You can create or edit .gitignore using either the GitHub browser interface or GitHub Desktop.

9.9.6.1. Creating `.gitignore` in the browser#

Open the repository on GitHub.
Click Add file.
Choose Create new file.
Name the file:

.gitignore

Add ignore rules.
Write a commit message.

For example:

Add .gitignore for Python and Jupyter files

Click Commit changes.

9.9.6.2. Creating `.gitignore` using GitHub Desktop#

Open the project folder on your computer.
Create a new plain-text file named .gitignore.
Add ignore rules.
Save the file.
Open GitHub Desktop.
Commit the new .gitignore file.
Push the commit to GitHub.

Rule of thumb

Use GitHub to save logs, code, notebooks, and small figures.

Do not use GitHub as a dumping ground for huge raw datasets unless your mentor tells you to.

9.10. Tracking Tasks and Ending a Work Session#

9.10.1. Tracking Tasks#

A research log records what happened during a work session. A task list records what still needs to be done. Both are useful, but they are not the same thing.

9.10.1.1. Research log#

Use the research log for what you tried, what happened, what files changed, what results you got, what confused you, and what you learned.

9.10.1.2. Task list#

Use a task list for what needs to be done next, what questions need to be answered, what bugs need to be fixed, what plots need to be remade, what files need to be cleaned up, and what deadlines are approaching.

9.10.1.3. Simple task list template#

# Task List

## To do

- [ ] Inspect quality flags for Sector 17
- [ ] Remake light curve after removing flagged points
- [ ] Compare Sector 17 and Sector 18
- [ ] Ask mentor whether this target should remain in the sample

## In progress

- [ ] Clean Sector 17 light curve

## Done

- [x] Download Sector 17 light curve
- [x] Make first raw light curve plot

9.10.1.4. Using GitHub Issues for tasks#

If your project uses GitHub, you can use GitHub Issues to track tasks.

A useful issue should include a short title, the problem or task, why it matters, what counts as done, and links to relevant files, figures, or logs.

Example issue title:

Inspect quality flags for TIC 123456789 Sector 17

Example issue body:

## Task

Inspect the quality flags for the Sector 17 TESS light curve of TIC 123456789.

## Why this matters

The raw light curve has several gaps and possible bad points. I should not interpret dips before checking whether flagged points are affecting the plot.

## Done when

- [ ] Quality flags have been inspected.
- [ ] A cleaned light curve has been saved.
- [ ] A before/after comparison plot has been made.
- [ ] The research log has been updated with the result.

Rule of thumb

The log explains what happened. The task list reminds you what still needs to happen.

9.10.2. End-of-Day Checklist#

Before you stop working, check that you wrote down what you tried, recorded important filenames, saved important plots or tables, recorded parameter values for simulations or analyses, recorded errors or failed attempts, wrote down what confused you, wrote the next step clearly enough to restart quickly, and backed up or synced the log. If you are using GitHub in the browser, make sure you clicked Commit changes. If you are using GitHub Desktop, make sure you clicked Commit and then Push origin.

A good end-of-day log entry does not need to be beautiful. It needs to prevent you from losing the thread of the project.

Five-minute shutdown routine

At the end of each work session:

Save your notebook or script.
Save any important figures.
Write the result of the work session.
Write the next step.
Sync or back up the files.

9.10.2.1. Example end-of-day entry#

## End-of-day summary

Today I downloaded and plotted the Sector 17 TESS light curve for TIC 123456789. The light curve has several gaps, and I have not yet checked the quality flags. The main output is `figures/2026-05-18_tic123456789_sector17_lightcurve.png`.

Next time I should inspect the quality flags, remove flagged points, and compare the result with Sector 18.

9.11. Common Mistakes and Safety#

9.11.1. Common Mistakes#

New researchers often make the same logging mistakes. Most of these mistakes are easy to avoid if you know what to watch for.

9.11.1.1. Mistake 1: Waiting too long to write the log#

Do not wait several days before writing the log. You will forget details, so write the log during the work session or immediately after it.

9.11.1.2. Mistake 2: Only recording successful results#

Failed attempts belong in the log. If something did not work, record what you tried, what happened, what error message appeared, what you think caused the problem, and what you should try next.

9.11.1.3. Mistake 3: Not recording filenames#

A result is much less useful if you cannot find the file later. Do not write:

Made a plot.

Write:

Made figures/2026-05-18_tic123456789_sector17_lightcurve.png.

9.11.1.4. Mistake 4: Not recording parameter values#

For code and simulations, parameter values matter. Do not write:

Ran the simulation with different settings.

Write:

Ran the simulation with e_bin = 0.2, a_p = 3.0 AU, and integration time 1e5 binary periods.

9.11.1.5. Mistake 5: Not explaining why you made a decision#

Research involves choices. Record the reason for important choices.

For example:

I used Sector 17 instead of Sector 18 because Sector 17 has fewer gaps and better phase coverage.

9.11.1.6. Mistake 6: Treating the log like polished writing#

A research log is not a final report. It is allowed to be rough. The log should be clear, dated, specific, and useful. It does not need to sound elegant.

9.11.1.7. Mistake 7: Not writing the next step#

The next step is what helps you restart.

Do not write:

Continue analysis.

Write:

Remove flagged data points and remake the light curve plot before attempting period analysis.

9.11.2. What Not to Put in the Log#

A research log should be useful, but it should not contain everything. Do not put passwords, API keys, private login information, private student information, private collaborator information, unrelated personal notes, copyrighted files you do not have permission to share, or large raw datasets in a shared research log unless your mentor says they belong there.

When in doubt, ask your mentor before uploading or sharing sensitive files.

Important

Never put passwords, tokens, or API keys in a GitHub repository.

9.12. Turning Logs into Reports, Posters, and Presentations#

A research log is not the final product, but it makes final products easier to create. When it is time to write a report, make a poster, or prepare a talk, your logs can help you find the question you investigated, methods you used, data you analyzed, problems you solved, figures you created, important results, and remaining questions.

9.12.1. How to review your logs before writing#

Before making a report or presentation, skim your logs and mark important results, useful figures, failed attempts that explain your final method, decisions that changed the project, and questions that remain open.

Then make a short summary.

## Project summary from logs

Main research question:
- 

Data or simulations used:
- 

Main methods:
- 

Most important result:
- 

Best figures:
- 

Problems solved:
- 

Questions still open:
- 

Key idea

A good research log turns a final report from a memory test into an editing task.

9.12.2. Final reminder#

A research log does not need to be polished. It needs to be clear, dated, and specific enough that you can continue the work later. Write for your future self. Record what worked, what failed, what files changed, and what you should do next.

A good research log protects the project from lost details. It also helps your mentor understand your progress and give better advice.

The basic rule is simple:

Final rule

If you changed something, record what changed. If something failed, record what failed. If you made a decision, record why. If you created a file, record where it is.

Research Logging

Contents

9. Research Logging#

9.1. Why Research Logs Matter#

9.1.1. What Counts as Research Work?#

9.2. Setting Up a Research Project#

9.2.1. Project Startup Checklist#

9.2.2. Recommended folder structure#

9.2.3. File Naming Conventions#

9.2.4. Project README Files#

9.2.4.1. Simple README template#

9.3. Writing Useful Log Entries#

9.3.1. The Minimum Useful Log Entry#

9.3.1.1. Date#

9.3.1.2. Goal#

9.3.1.3. Actions#

9.3.1.4. Result#

9.3.1.5. Next step#

9.3.2. Daily log template#

9.3.2.1. Example filled entry#

9.3.3. Examples of Weak and Strong Log Entries#

9.3.3.1. Example 1: Downloading data#

9.3.3.2. Example 2: Running code#

9.3.3.3. Example 3: Simulation work#

9.3.3.4. Example 4: Being confused#

9.3.3.5. Example 5: Reading a paper#

9.4. Research Notes Beyond the Daily Log#

9.4.1. Meeting Notes#

9.4.1.1. Meeting notes template#

9.4.1.2. Example meeting notes#

9.4.2. Paper Reading Notes#

9.4.2.1. What to record when reading a paper#

9.4.2.2. Paper notes template#

9.4.2.3. Example paper notes#

9.4.3. Using AI Tools as Part of a Research Workflow#

9.4.3.1. Why good research logs make AI more useful#

9.4.3.2. Using NotebookLM with research logs#

9.4.3.3. Keeping a prompt log#

9.4.3.3.1. Prompt log template#

9.4.3.3.2. Example prompt log entry#

9.4.3.4. Prompt structure: persona, context, task, constraints, output#

9.4.3.5. Prompt iteration#

9.4.3.6. Rule summarization at the end of an AI session#

9.4.3.7. Documenting AI use in the research log#

9.4.3.7.1. Example AI-use log entry#

9.5. Choosing the Right Tool for the Job#

9.5.1. Jupyter Notebook or Markdown?#

9.5.1.1. When to use a Jupyter notebook#

9.5.1.2. When to use a Markdown file#

9.5.1.3. Linking to a saved figure in Markdown#

9.5.2. Optional Videos and Tutorials#

9.5.2.1. Research logs and lab notebooks#

9.5.2.2. Markdown and Jupyter notebooks#

9.5.2.3. GitHub and GitHub Desktop#

9.6. Logging Data and Computational Work#

9.6.1. Data Provenance#

9.6.1.1. Data provenance template#

9.6.1.2. Example data provenance entry#

9.6.2. Logging Python Work#

9.6.2.1. What to record when using Python#

9.6.2.2. Example: recording package versions#

9.6.2.3. Example: saving a figure with a useful filename#

9.6.2.4. Example log entry for Python work#

9.6.3. Reproducibility Checklist#

9.6.3.1. Random seeds#

9.6.3.2. Saving parameters#

9.7. Logging Specialized Research Work#

9.7.1. Logging Simulation Runs#

9.7.1.1. Questions your simulation log should answer#

9.7.1.2. Example simulation log entry#

9.7.1.3. Example parameter table#

9.7.2. Logging Observations#

9.7.2.1. Observation log template#

9.7.2.2. Example observation log entry#

9.7.2.3. Example: converting an observation time with Astropy#

9.8. Logging Problems, Errors, and False Starts#

9.8.1. Example: code error#

9.8.2. Example: confusing result#

9.8.3. Example: no data found#

9.9. Syncing, Backing Up, and Version Control#

9.9.6. Using `.gitignore`#

9.9.6.1. Creating `.gitignore` in the browser#

9.9.6.2. Creating `.gitignore` using GitHub Desktop#