| Name | mockflow JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Professional-grade financial time series mock data generation |
| upload_time | 2025-08-20 12:26:00 |
| maintainer | None |
| docs_url | None |
| author | Conflux ML Engine Team |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MockFlow
Professional-grade Python package for generating realistic financial time series data for backtesting, simulation, and development purposes.
## Features
- **Realistic Market Patterns**: Generate bull, bear, and sideways market scenarios
- **Advanced Volatility Modeling**: GARCH-like volatility clustering with regime switching
- **Volume Correlation**: Realistic volume patterns correlated with price movements
- **Seed-based Reproducibility**: Deterministic generation for consistent testing
- **Multiple Timeframes**: Support for 15m to 1w timeframes
- **OHLCV Data**: Complete OHLC + Volume data generation
## Installation
```bash
pip install mockflow
```
For development:
```bash
pip install mockflow[dev]
```
## Quick Start
```python
from mockflow import generate_mock_data
# Generate 30 days of hourly mock data
data = generate_mock_data(
symbol="BTCUSDT",
timeframe="1h",
days=30,
scenario="auto" # auto-select bull/bear/sideways
)
print(data.head())
```
## API Reference
### Main Function: `generate_mock_data()`
```python
def generate_mock_data(
symbol: str,
timeframe: str,
days: Optional[int] = None,
start_date: Optional[datetime] = None,
end_date: Optional[datetime] = None,
limit: Optional[int] = None,
scenario: str = "auto"
) -> pd.DataFrame
```
**Parameters:**
- **`symbol`** (str): Trading pair symbol (e.g., "BTCUSDT", "ETHUSD")
- **`timeframe`** (str): Candle timeframe. Supported values:
- `"15m"`, `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"6h"`, `"8h"`, `"12h"`, `"1d"`, `"3d"`, `"1w"`
- **`days`** (int, optional): Number of days to generate. Alternative to date range.
- **`start_date`** (datetime, optional): Start date for generation. Used with `end_date`.
- **`end_date`** (datetime, optional): End date for generation. Used with `start_date`.
- **`limit`** (int, optional): Exact number of candles to generate.
- **`scenario`** (str): Market scenario. Options:
- `"auto"`: Automatically select scenario based on symbol/timeframe
- `"bull"`: Sustained upward trend with pullbacks
- `"bear"`: Sustained downward trend with rallies
- `"sideways"`: Range-bound movement with cyclical patterns
**Returns:**
- `pd.DataFrame`: OHLCV data with datetime index
**Raises:**
- `ValueError`: Invalid parameters or unsupported timeframe
- `TypeError`: Incorrect parameter types
## Usage Examples
### Basic Generation
```python
import mockflow
# Generate data with specific scenario
data = mockflow.generate_mock_data(
symbol="ETHUSD",
timeframe="4h",
days=90,
scenario="bull" # "bull", "bear", "sideways", "auto"
)
```
### Date Range Generation
```python
from datetime import datetime
data = mockflow.generate_mock_data(
symbol="BTCUSDT",
timeframe="1d",
start_date=datetime(2024, 1, 1),
end_date=datetime(2024, 3, 31)
)
```
### With Custom Limit
```python
data = mockflow.generate_mock_data(
symbol="SOLUSD",
timeframe="15m",
limit=1000 # Generate exactly 1000 candles
)
```
### Seed-based Reproducibility
```python
import numpy as np
# Set seed for reproducible data
np.random.seed(42)
data1 = mockflow.generate_mock_data("BTCUSDT", "1h", days=7)
np.random.seed(42)
data2 = mockflow.generate_mock_data("BTCUSDT", "1h", days=7)
# data1 and data2 are identical
assert data1.equals(data2)
```
## Output Format
Returns a pandas DataFrame with:
- **Index**: Datetime timestamps
- **Columns**: `open`, `high`, `low`, `close`, `volume`
- **Data Types**: Float64 for OHLC, Int64 for volume
## Market Scenarios
- **Bull Market**: Sustained upward trend with occasional pullbacks
- **Bear Market**: Sustained downward trend with occasional rallies
- **Sideways Market**: Range-bound movement with cyclical patterns
- **Auto**: Automatically selects scenario based on symbol/timeframe
## Advanced Features
### Volatility Clustering
The package implements GARCH-like volatility clustering where:
- High volatility periods tend to be followed by high volatility
- Low volatility periods tend to be followed by low volatility
- Realistic intrabar movement with proper OHLC relationships
### Volume Patterns
Volume generation includes:
- Correlation with price volatility (higher volume during volatile periods)
- Correlation with price changes (higher volume on large moves)
- Cyclical volume patterns
- Random variation within realistic bounds
## Use Cases
### Backtesting Strategy Development
```python
import mockflow
import pandas as pd
# Generate test data for strategy backtesting
def create_backtest_dataset():
# Multiple market conditions for robust testing
bull_data = mockflow.generate_mock_data("BTCUSDT", "4h", days=180, scenario="bull")
bear_data = mockflow.generate_mock_data("BTCUSDT", "4h", days=180, scenario="bear")
sideways_data = mockflow.generate_mock_data("BTCUSDT", "4h", days=180, scenario="sideways")
# Combine for comprehensive testing
full_dataset = pd.concat([bull_data, bear_data, sideways_data], ignore_index=True)
return full_dataset
# Test your strategy
data = create_backtest_dataset()
print(f"Generated {len(data)} candles for backtesting")
```
### Multi-Asset Portfolio Testing
```python
# Create correlated assets for portfolio testing
symbols = ["BTCUSDT", "ETHUSD", "ADAUSDT", "DOTUSD"]
portfolio_data = {}
for symbol in symbols:
portfolio_data[symbol] = mockflow.generate_mock_data(
symbol=symbol,
timeframe="1d",
days=365,
scenario="auto"
)
print("Portfolio datasets ready for analysis")
```
### Data Validation
```python
# Validate generated data quality
def validate_ohlcv_data(data):
"""Validate OHLCV data structure and relationships"""
assert all(data['high'] >= data['low']), "High must be >= Low"
assert all(data['high'] >= data['open']), "High must be >= Open"
assert all(data['high'] >= data['close']), "High must be >= Close"
assert all(data['low'] <= data['open']), "Low must be <= Open"
assert all(data['low'] <= data['close']), "Low must be <= Close"
assert all(data['volume'] > 0), "Volume must be positive"
print("Data validation passed")
# Test data quality
test_data = mockflow.generate_mock_data("BTCUSDT", "1h", limit=100)
validate_ohlcv_data(test_data)
```
### Performance Benchmarking
```python
import time
# Benchmark generation performance
def benchmark_generation():
start_time = time.time()
large_dataset = mockflow.generate_mock_data(
symbol="BTCUSDT",
timeframe="1h",
limit=10000 # 10k candles
)
end_time = time.time()
generation_time = end_time - start_time
print(f"Generated {len(large_dataset)} candles in {generation_time:.2f}s")
print(f"Rate: {len(large_dataset)/generation_time:.0f} candles/second")
benchmark_generation()
```
## Requirements
- Python 3.8+
- numpy >= 1.20.0
- pandas >= 1.3.0
## Development
### Installation
```bash
git clone <repository-url>
cd mockflow
pip install -e .[dev]
```
### Testing
```bash
# Run all tests
pytest
# Run tests with coverage
pytest --cov=mockflow --cov-report=html
# Run specific test categories
pytest -m contract # API contract tests
pytest -m integration # Integration tests
```
### Code Quality
```bash
# Linting
ruff check .
# Type checking
mypy .
# Code formatting
black .
```
### Package Building
```bash
# Build distribution packages
python -m build
# Check package metadata
twine check dist/*
```
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Make changes and add tests
4. Ensure tests pass: `pytest`
5. Check code quality: `ruff check . && mypy .`
6. Submit pull request
## Support
For issues and questions, please use the GitHub issue tracker.
Raw data
{
"_id": null,
"home_page": null,
"name": "mockflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Conflux ML Engine Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cf/3f/fce9d3c149ab3aac6bbe9e2c64f1414a7172ca34dfaef16a8931fd6231b0/mockflow-0.1.0.tar.gz",
"platform": null,
"description": "# MockFlow\n\nProfessional-grade Python package for generating realistic financial time series data for backtesting, simulation, and development purposes.\n\n## Features\n\n- **Realistic Market Patterns**: Generate bull, bear, and sideways market scenarios\n- **Advanced Volatility Modeling**: GARCH-like volatility clustering with regime switching\n- **Volume Correlation**: Realistic volume patterns correlated with price movements\n- **Seed-based Reproducibility**: Deterministic generation for consistent testing\n- **Multiple Timeframes**: Support for 15m to 1w timeframes\n- **OHLCV Data**: Complete OHLC + Volume data generation\n\n## Installation\n\n```bash\npip install mockflow\n```\n\nFor development:\n```bash\npip install mockflow[dev]\n```\n\n## Quick Start\n\n```python\nfrom mockflow import generate_mock_data\n\n# Generate 30 days of hourly mock data\ndata = generate_mock_data(\n symbol=\"BTCUSDT\",\n timeframe=\"1h\", \n days=30,\n scenario=\"auto\" # auto-select bull/bear/sideways\n)\n\nprint(data.head())\n```\n\n## API Reference\n\n### Main Function: `generate_mock_data()`\n\n```python\ndef generate_mock_data(\n symbol: str,\n timeframe: str,\n days: Optional[int] = None,\n start_date: Optional[datetime] = None,\n end_date: Optional[datetime] = None,\n limit: Optional[int] = None,\n scenario: str = \"auto\"\n) -> pd.DataFrame\n```\n\n**Parameters:**\n\n- **`symbol`** (str): Trading pair symbol (e.g., \"BTCUSDT\", \"ETHUSD\")\n- **`timeframe`** (str): Candle timeframe. Supported values:\n - `\"15m\"`, `\"30m\"`, `\"1h\"`, `\"2h\"`, `\"4h\"`, `\"6h\"`, `\"8h\"`, `\"12h\"`, `\"1d\"`, `\"3d\"`, `\"1w\"`\n- **`days`** (int, optional): Number of days to generate. Alternative to date range.\n- **`start_date`** (datetime, optional): Start date for generation. Used with `end_date`.\n- **`end_date`** (datetime, optional): End date for generation. Used with `start_date`.\n- **`limit`** (int, optional): Exact number of candles to generate.\n- **`scenario`** (str): Market scenario. Options:\n - `\"auto\"`: Automatically select scenario based on symbol/timeframe\n - `\"bull\"`: Sustained upward trend with pullbacks\n - `\"bear\"`: Sustained downward trend with rallies\n - `\"sideways\"`: Range-bound movement with cyclical patterns\n\n**Returns:**\n- `pd.DataFrame`: OHLCV data with datetime index\n\n**Raises:**\n- `ValueError`: Invalid parameters or unsupported timeframe\n- `TypeError`: Incorrect parameter types\n\n## Usage Examples\n\n### Basic Generation\n\n```python\nimport mockflow\n\n# Generate data with specific scenario\ndata = mockflow.generate_mock_data(\n symbol=\"ETHUSD\",\n timeframe=\"4h\",\n days=90,\n scenario=\"bull\" # \"bull\", \"bear\", \"sideways\", \"auto\"\n)\n```\n\n### Date Range Generation\n\n```python\nfrom datetime import datetime\n\ndata = mockflow.generate_mock_data(\n symbol=\"BTCUSDT\",\n timeframe=\"1d\",\n start_date=datetime(2024, 1, 1),\n end_date=datetime(2024, 3, 31)\n)\n```\n\n### With Custom Limit\n\n```python\ndata = mockflow.generate_mock_data(\n symbol=\"SOLUSD\",\n timeframe=\"15m\",\n limit=1000 # Generate exactly 1000 candles\n)\n```\n\n### Seed-based Reproducibility\n\n```python\nimport numpy as np\n\n# Set seed for reproducible data\nnp.random.seed(42)\ndata1 = mockflow.generate_mock_data(\"BTCUSDT\", \"1h\", days=7)\n\nnp.random.seed(42) \ndata2 = mockflow.generate_mock_data(\"BTCUSDT\", \"1h\", days=7)\n\n# data1 and data2 are identical\nassert data1.equals(data2)\n```\n\n## Output Format\n\nReturns a pandas DataFrame with:\n- **Index**: Datetime timestamps\n- **Columns**: `open`, `high`, `low`, `close`, `volume`\n- **Data Types**: Float64 for OHLC, Int64 for volume\n\n## Market Scenarios\n\n- **Bull Market**: Sustained upward trend with occasional pullbacks\n- **Bear Market**: Sustained downward trend with occasional rallies \n- **Sideways Market**: Range-bound movement with cyclical patterns\n- **Auto**: Automatically selects scenario based on symbol/timeframe\n\n## Advanced Features\n\n### Volatility Clustering\n\nThe package implements GARCH-like volatility clustering where:\n- High volatility periods tend to be followed by high volatility\n- Low volatility periods tend to be followed by low volatility\n- Realistic intrabar movement with proper OHLC relationships\n\n### Volume Patterns\n\nVolume generation includes:\n- Correlation with price volatility (higher volume during volatile periods)\n- Correlation with price changes (higher volume on large moves)\n- Cyclical volume patterns\n- Random variation within realistic bounds\n\n## Use Cases\n\n### Backtesting Strategy Development\n\n```python\nimport mockflow\nimport pandas as pd\n\n# Generate test data for strategy backtesting\ndef create_backtest_dataset():\n # Multiple market conditions for robust testing\n bull_data = mockflow.generate_mock_data(\"BTCUSDT\", \"4h\", days=180, scenario=\"bull\")\n bear_data = mockflow.generate_mock_data(\"BTCUSDT\", \"4h\", days=180, scenario=\"bear\")\n sideways_data = mockflow.generate_mock_data(\"BTCUSDT\", \"4h\", days=180, scenario=\"sideways\")\n \n # Combine for comprehensive testing\n full_dataset = pd.concat([bull_data, bear_data, sideways_data], ignore_index=True)\n return full_dataset\n\n# Test your strategy\ndata = create_backtest_dataset()\nprint(f\"Generated {len(data)} candles for backtesting\")\n```\n\n### Multi-Asset Portfolio Testing\n\n```python\n# Create correlated assets for portfolio testing\nsymbols = [\"BTCUSDT\", \"ETHUSD\", \"ADAUSDT\", \"DOTUSD\"]\nportfolio_data = {}\n\nfor symbol in symbols:\n portfolio_data[symbol] = mockflow.generate_mock_data(\n symbol=symbol,\n timeframe=\"1d\",\n days=365,\n scenario=\"auto\"\n )\n\nprint(\"Portfolio datasets ready for analysis\")\n```\n\n### Data Validation\n\n```python\n# Validate generated data quality\ndef validate_ohlcv_data(data):\n \"\"\"Validate OHLCV data structure and relationships\"\"\"\n assert all(data['high'] >= data['low']), \"High must be >= Low\"\n assert all(data['high'] >= data['open']), \"High must be >= Open\"\n assert all(data['high'] >= data['close']), \"High must be >= Close\"\n assert all(data['low'] <= data['open']), \"Low must be <= Open\"\n assert all(data['low'] <= data['close']), \"Low must be <= Close\"\n assert all(data['volume'] > 0), \"Volume must be positive\"\n print(\"Data validation passed\")\n\n# Test data quality\ntest_data = mockflow.generate_mock_data(\"BTCUSDT\", \"1h\", limit=100)\nvalidate_ohlcv_data(test_data)\n```\n\n### Performance Benchmarking\n\n```python\nimport time\n\n# Benchmark generation performance\ndef benchmark_generation():\n start_time = time.time()\n \n large_dataset = mockflow.generate_mock_data(\n symbol=\"BTCUSDT\",\n timeframe=\"1h\",\n limit=10000 # 10k candles\n )\n \n end_time = time.time()\n generation_time = end_time - start_time\n \n print(f\"Generated {len(large_dataset)} candles in {generation_time:.2f}s\")\n print(f\"Rate: {len(large_dataset)/generation_time:.0f} candles/second\")\n\nbenchmark_generation()\n```\n\n## Requirements\n\n- Python 3.8+\n- numpy >= 1.20.0\n- pandas >= 1.3.0\n\n## Development\n\n### Installation\n\n```bash\ngit clone <repository-url>\ncd mockflow\npip install -e .[dev]\n```\n\n### Testing\n\n```bash\n# Run all tests\npytest\n\n# Run tests with coverage\npytest --cov=mockflow --cov-report=html\n\n# Run specific test categories\npytest -m contract # API contract tests\npytest -m integration # Integration tests\n```\n\n### Code Quality\n\n```bash\n# Linting\nruff check .\n\n# Type checking\nmypy .\n\n# Code formatting\nblack .\n```\n\n### Package Building\n\n```bash\n# Build distribution packages\npython -m build\n\n# Check package metadata\ntwine check dist/*\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/new-feature`\n3. Make changes and add tests\n4. Ensure tests pass: `pytest`\n5. Check code quality: `ruff check . && mypy .`\n6. Submit pull request\n\n## Support\n\nFor issues and questions, please use the GitHub issue tracker.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional-grade financial time series mock data generation",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/stefan-mcf/conflux-ml-engine",
"Issues": "https://github.com/stefan-mcf/conflux-ml-engine/issues",
"Repository": "https://github.com/stefan-mcf/conflux-ml-engine"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fbcddf41ef85f4f6e111e2c394163b6fce579cefdead82aed355c58aada6c832",
"md5": "cd1ad57d4a9d3186201c3ab8dbf85de1",
"sha256": "31a34f95387bfbac3d86314811e37cfb66566a3041def21aa9e589d839720f2e"
},
"downloads": -1,
"filename": "mockflow-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cd1ad57d4a9d3186201c3ab8dbf85de1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10744,
"upload_time": "2025-08-20T12:25:59",
"upload_time_iso_8601": "2025-08-20T12:25:59.530909Z",
"url": "https://files.pythonhosted.org/packages/fb/cd/df41ef85f4f6e111e2c394163b6fce579cefdead82aed355c58aada6c832/mockflow-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf3ffce9d3c149ab3aac6bbe9e2c64f1414a7172ca34dfaef16a8931fd6231b0",
"md5": "2b9094daff5193c28ed874579a6999f0",
"sha256": "21903dbe2b90e477a25838b6eeb954757e422c75adf1a0f9607809e259010517"
},
"downloads": -1,
"filename": "mockflow-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2b9094daff5193c28ed874579a6999f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10249,
"upload_time": "2025-08-20T12:26:00",
"upload_time_iso_8601": "2025-08-20T12:26:00.735660Z",
"url": "https://files.pythonhosted.org/packages/cf/3f/fce9d3c149ab3aac6bbe9e2c64f1414a7172ca34dfaef16a8931fd6231b0/mockflow-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 12:26:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stefan-mcf",
"github_project": "conflux-ml-engine",
"github_not_found": true,
"lcname": "mockflow"
}
