Metadata-Version: 2.1
Name: btsf
Version: 1.0.1
Summary: btsf (for Binary Time Series File) is a package to store your data in a condensed and fast yet flexible way.
Home-page: https://github.com/pklaus/btsf
Author: Philipp Klaus
Author-email: philipp.l.klaus@web.de
License: GPL
Description: ## btfs - Binary Time Series File
        
        This is a module to store time series data in a custom binary file format (.btfs) with the following **objectives**:
        
        * small file size
        * appendable
        * fast to read and write
        * easy to adapt to new scenarios
        * ability to store metadata (units, annotations, ...)
        * targeted at Python (adding support for other languages should be rather straight-forward)
        * possibility to tune implementation details such as byte order or padding
        
        Quick description of the file structure of a .btfs file:
        
        ```
        File Signature (fixed)
        (32 bytes)
        
        at least one intro section
        (16-byte header + variable length payload + variable length reserved zero-bytes)
        
        end of intro section header
        (16 bytes)
        
        concatenated packed structured data
        (structure of fixed length * N, thus appendable!)
        ```
        
        A typical use case for btfs is:
        
        * Time series measurements of one or multiple variables (sampled at the same time).
        * Appending (=adding) new measurements to file is always possible, eg. after a restart of the acquisition.
        * The metadata of the file (stored in the intro sections of the file) can later be updated
          with additional information, such as data annotations, tags or similar.
        
        What btfs is not suited for, at least not perfectly:
        
        * event-based data with varying number of values or varying value types.
        
        *Note: As the size of the introduction sections cannot be expanded, editing the metadata is only possible
        within the limits of reserved extra space for the intro section, specified when creating the file.*
        
        ### Installation
        
            pip install --upgrade https://github.com/pklaus/btsf/archive/master.zip
        
        ### Example Usage
        
        ```python
        from btsf import Metric, MetricType, BinaryTimeSeriesFile
        
        metrics = [
            Metric('time', MetricType.Double),
            Metric('power', MetricType.Float),
            Metric('counter', MetricType.UInt64),
            Metric('flags', MetricType.UInt8),
        ]
        
        with BinaryTimeSeriesFile.create('test.btsf', metrics) as f:
            f.append(1.1, 2.2, 0xf0f0f0f0f0f0f0f0, 1)
            f.append(3.3, 4.4, 0xffffffffffffffff, 2)
            f.append(5.0, 1.0, 0x123456789ABCDEF1, 3)
        ```
        
        Checking what's in a .btsf file is easy with the supplied CLI:
        
        ```bash
        btsf info test.btsf
        ```
        
        resulting in the following output:
        
        ```
        test.btsf - Number of entries: 3
        Metrics:
        time (MetricType.Double)   power (MetricType.Float)   counter (MetricType.UInt64)   flags (MetricType.UInt8)
        entries:
        (1.1, 2.200000047683716, 17361641481138401520, 1)
        (3.3, 4.400000095367432, 18446744073709551615, 2)
        (5.0, 1.0, 1311768467463790321, 3)
        ```
        
Keywords: binary,time series,file,storage
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
Provides-Extra: to_numpy
Provides-Extra: to_pandas
Provides-Extra: tests
