# Popyrous
(Pouya's Python Routines) A collection of useful and frequently encountered Python routines for (data) science, research, development, and everyday life.
Author: Pouya P. Niaz (<pniaz20@ku.edu.tr> , <pouya.p.niaz@gmail.com>)
Version: 0.0.13
Last Update: August 02, 2024
This is a collection of Python routines for the following purposes:
- Checking for packages and installing missing ones iwithin scripts without the need for Jupyter and symbols like "!" and "%".
- Reading and writing `.mat` files coming to/from MathWorks MATLAB software.
- Building and manipulating time series data using sliding windows, low-pass filtering, etc.
- Building flexible and easy-to-use datasets for data analysis or machine learning out of structured time series experiments (multiple subjects, conditions, repetitions, etc.).
- Downloading data/files from the internet and Google Drive, using simple functions.
- Compressing or extracting Zip files with LZMA, etc., using simple functions.
Install with:
```bash
pip install popyrous
```
-------------------------------------------------------------
## 1- Intro
This package is a collection of routines I have widely used in my scientific, academic and engineering life.
It holds functionality for data and file manipulation, some tools for manipulating time series data,
some tools for extracting machine-learning-ready time series datasets from tabular timeseries data of structured experiments,
i.e., experiments performed with multiple subjects, under multiple conditions, with many repetitions, and so forth.
The contents and applications of this package are described briefly below. However, extensive documentation is provided in the docstrings of
all functions and classes in the code, which is where you should look for further information.
-------------------------------------------------------------
## 2- Contents and Submodules
### 2-1- matlab
This submodule contains functions for reading and writing data to and from `.mat` files.
- `type_compatible(typ)`: Determining whether or not a Python data type is compatible for writing into `.mat` files.
- `save_workspace(filename, masterdict)`: Save dictionary holding variables and data into `.mat` file.
- `load_workspace(filename, dictname)`: Load contents of `.mat` file into an (existing or new) dictionary.
### 2-2- packages
This submodule contains functions for checking which packages are installed in the environment without having to be in a notebook and running commands with `!` or `%`.
Also, you can check for a list of required packages (with or without required versions) and install missing packages, or wrong-versioned packages at the same time.
- `get_package_list()`: Get list (dictionary with keys being packages and values being versions) of packages in the (conda) environment.
- `check_packages(pkglst, install_missing, **kwargs)`: Get a list of required packages and see if they are all installed, installing the missing ones in the process.
Example:
```python
from popyrous.packages import check_packages
check_packages(["numpy","scipy","pandas==1.5.2"], install_missing=True, reinstall_wrong_versions=True)
```
### 2-3- timeseries
This submodule contains some classes and functions for working easily and efficiently with time series data.
You can filter data, pass it through sliding window and extract data for machine/deep learning, etc.
Also, given the dataframe of a tructured time series experiment where multiple subjects repeated an experiment
multiple times under various conditions, you can get their data, preprocess, post-process, filter, extract sliding window, etc.
and then keep some subjects, conditions, or trials for training and the rest for testing (for data analysis or machine learning), and so forth.
#### 2-3-1- sliding_window
The `sliding_window` function gets tabular timeseries data, extracts sliding windows from it, then downsamples or inverts them, etc. then returns them.
Sliding windows of time series data is used for time series modeling, prediction, classification, regression and forecasting problems.
#### 2-3-2- datasets
- `TabularDataset`: A class for reading time series data from an array, downsampling, preprocessing, and extracting sliding windows from it.
- `make_squeezed_dataset(hparams, inputs, outputs, **kwargs)`: Gets inputs/outputs, returns squeezed (2D) sliding window dataset ready to be fed to, e.g., an ANN model.
- `make_unsqueezed_dataset(hparams, inputs, outputs, **kwargs)`: Gets inputs/outputs, returns unsqueezed (3D) sliding window dataset ready to be fed to, e.g., an LSTM model.
#### 2-3-3- experiment
- `TimeseriesExperiment`: A class that gets a single dataframe containing the time series data of a series of structured experiments where
there are multiple subjects, repetitions and trials. The data can then be processed such that data of each trial is separated and processed individually,
some subjects, conditions or trials are kept for training/testing, there is preprocessing before extracting sliding windows, and postprocessing after it,
and so on. This class comes in handy when the data of such a structured series of experiments needs to be processed and fed to a machine learning model, for instance.
- `generate_cell_array`: A function, which is a more concise version of the above class, doing everything in one shot and returning everything together.
#### 2-3-4- filt
Some functions for low-pass filtering time series data.
- `butter_lowpass_filter_forward` filters input data with a digital Butterworth low-pass filter gvien sampling and cutoff frequncies, and filter order.
This filter is causal, and only goes forward in time. It does not see its future. It is used for real-time implementations.
Because this filter is causal, it induces a phase shift, so the filtered signal will have a delay relative to the real signal.
The lower the cutoff frequency, the longer the delay. This function in turn uses the `sosfiltfilt` utility of SciPy.
- `butter_lowpass_filter_back_to_back` filters input data similarly, but uses `sosfiltfilt` to go back to back, so it looks both to past and future.
It can only smooth the data offline, since it has access to the future as well. Unlike the previous causal filter, it has no phase shift.
- `butter_highpass_filter_forward` and `butter_highpass_filter_back_to_back` can be used for similar purposes.
- The new `butter_filter` function encompasses virtually any kind of digital Butterworth filter, including all of the above.
#### 2-3-5- metrics
Some metrics used for time-series classification, etc.
- `tsc_metrics`: Time-series classification metrics, including accuracy, f1 score, concurrency (transitioning on time) and consistency (not changing prediction in consistent non-transitioning portions of the data)
#### 2-3-6- cwt
Continmuous Wavelet Transform
- `cwt_for_batch`: gets a numpy array of shape, e.g., (batchsize, channels, seqlen) [could be any shape, as long as time is the last dimension]
and returns an array of its CWT coefficients.
Additionally, it can downsample it and remove the last row and column. Returns a (batchsize, channels, coefs, seqlen) dataset of 2D images.
- `cwt_for_tensor`: gets a data tensor of any shape and simply performs CWT on it. Takes the last dimension as time, and adds a dimension
to the beginning, containing coefficients.
### 2-4- web
This submodule contains some web-related functions for downloading files from the internet or Google Drive, storing them, reading their contents, etc.
- `download_google_drive_file(shareable_link, output_file)`: Gets shareable link of a Google Drive file, and downlaods it.
- `download(url, filename, **kwargs)`: Downlaods material from the internet, and reads its content or stores in a file.
### 2-5- zipfiles
This submodule contains some functions for compressing/decompressing zip files.
- `extract_files(fileName)`: Extracts everything in the zip file.
- `compress_files(file_name, **kwargs)`: Compresses files into a zip file. Options for compression method, etc. are provided.
### 2-6- ml
This submodule contains some machine-learning-related code. For now, it just contains a function for pretty plotting confusion matrices (see credits).
- `make_confusion_matrix` gets a confusion matrix and some parameters, and pretty plots it.
-------------------------------------------------------------
## 3- License
This package is built with MIT license.
-------------------------------------------------------------
## 4- Credits
Pretty plotting confusion matrix:
Dennis T
<https://github.com/DTrimarchi10/confusion_matrix>
<https://medium.com/@dtuk81/confusion-matrix-visualization-fc31e3f30fea>
Raw data
{
"_id": null,
"home_page": "https://github.com/pniaz20/popyrous",
"name": "popyrous",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "python, routines, matlab, zipfile, packages, time series, filtering, download, web",
"author": "Pouya P. Niaz",
"author_email": "<pniaz20@ku.edu.tr>",
"download_url": "https://files.pythonhosted.org/packages/fd/48/9bb73c2ddf4e7f2d54c1a2cdfb1f07fb00c728eeab00876960640061b941/popyrous-0.0.13.tar.gz",
"platform": null,
"description": "# Popyrous\n\n(Pouya's Python Routines) A collection of useful and frequently encountered Python routines for (data) science, research, development, and everyday life.\n\nAuthor: Pouya P. Niaz (<pniaz20@ku.edu.tr> , <pouya.p.niaz@gmail.com>) \nVersion: 0.0.13 \nLast Update: August 02, 2024\n\nThis is a collection of Python routines for the following purposes:\n\n- Checking for packages and installing missing ones iwithin scripts without the need for Jupyter and symbols like \"!\" and \"%\".\n- Reading and writing `.mat` files coming to/from MathWorks MATLAB software.\n- Building and manipulating time series data using sliding windows, low-pass filtering, etc.\n- Building flexible and easy-to-use datasets for data analysis or machine learning out of structured time series experiments (multiple subjects, conditions, repetitions, etc.).\n- Downloading data/files from the internet and Google Drive, using simple functions.\n- Compressing or extracting Zip files with LZMA, etc., using simple functions.\n\nInstall with:\n\n```bash\npip install popyrous\n```\n\n-------------------------------------------------------------\n\n## 1- Intro\n\nThis package is a collection of routines I have widely used in my scientific, academic and engineering life.\nIt holds functionality for data and file manipulation, some tools for manipulating time series data,\nsome tools for extracting machine-learning-ready time series datasets from tabular timeseries data of structured experiments,\ni.e., experiments performed with multiple subjects, under multiple conditions, with many repetitions, and so forth.\n\nThe contents and applications of this package are described briefly below. However, extensive documentation is provided in the docstrings of\nall functions and classes in the code, which is where you should look for further information.\n\n-------------------------------------------------------------\n\n## 2- Contents and Submodules\n\n### 2-1- matlab\n\nThis submodule contains functions for reading and writing data to and from `.mat` files.\n\n- `type_compatible(typ)`: Determining whether or not a Python data type is compatible for writing into `.mat` files.\n- `save_workspace(filename, masterdict)`: Save dictionary holding variables and data into `.mat` file.\n- `load_workspace(filename, dictname)`: Load contents of `.mat` file into an (existing or new) dictionary.\n\n### 2-2- packages\n\nThis submodule contains functions for checking which packages are installed in the environment without having to be in a notebook and running commands with `!` or `%`.\nAlso, you can check for a list of required packages (with or without required versions) and install missing packages, or wrong-versioned packages at the same time.\n\n- `get_package_list()`: Get list (dictionary with keys being packages and values being versions) of packages in the (conda) environment.\n- `check_packages(pkglst, install_missing, **kwargs)`: Get a list of required packages and see if they are all installed, installing the missing ones in the process.\n\nExample:\n\n```python\nfrom popyrous.packages import check_packages\ncheck_packages([\"numpy\",\"scipy\",\"pandas==1.5.2\"], install_missing=True, reinstall_wrong_versions=True)\n```\n\n### 2-3- timeseries\n\nThis submodule contains some classes and functions for working easily and efficiently with time series data.\nYou can filter data, pass it through sliding window and extract data for machine/deep learning, etc.\nAlso, given the dataframe of a tructured time series experiment where multiple subjects repeated an experiment\nmultiple times under various conditions, you can get their data, preprocess, post-process, filter, extract sliding window, etc.\nand then keep some subjects, conditions, or trials for training and the rest for testing (for data analysis or machine learning), and so forth.\n\n#### 2-3-1- sliding_window\n\nThe `sliding_window` function gets tabular timeseries data, extracts sliding windows from it, then downsamples or inverts them, etc. then returns them.\nSliding windows of time series data is used for time series modeling, prediction, classification, regression and forecasting problems.\n\n#### 2-3-2- datasets\n\n- `TabularDataset`: A class for reading time series data from an array, downsampling, preprocessing, and extracting sliding windows from it.\n- `make_squeezed_dataset(hparams, inputs, outputs, **kwargs)`: Gets inputs/outputs, returns squeezed (2D) sliding window dataset ready to be fed to, e.g., an ANN model.\n- `make_unsqueezed_dataset(hparams, inputs, outputs, **kwargs)`: Gets inputs/outputs, returns unsqueezed (3D) sliding window dataset ready to be fed to, e.g., an LSTM model.\n\n#### 2-3-3- experiment\n\n- `TimeseriesExperiment`: A class that gets a single dataframe containing the time series data of a series of structured experiments where\n there are multiple subjects, repetitions and trials. The data can then be processed such that data of each trial is separated and processed individually,\n some subjects, conditions or trials are kept for training/testing, there is preprocessing before extracting sliding windows, and postprocessing after it,\n and so on. This class comes in handy when the data of such a structured series of experiments needs to be processed and fed to a machine learning model, for instance.\n- `generate_cell_array`: A function, which is a more concise version of the above class, doing everything in one shot and returning everything together.\n\n#### 2-3-4- filt\n\nSome functions for low-pass filtering time series data.\n\n- `butter_lowpass_filter_forward` filters input data with a digital Butterworth low-pass filter gvien sampling and cutoff frequncies, and filter order.\n This filter is causal, and only goes forward in time. It does not see its future. It is used for real-time implementations.\n Because this filter is causal, it induces a phase shift, so the filtered signal will have a delay relative to the real signal.\n The lower the cutoff frequency, the longer the delay. This function in turn uses the `sosfiltfilt` utility of SciPy.\n- `butter_lowpass_filter_back_to_back` filters input data similarly, but uses `sosfiltfilt` to go back to back, so it looks both to past and future.\n It can only smooth the data offline, since it has access to the future as well. Unlike the previous causal filter, it has no phase shift.\n- `butter_highpass_filter_forward` and `butter_highpass_filter_back_to_back` can be used for similar purposes.\n- The new `butter_filter` function encompasses virtually any kind of digital Butterworth filter, including all of the above.\n\n#### 2-3-5- metrics\n\nSome metrics used for time-series classification, etc.\n\n- `tsc_metrics`: Time-series classification metrics, including accuracy, f1 score, concurrency (transitioning on time) and consistency (not changing prediction in consistent non-transitioning portions of the data)\n\n#### 2-3-6- cwt\n\nContinmuous Wavelet Transform\n\n- `cwt_for_batch`: gets a numpy array of shape, e.g., (batchsize, channels, seqlen) [could be any shape, as long as time is the last dimension]\n and returns an array of its CWT coefficients.\n Additionally, it can downsample it and remove the last row and column. Returns a (batchsize, channels, coefs, seqlen) dataset of 2D images.\n- `cwt_for_tensor`: gets a data tensor of any shape and simply performs CWT on it. Takes the last dimension as time, and adds a dimension\n to the beginning, containing coefficients.\n\n### 2-4- web\n\nThis submodule contains some web-related functions for downloading files from the internet or Google Drive, storing them, reading their contents, etc.\n\n- `download_google_drive_file(shareable_link, output_file)`: Gets shareable link of a Google Drive file, and downlaods it.\n- `download(url, filename, **kwargs)`: Downlaods material from the internet, and reads its content or stores in a file.\n\n### 2-5- zipfiles\n\nThis submodule contains some functions for compressing/decompressing zip files.\n\n- `extract_files(fileName)`: Extracts everything in the zip file.\n- `compress_files(file_name, **kwargs)`: Compresses files into a zip file. Options for compression method, etc. are provided.\n\n### 2-6- ml\n\nThis submodule contains some machine-learning-related code. For now, it just contains a function for pretty plotting confusion matrices (see credits).\n\n- `make_confusion_matrix` gets a confusion matrix and some parameters, and pretty plots it.\n\n-------------------------------------------------------------\n\n## 3- License\n\nThis package is built with MIT license.\n\n-------------------------------------------------------------\n\n## 4- Credits\n\nPretty plotting confusion matrix: \nDennis T \n<https://github.com/DTrimarchi10/confusion_matrix> \n<https://medium.com/@dtuk81/confusion-matrix-visualization-fc31e3f30fea>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pouya's Python routines. A collection of useful Python routines for everyday and professional life.",
"version": "0.0.13",
"project_urls": {
"Homepage": "https://github.com/pniaz20/popyrous"
},
"split_keywords": [
"python",
" routines",
" matlab",
" zipfile",
" packages",
" time series",
" filtering",
" download",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be8d9c29de8ad8e217546c64cc28e6d443b19c8777fa832bd93f1c8ddddc0023",
"md5": "0e3242c7d630b913556912a9cc09d658",
"sha256": "330cd6a2181cc632949fc810ac7e8bc420807c633648d729d4d2c15eacf7ab4f"
},
"downloads": -1,
"filename": "popyrous-0.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e3242c7d630b913556912a9cc09d658",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 46089,
"upload_time": "2024-08-02T11:01:13",
"upload_time_iso_8601": "2024-08-02T11:01:13.900532Z",
"url": "https://files.pythonhosted.org/packages/be/8d/9c29de8ad8e217546c64cc28e6d443b19c8777fa832bd93f1c8ddddc0023/popyrous-0.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd489bb73c2ddf4e7f2d54c1a2cdfb1f07fb00c728eeab00876960640061b941",
"md5": "df12a8c3f237e253f6f43b5d645b39fe",
"sha256": "cc4dfb925de184552cf865c8a8fc9709c0fd5b26a7bdf28936b5fc724c1c45a2"
},
"downloads": -1,
"filename": "popyrous-0.0.13.tar.gz",
"has_sig": false,
"md5_digest": "df12a8c3f237e253f6f43b5d645b39fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 44334,
"upload_time": "2024-08-02T11:01:15",
"upload_time_iso_8601": "2024-08-02T11:01:15.652801Z",
"url": "https://files.pythonhosted.org/packages/fd/48/9bb73c2ddf4e7f2d54c1a2cdfb1f07fb00c728eeab00876960640061b941/popyrous-0.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-02 11:01:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pniaz20",
"github_project": "popyrous",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "popyrous"
}
JSON
