py-stats

A pure-Python module providing comprehensive statistics functions similar to those found on scientific calculators. This package offers over 60 statistics functions for both univariate and multivariate analysis.

Educational Focus: Perfect for learning statistics, programming, and data science with clear mathematical implementations and comprehensive examples.

📊 Project Status

✅ Complete and Ready for Use

• Version: 2.0.0
• Functions: 60+ statistical functions implemented
• Testing: 100% test coverage with comprehensive unit tests
• Documentation: Complete with examples and mathematical formulas
• Educational Value: High-quality learning resource
• License: MIT License (permissive and open)
• Repository: GitHub

🚀 Quick Links

• 📦 PyPI Package: python-stats on PyPI
• 🐙 GitHub Repository: RanaEhtashamAli/py-stats
• 📖 Documentation: README
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

📋 Table of Contents

• Project Status
• Quick Links
• Features
• Installation
• Quick Start
• Documentation
• Package Structure
• Requirements
• Testing
• Performance Notes
• Educational Focus
• License
• Contributing
• Acknowledgments
• Support

Features

Univariate Statistics

• Means: arithmetic, harmonic, geometric, and quadratic means
• Central Tendency: median, mode, midrange, trimean
• Angular Statistics: mean of angular quantities
• Averages: running and weighted averages
• Quantiles: quartiles, hinges, and quantiles
• Dispersion: variance and standard deviation (sample and population)
• Deviation Measures: average deviation and median average deviation (MAD)
• Shape: skewness and kurtosis
• Error: standard error of the mean
• Robust Statistics: winsorized mean, trimmed mean, interquartile range, range, coefficient of variation
• Order Statistics: percentile rank, deciles, percentiles
• Shape and Distribution: coefficient of skewness, coefficient of kurtosis, normality test
• Central Tendency Alternatives: winsorized median, midhinge
• Probability and Distribution: z-score, t-score, percentile from z-score, confidence intervals
• Time Series: moving average, exponential smoothing, seasonal decomposition

Multivariate Statistics

• Correlation: Pearson's, Spearman's, Kendall's tau, Q-correlation, point-biserial correlation
• Covariance: sample and population covariance
• Regression: simple linear, multiple linear, polynomial regression, residual analysis
• Sums: Sxx, Syy, and Sxy calculations
• Association Measures: chi-square test, Cramer's V, contingency coefficient

Installation

From PyPI (Recommended)

pip install python-stats

From GitHub

pip install git+https://github.com/RanaEhtashamAli/py-stats.git

Development Installation

git clone https://github.com/RanaEhtashamAli/py-stats.git
cd py-stats
pip install -e .

Quick Start

import py_stats as ps

# Basic statistics
data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
print(f"Mean: {ps.arithmetic_mean(data)}")
print(f"Median: {ps.median(data)}")
print(f"Standard Deviation: {ps.standard_deviation(data)}")

# Robust statistics
print(f"IQR: {ps.interquartile_range(data)}")
print(f"Coefficient of Variation: {ps.coefficient_of_variation(data)}")

# Multivariate analysis
x = [1, 2, 3, 4, 5]
y = [2, 4, 5, 4, 5]
print(f"Pearson Correlation: {ps.pearson_correlation(x, y)}")
print(f"Spearman Correlation: {ps.spearman_correlation(x, y)}")

# Regression
slope, intercept, r_squared = ps.linear_regression(x, y)
print(f"Regression: y = {slope:.2f}x + {intercept:.2f}, R² = {r_squared:.3f}")

Documentation

Univariate Functions

Means

• arithmetic_mean(data): Arithmetic mean
• harmonic_mean(data): Harmonic mean
• geometric_mean(data): Geometric mean
• quadratic_mean(data): Quadratic mean (RMS)

Central Tendency

• median(data): Median
• mode(data): Mode
• midrange(data): Midrange
• trimean(data): Trimean

Quantiles

• quartiles(data): First, second, and third quartiles
• hinges(data): Lower and upper hinges
• quantile(data, q): Quantile at specified probability

Dispersion

• variance(data, population=False): Variance (sample or population)
• standard_deviation(data, population=False): Standard deviation
• average_deviation(data): Average absolute deviation
• median_absolute_deviation(data): Median absolute deviation (MAD)

Shape

• skewness(data): Skewness coefficient
• kurtosis(data): Kurtosis coefficient

Robust Statistics

• winsorized_mean(data, percent=10.0): Winsorized mean
• trimmed_mean(data, percent=10.0): Trimmed mean
• interquartile_range(data): Interquartile range (IQR)
• range_value(data): Range (max - min)
• coefficient_of_variation(data): Coefficient of variation

Order Statistics

• percentile_rank(data, value): Percentile rank of a value
• deciles(data): All deciles (10th, 20th, ..., 90th percentiles)
• percentile(data, p): pth percentile (0-100)

Shape and Distribution

• coefficient_of_skewness(data): Standardized skewness
• coefficient_of_kurtosis(data): Standardized kurtosis
• simple_normality_test(data): Basic normality test

Central Tendency Alternatives

