Handbook
Gradient Handbook / Product Team / Coding / Coding Standards / File Saving Rules Edit this page

File Saving Rules

Project files in a Repository

Our projects all follow the same structure as explained in Coding at Gradient
Never use any of the following Unicode characters in your file names:

  • < (less than)
  • > (greater than)
  • : (colon)
  • " (double quote)
  • / (forward slash)
  • \ (backslash)
  • | (vertical bar or pipe)
  • ? (question mark)
  • * (asterisk)
  • . (dot)

R

This is where our scripts live. All names should be meaningful and follow a logical pattern. Often, we chain our scripts or have a particular order in the scripts, which is why we follow the convention of including padded numbers in front of file names.

Proper formatting:

R Script File Naming Protocol

  • 000_libraries.Rmd
  • 100_read_data.Rmd
  • 110_prepare_data.Rmd
  • 201_plots_clv.Rmd
  • 202_estimate_regularity_clv.Rmd
  • 300_syhtesis.Rmd

For naming objects and functions inside each script, we have a separate guide, which closely follows the Tidyverse style guide.

Data

Data comes in many storing forms. Which is why we should keep the naming the same.

  • Client(.spss, .xlsx, .csv etc.)
    • Should never be altered, only read and saved to other files.
    • Keep the name meaningful and add client_ before the name. E.g “client_customer_transactional_history.csv”
  • Gradient (.csv, .rda, .rds, etc.)
    • Include date of creation of the file name in ISO format (YYYY-MM-DD).
    • Give meaningful names!
    • Save R Objects as defined below!

R Objects

Sometimes, we will have to save R objects to continue our workflow. For example, running a Random Forest model might take a few hours, and we’d like to save the model for future use. Or we have an extremely large CSV file we do not want to read every time we work on the project. If this is the case, follow the protocol:

  • Use aws.s3::s3saveRDS(x, object = 'data/YYYY-MM-DD_name.rds', bucket = 'monorepo-data/project_code') function to save your objects on AWS.
  • Include date of creation of the file name ISO format (YYYY-MM-DD).
  • Give meaningful names
  • Extent the name with the type. E.g. "2018-05-29_customer_prediction_data.csv" or “2018-05-29_customer_survival_model.rds"
  • Only save intermediate files if absolutely necessary! Directories and data become messy if we save too much

AWS repository File Structure Protocol

On AWS S3 you can find the monorepo-data bucket responsible for the storage of all our data and results. Each project contains below folders. Use sub-folders if necessary (e.g. .pdf format in “plots” folder and include an “plots/images” folder with .png files.

  • Models
    • 2018-05-29_clv_bayesian_model.rds
    • 2018-05-27_clv_bayesian_model.rds
    • 2018-05-29_random_forest_model.rds
    • 2018-05-29_gradient_boosting_model.rds
  • Data
    • Client
    • Gradient
      • 2018-07-03_customer_transaction_data.rds
      • 2018-07-03_product_meta_data.rds
  • Results
    • 2021-01-21_segment_assignments.csv
    • 2021-01-21_clv_bayesian_model_customer_predictions.csv
    • 2018-05-29_final_client_report.html
    • 2018-05-29_final_client_report.rmd
  • Plots
    • 2018-05-29_01_customer_plot.pdf
    • 2018-05-27_01_customer_plot.pdf
    • 2018-05-25_01_customer_plot.pdf
    • 2018-05-29_02_retention_plot.pdf
    • Images
      • 2018-05-29_01_customer_plot.png
      • 2018-05-29_01_retention_plot.png