AI, machine learning and deep learning · Introductory

Write a Clear Methods Section

Written by SignalsLab

Early edition: these lessons are being reviewed.

Content

Summary

A methods section must provide sufficient detail, including specific function names and nondefault parameters, to allow other researchers to replicate scientific procedures. Making analysis code or data freely available benefits the scientific community, increases research visibility through citations, and motivates the author to write error-free code.

Intuition

Think of the methods section as a recipe. If you leave out ingredients or vague instructions like 'cook until done,' no one can replicate your dish. Similarly, in machine learning, if you don't specify which toolbox functions you used or what nondefault parameters were set, replication is impossible. Sharing your code is not just about transparency; it creates a feedback loop where the knowledge that others might inspect your work encourages you to write cleaner, better-commented code from the start. This practice also boosts your citation count, as users of your code will reference your work.

Derivation

  1. Replication is the cornerstone of scientific validity.
  2. Vague methods sections prevent replication.
  3. Therefore, methods must include specific function names and nondefault parameters.
  4. Sharing code allows others to learn and use the work, benefiting the community.
  5. Using code leads to citations, increasing research visibility.
  6. Public availability motivates the author to write error-free, well-commented code.
  7. Authors should attempt to replicate their own findings in subsequent experiments.

Worked example

Problem

A researcher writes a methods section stating: 'We used a neural network to classify images.' They do not specify the library, the architecture, or the learning rate. Another researcher tries to replicate this but fails. What went wrong and how should the code be shared?

  1. Identify that the methods section is too vague.
  2. Note that specific function names and nondefault parameters (like learning rate) are missing.
  3. Conclude that replication failed due to insufficient detail.
  4. Recommend uploading code to a platform like GitHub or a lab website instead of just offering it 'upon request'.

Answer The methods section lacked sufficient detail (function names, parameters), preventing replication. The code should be made freely available via GitHub or a lab website to benefit the community and increase citations.

Common mistakes

  • Writing methods sections that are too vague, preventing other researchers from replicating exact procedures.
  • Using insufficient space as an excuse for omitting details, despite journals allowing supplemental online sections.
  • Relying on the 'code available upon request' method, which is considered the least preferred option for sharing code.

Animation

Animation coming soon

The animated version of this lesson is being prepared for the web. In the Signals AI app, lessons are drawn step by step.

Code

This is a text lesson: it has no animation code yet.

ccBYNC© 2026 SignalsLab. Lesson text shared as is under CC BY-NC 4.0.