• winsorized_median(data, percent=10.0): Winsorized median
• midhinge(data): Midhinge

Probability and Distribution

• z_score(data, value): Z-score of a value
• t_score(data, value): T-score of a value
• percentile_from_z_score(z): Percentile from z-score
• confidence_interval_mean(data, confidence=0.95): Confidence interval for mean
• confidence_interval_proportion(successes, total, confidence=0.95): Confidence interval for proportion

Time Series

• moving_average(data, window=3): Simple moving average
• exponential_smoothing(data, alpha=0.3): Exponential smoothing
• seasonal_decomposition_simple(data, period=4): Simple seasonal decomposition

Specialized

• angular_mean(data, degrees=True): Mean of angular quantities
• running_average(data, window=3): Running average
• weighted_average(data, weights): Weighted average
• standard_error_mean(data): Standard error of the mean

Multivariate Functions

Correlation

• pearson_correlation(x, y): Pearson's correlation coefficient
• spearman_correlation(x, y): Spearman's rank correlation
• kendall_tau(x, y): Kendall's tau correlation
• q_correlation(x, y): Q-correlation coefficient
• point_biserial_correlation(x, y): Point-biserial correlation

Covariance

• covariance(x, y, population=False): Covariance (sample or population)

Regression

• linear_regression(x, y): Simple linear regression
• multiple_linear_regression(x_vars, y): Multiple linear regression
• polynomial_regression(x, y, degree=2): Polynomial regression
• residual_analysis(x, y): Residual analysis

Sums

• sum_xx(x): Sum of squared deviations (Sxx)
• sum_yy(y): Sum of squared deviations (Syy)
• sum_xy(x, y): Sum of cross-products (Sxy)

Association Measures

• chi_square_test(observed): Chi-square test of independence
• cramers_v(observed): Cramer's V association measure
• contingency_coefficient(observed): Contingency coefficient

📁 Package Structure

py-stats/
├── py_stats/
│   ├── __init__.py          # Package initialization (v2.0.0)
│   ├── univariate.py        # 40+ univariate functions
│   └── multivariate.py      # 20+ multivariate functions
├── tests/
│   ├── test_univariate.py   # Comprehensive univariate tests
│   └── test_multivariate.py # Comprehensive multivariate tests
├── examples/
│   ├── basic_usage.py       # Basic usage examples
│   └── advanced_usage.py    # Advanced usage examples
├── setup.py                 # Package configuration
├── pyproject.toml          # Modern packaging config
├── README.md               # This documentation
├── LICENSE                 # MIT License
└── .gitignore             # Git ignore patterns

Requirements

• Python 3.7 or higher
• NumPy 1.19.0 or higher

License

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

License Summary

The MIT License is a permissive license that allows you to:

• ✅ Use the software for any purpose
• ✅ Modify the software
• ✅ Distribute the software
• ✅ Distribute modified versions
• ✅ Use it commercially

The only requirement is that the original license and copyright notice must be included in any substantial portions of the software.

Contributing

We welcome contributions to make python-stats even better! Here's how you can help:

🤝 How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests for new functionality
4. Run the tests: python -m pytest tests/ -v
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📋 Contribution Guidelines

• Code Style: Follow PEP 8 and use Black for formatting
• Documentation: Add docstrings for new functions
• Tests: Include tests for new functionality
• Educational Focus: Keep the educational value in mind
• Mathematical Accuracy: Ensure statistical formulas are correct

🐛 Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Python version and environment details

Testing

Run the test suite:

python -m pytest tests/ -v

Performance Notes

This package is designed for educational purposes and small to medium-sized datasets. For large-scale data analysis, consider using NumPy, SciPy, or Pandas for better performance.

🎓 Educational Focus

This package is specifically designed for educational purposes and serves as an excellent resource for:

📚 Learning Applications

• Statistics Courses: Covers undergraduate statistics curriculum
• Programming Education: Demonstrates Python package development
• Research Methods: Practical statistical analysis tools
• Data Science: Foundation for more advanced analysis

🎯 Key Educational Features

• Mathematical Transparency: Clear implementation of statistical formulas
• Comprehensive Examples: Step-by-step usage demonstrations
• Pure Python: Easy to understand and modify
• Well-Documented: Detailed docstrings with mathematical explanations
• Test-Driven: All functions thoroughly tested for accuracy

💡 Use Cases

• Classroom Teaching: Interactive statistics demonstrations
• Self-Learning: Understanding statistical concepts through code
• Research Projects: Small-scale statistical analysis
• Code Review: Learning Python best practices
• Portfolio Projects: Showcasing statistical programming skills

The code is well-documented with clear mathematical formulas and examples, making it ideal for educational use.

🙏 Acknowledgments

• NumPy: For efficient numerical computations
• Scientific Community: For statistical formulas and methodologies
• Open Source Community: For inspiration and best practices
• Educational Institutions: For feedback and testing

📞 Support

If you have questions, suggestions, or need help:

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and function docstrings
• Examples: Check the examples/ directory for usage demonstrations

Made with ❤️ for the educational community