A powerful and flexible project template for data analytics and machine learning workflows.

Omni-Grid provides a well-structured, git-integrated environment that accelerates data science projects from exploration to production. Built for Visual Studio Code but compatible with any IDE, it combines industry best practices with modern tooling to streamline your analytics workflow.

• 🚀 Quick Start: Get from zero to analysis in minutes with pre-configured templates
• 📁 Organized Structure: Clean, scalable project organization that grows with your needs
• 🔄 Modular Design: Easy-to-use module generator for creating isolated analysis environments
• 🤖 AI-Ready: Built-in support for AI-powered analysis and insights
• 🔧 Developer Friendly: Integrated with VSCode tasks, git workflows, and best practices
• 📊 Full Stack: Includes all essential data science libraries pre-configured

• Jupyter Notebook Integration - Rich, interactive data analysis environment
• Essential Libraries Pre-configured
  • pandas - Data manipulation and analysis
  • matplotlib & seaborn - Visualization
  • numpy - Numerical computing
• Smart Data Management - Automatic .gitignore for data directories
• Module Finder System - Seamless code sharing across analysis modules
• Template Generation - One-command module scaffolding via VSCode tasks
• Utility Functions - Pre-built helpers for common operations
• AI Analysis Integration - Framework for incorporating AI insights (see AI_ANALYSIS_GUIDE.md)
• Clean Git Workflow - Pre-configured .gitignore for Python projects

• Prerequisites
• Quick Start
• Project Structure
• Creating New Analysis Modules
• Usage Examples
• Documentation
• Contributing
• License
• Acknowledgments

Before you begin, ensure you have the following installed:

• Python 3.9+ - Download here
• Conda (recommended) - Installation instructions
• Visual Studio Code (optional, but recommended) - Download here
• Git - Download here

1. Clone the repository

   git clone https://github.com/GizzZmo/Omni-Grid.git
   cd Omni-Grid

2. Set up your Python environment

   Option A: Using Conda (Recommended)

   conda create -n omni-grid python=3.9
   conda activate omni-grid

   Option B: Using venv

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install required packages

   pip install jupyter pandas numpy matplotlib seaborn

4. Launch Jupyter Notebook

   jupyter notebook

5. Try the example

   • Navigate to src/example/
   • Unzip data/archive.zip if you want to use the sample dataset
   • Open and run main.ipynb

6. Start your analysis! 🎉

   • Create a new module (see below)
   • Add your data to the module's data/ directory
   • Begin analyzing!

💡 Tip: For the best experience, open this project in Visual Studio Code to access integrated tasks and features.

Omni-Grid/
├── .git/                      # Git repository
├── .gitignore                 # Git ignore rules (includes data directories)
├── .templates/                # Module templates
│   └── module/                # Default analysis module template
│       ├── __module_finder__.py
│       ├── data/              # Template data directory (git-ignored)
│       └── main.ipynb         # Template notebook
├── .vscode/                   # VSCode configuration
│   ├── settings.json          # Editor settings
│   └── tasks.json             # Custom tasks (module generation)
├── src/                       # Source code and analysis modules
│   ├── example/               # Example analysis module
│   │   ├── .gitignore         # Module-specific git rules
│   │   ├── __module_finder__.py  # Module path configuration
│   │   ├── data/              # Example datasets (git-ignored)
│   │   │   ├── Churn_Modelling.csv
│   │   │   └── archive.zip
│   │   ├── main.ipynb         # Main analysis notebook
│   │   └── ai_analysis_demo.ipynb  # AI analysis demonstration
│   └── utils/                 # Shared utility functions
│       ├── __init__.py
│       └── display.py         # Display helper functions
├── AI_ANALYSIS_GUIDE.md       # Guide for AI-powered analysis
├── LICENSE                    # Apache 2.0 License
└── README.md                  # This file

• .templates/: Contains reusable templates for generating new analysis modules
• src/: Your workspace for all analysis code
  • Each subdirectory (except utils/) represents an independent analysis module
  • Modules are isolated but can share utilities
• src/utils/: Shared utilities accessible to all modules via __module_finder__.py
• data/: Every module has its own data/ directory that's automatically git-ignored

Omni-Grid makes it incredibly easy to create new, isolated analysis environments.

1. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux)
2. Type and select: Tasks: Run Task
3. Select: Template: Generate Analysis Module
4. Enter your module name (e.g., sales_analysis)
5. A new module is created at src/your_module_name/

cp -r .templates/module src/your_module_name
cd src/your_module_name
# Add your data to the data/ directory
# Open main.ipynb and start analyzing

Each new module includes:

• 📓 main.ipynb: Pre-configured Jupyter notebook with imports and settings
• 📂 data/: Directory for your datasets (automatically git-ignored)
• 🔍 __module_finder__.py: Enables importing from src/utils/

import pandas as pd
import __module_finder__  # Import this first to enable utils access
from utils.display import printdf
import matplotlib.pyplot as plt
import numpy as np

# Load your data
data = pd.read_csv('data/your_dataset.csv')

# Display with enhanced formatting
printdf(data.head())

# Create visualizations
plt.figure(figsize=(10, 6))
data['column_name'].hist()
plt.title('Distribution Analysis')
plt.show()

The utils/display.py module provides convenient display functions:

from utils.display import printdf, printsf

# Display DataFrame with nice HTML formatting
printdf(dataframe)

# Display Series as a formatted DataFrame
printsf(series)

1. Add new functions to src/utils/
2. Import them in any module using __module_finder__:

   import __module_finder__
   from utils.your_module import your_function

For more detailed information, check out these guides:

• AI Analysis Integration Guide - Learn how to integrate AI-powered insights
• Installation Guide - Detailed setup instructions
• Usage Guide - In-depth usage examples
• Architecture Guide - Technical architecture details
• API Reference - Utility functions reference

We welcome contributions! Whether it's:

• 🐛 Bug reports
• ✨ Feature requests
• 📖 Documentation improvements
• 🔧 Code contributions

Please feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For detailed contribution guidelines, see CONTRIBUTING.md.

Issue: Module not found errors

ModuleNotFoundError: No module named 'utils'

Solution: Make sure you import __module_finder__ before importing from utils:

import __module_finder__  # This must come first
from utils.display import printdf

Issue: Jupyter kernel not found

Kernel Error: No kernel found

Solution: Install ipykernel in your environment:

conda activate omni-grid
conda install ipykernel
python -m ipykernel install --user --name omni-grid

Issue: Data directory not ignored by git

git status shows files in data/

Solution: The .gitignore is configured to ignore **/data/*. Make sure your data is in a data/ subdirectory.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright (C) 2022 JANISHAR ALI ANWAR

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

• Original template created by Janishar Ali Anwar
• Maintained by the GizzZmo team
• Built with ❤️ for the data science community

Find this project useful? ⭐ Star it on GitHub!

• 💬 Open an Issue for questions or suggestions
• 🐛 Report a Bug
• 💡 Request a Feature

Happy Analyzing! 🚀📊