
This project is a practical guide and template for setting up robust and reproducible research projects in machine learning.

The objective is to share good engineering practices acquired through research and development experiences, focusing on environment setup, remote development, experiment tracking, version control, and maintainable code organization.

The template covers essential tools and workflows such as SSH-based development, Git branching strategies, pre-commit hooks, experiment logging, command-line interfaces, testing, and reproducible project structures.

The goal is to move from exploratory code to reliable research software that can be easily maintained, shared, and extended by other researchers.



# Development Workflow

## Remote Development

A significant part of modern machine learning research relies on remote computational resources. This project introduces workflows based on:

- VS Code Remote SSH for developing directly on remote machines.
- SSHFS for accessing remote files as a local filesystem.
- Tmux for maintaining long-running processes on servers.

These tools simplify development on clusters and avoid inefficient workflows based on repeated file transfers.

# Code Quality and Reproducibility

## Github Workflow

Version control is a fundamental component of collaborative research.

The project introduces:

- Branch-based development workflows.
- Pull requests for reviewing changes.
- Clear commit history and collaboration practices.

The objective is to make research code understandable and maintainable by others.

## Pre-commit

Pre-commit hooks help automatically enforce code quality standards before changes are pushed.

They provide an additional safety layer by detecting formatting issues, common mistakes, and inconsistent practices early in the development workflow.

# Experiment Management

## Logging Experiments

Keeping track of experiments is essential in machine learning research.

Using tools such as ClearML or TensorBoard, each experiment can be automatically recorded, including:

- Hyperparameters.
- Metrics.
- Model versions.
- Training curves.

This avoids losing track of previous experiments and makes comparisons easier, especially when writing reports or papers.

## Command Line Interfaces

The project explores different approaches for managing experiment configurations:

- Argument parsing.
- Hydra-based configuration systems.
- Structured command-line interfaces.

The objective is to make experiments reproducible by avoiding hard-coded parameters directly inside scripts.

# Coding Practices

## Project Structure

A key principle is separating reusable code from experimentation scripts.

Instead of placing all logic inside notebooks, the recommended structure is:

- Python modules (`.py`) containing the actual implementation.
- Minimal notebooks only used for visualization, debugging, and quick experiments.

This improves:
- Version control.
- Code readability.
- Reusability.
- Long-term maintenance.

## Why Avoid Large Notebooks?

Although notebooks are useful for teaching and quick prototyping, they introduce several limitations for long-term research projects:

- Difficult version tracking and conflict resolution.
- Possibility of executing cells in inconsistent orders.
- Poor reproducibility of complex experiments.
- Limited maintainability over time.

For these reasons, notebooks should be considered as interactive tools rather than the main structure of a research codebase.

# Conclusion

This project summarizes practical lessons learned while developing machine learning systems and aims to provide a reliable starting point for future research projects.

The main objective is simple: make research code reproducible, understandable, and easy to collaborate on.

Research Project Template, Building Reproducible Machine Learning Projects

This document summarizes the workflow and practical tips I currently follow. Please note that this version is a draft.



# Workflow. 
This section provides an overview of tools and practices aimed at improving reproducibility, experiment tracking, and code reliability in research workflows. Each subsection briefly describes a component of the workflow, its purpose, and recommendations based on practical experience.

## Pre-commit  
Pre-commit is a useful tool for ensuring code standardization in a reproducible manner. I have tested several pre-commit configurations and, for research-oriented projects, I recommend using lightweight hooks such as those described [here](https://github.com/gardiens/research-project-template/blob/main/.pre-commit-config.yaml).  
To set it up, simply run `pre-commit install`. Once installed, the checks will automatically run with each commit.


## Hydra 
When doing more experiments, it is really important to be able to track and backtrack any improvements and changes. Hydra is a python framework that provides a (not) convenient way to create a hierarchical configuration by compisition and override through config files and command lines.  I will ( or should have) created a blogs about it

## TensorBoard / ClearML  
Effective experiment tracking requires a robust logging tool. I have personally used ClearML, which allows monitoring of experiment outcomes. In the future, I plan to systematically store my scripts alongside experiments to facilitate reproducibility and experimentation history. It is really important when writing report and competitions and you can feel the huge difference when you are using it or not.

## Workflows  
Automation workflows (e.g., GitHub Actions) can verify that code executes correctly upon each commit or push. They are especially useful for ensuring reproducibility of installations and validating that tests pass consistently. I recommend combining this with Pytest, although setting up workflows locally can be complex.

## Pytest  
Pytest provides a means to verify the core functionality of your codebase. In deep learning and prototyping contexts, extensive test coverage may not be essential, but testing core scripts such as `main.py` or major functions is beneficial. This ensures peace of mind when collaborating within a team.

## Auto Typer  
This tool has potential, but I do not yet have sufficient experience with it to incorporate it into my current workflow.


## Tips
### Accessing research paper:
If you want to have access to research paper and are in the Paris saclay university, look at [focus](https://upsaclay.focus.universite-paris-saclay.fr/primo-explore/search?sortby=rank&vid=33UDPS_VU1&lang=fr_FR), it can bypass some paywall ( i.e IEE) even thought the institution are not recognised.
\\ 
Otherwise look at [z-lib](https://www.reddit.com/r/zlibrary/wiki/index/access/) and pray.
### Writing the Results Section  
A colleague once recommended a clear structure for writing results:  
" we have **CAUSE** which causes **PROBLEMS**. therefore we or they do **CONTRIBUTION**  and **WHY WE SOLVE IT**"
This framework has significantly improved the clarity of my writing, especially in research papers where structure can make a substantial difference — including my own work.

### Python Notebooks  
Python notebooks have recently gained popularity as a convenient tool for writing and executing code in educational contexts such as labs or tutorials. However, for projects requiring more than one hour of sustained development, notebooks present several critical limitations:

- **Poor version control:** Traditional versioning systems like Git are not well-suited to notebooks. Commits do not clearly show line-by-line code changes, and merge conflicts are difficult to resolve.
- **Non-linear execution:** Notebooks allow cells to be executed in arbitrary order, which undermines reproducibility. It becomes difficult to ensure that the notebook can run from top to bottom without errors.
- **Resource inefficiency:** For memory- or GPU-intensive tasks, Jupyter can be inefficient and place significant load on system resources, making it less suitable for heavy computations.
- **Short lifecycle and poor maintainability:** In practice, notebooks often lack sufficient documentation and structure. Over time, users forget the purpose and logic of the code, leading to repeated, redundant work.

Based on these limitations, I recommend the following workflow:

- Core functions should be defined in `.py` files organized in a standard Python project structure. This promotes clarity, reuse, and traceability of changes through version control.
- The notebook itself should only contain function calls and minimal code for visualization or debugging. It should not serve as the primary implementation file.

In summary, I strongly discourage the use of notebooks as the main development environment. Instead, I advocate for using a proper logging system and structured Python scripts.

Research Project Template, Building Reproducible Machine Learning Projects

Workflow and Tips

My Socials

Mail :

Mail :