ccfx 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

ccfx/ccfx.py

@@ -26,7 +26,9 @@ import geopandas, pandas
 from osgeo import gdal, ogr, osr
 import py7zr
 import subprocess
-
+import multiprocessing
+from mutagen.mp3 import MP3
+from mutagen.id3 import ID3, TPE1, TALB, TIT2, TRCK, TDRC, TCON, APIC, COMM, USLT, TPE2, TCOM, TPE3, TPE4, TCOP, TENC, TSRC, TBPM
 
 
 # functions
@@ -56,8 +58,142 @@ def getExtension(filePath:str) -> str:
     '''
     Get the extension of a file
     filePath: file path
+
+    return: file extension without the dot
+    '''
+    return os.path.splitext(filePath)[1].lstrip('.')
+
+
+def getMp3Metadata(fn, imagePath=None):
+    '''
+    This function takes a path to mp3 and returns a dictionary with
+    the following keys:
+    - artist, album, title, track number, year, genre
+    '''
+    metadata = {}
+    
+    try:
+        audio = MP3(fn, ID3=ID3)
+        
+        if 'TPE1' in audio.tags: metadata['artist'] = str(audio.tags['TPE1'])
+        else: metadata['artist'] = "Unknown Artist"
+            
+        if 'TALB' in audio.tags: metadata['album'] = str(audio.tags['TALB'])
+        else: metadata['album'] = "Unknown Album"
+            
+        if 'TIT2' in audio.tags: metadata['title'] = str(audio.tags['TIT2'])
+        else: metadata['title'] = os.path.basename(fn).replace('.mp3', '')
+            
+        if 'TRCK' in audio.tags: metadata['track_number'] = str(audio.tags['TRCK'])
+        else: metadata['track_number'] = "0"
+            
+        if 'TDRC' in audio.tags: metadata['year'] = str(audio.tags['TDRC'])
+        else: metadata['year'] = "Unknown Year"
+            
+        if 'TCON' in audio.tags: metadata['genre'] = str(audio.tags['TCON'])
+        else: metadata['genre'] = "Unknown Genre"
+
+        if imagePath is not None:
+            foundImage = False
+            if audio.tags:
+                for tagKey in audio.tags.keys():
+                    if tagKey.startswith("APIC:"):
+                        with open(imagePath, 'wb') as img_file:
+                            img_file.write(audio.tags[tagKey].data)
+                        foundImage = True
+                        break
+            if not foundImage:
+                print("No image found in metadata.")
+    
+    except Exception as e:
+        print(f"Error extracting metadata from {fn}: {e}")
+        # Set default values if extraction fails
+        metadata = {
+            'artist': "Unknown Artist",
+            'album': "Unknown Album",
+            'title': os.path.basename(fn).replace('.mp3', ''),
+            'track_number': "0",
+            'year': "Unknown Year",
+            'genre': "Unknown Genre"
+        }
+    
+    return metadata
+
+def guessMimeType(imagePath):
+    ext = os.path.splitext(imagePath.lower())[1]
+    if ext in ['.jpg', '.jpeg']:
+        return 'image/jpeg'
+    elif ext == '.png':
+        return 'image/png'
+    return 'image/png'
+
+def setMp3Metadata(fn, metadata, imagePath=None):
     '''
-    return os.path.splitext(filePath)[1]
+    This function takes a path to an mp3 and a metadata dictionary,
+    then writes that metadata to the file's ID3 tags.
+    
+    The metadata dictionary should have these keys:
+    - artist, album, title, track_number, year, genre
+    
+    Additionally, an optional imagePath parameter can be provided to
+    attach album artwork from a PNG or JPEG file.
+    
+    Alternatively, you can include an 'imagePath' key in the metadata
+    dictionary instead of using the separate parameter.
+    '''
+    try:
+        # Try to load existing ID3 tags or create new ones if they don't exist
+        try:
+            audio = ID3(fn)
+        except:
+            audio = ID3()
+            
+        # Set artist
+        if 'artist' in metadata and metadata['artist']: audio['TPE1'] = TPE1(encoding=3, text=metadata['artist'])
+        if 'album' in metadata and metadata['album']: audio['TALB'] = TALB(encoding=3, text=metadata['album'])
+        if 'title' in metadata and metadata['title']: audio['TIT2'] = TIT2(encoding=3, text=metadata['title'])
+        if 'track_number' in metadata and metadata['track_number']: audio['TRCK'] = TRCK(encoding=3, text=metadata['track_number'])
+        if 'year' in metadata and metadata['year']: audio['TDRC'] = TDRC(encoding=3, text=metadata['year'])
+        if 'genre' in metadata and metadata['genre']: audio['TCON'] = TCON(encoding=3, text=metadata['genre'])
+        if 'comment' in metadata and metadata['comment']: audio['COMM'] = COMM(encoding=3, text=metadata['comment'])
+        if 'lyrics' in metadata and metadata['lyrics']: audio['USLT'] = USLT(encoding=3, text=metadata['lyrics'])
+        if 'publisher' in metadata and metadata['publisher']: audio['TPUB'] = TPE2(encoding=3, text=metadata['publisher'])
+        if 'composer' in metadata and metadata['composer']: audio['TCOM'] = TCOM(encoding=3, text=metadata['composer'])
+        if 'conductor' in metadata and metadata['conductor']: audio['TPE3'] = TPE3(encoding=3, text=metadata['conductor'])
+        if 'performer' in metadata and metadata['performer']: audio['TPE4'] = TPE4(encoding=3, text=metadata['performer'])
+        if 'copyright' in metadata and metadata['copyright']: audio['TCOP'] = TCOP(encoding=3, text=metadata['copyright'])
+        if 'encoded_by' in metadata and metadata['encoded_by']: audio['TENC'] = TENC(encoding=3, text=metadata['encoded_by'])
+        if 'encoder' in metadata and metadata['encoder']: audio['TENC'] = TENC(encoding=3, text=metadata['encoder'])
+        if 'isrc' in metadata and metadata['isrc']: audio['TSRC'] = TSRC(encoding=3, text=metadata['isrc'])
+        if 'bpm' in metadata and metadata['bpm']: audio['TBPM'] = TBPM(encoding=3, text=metadata['bpm'])
+        # Check if image path is in metadata dictionary and not provided as parameter
+        if imagePath is None and 'imagePath' in metadata:
+            imagePath = metadata['imagePath']
+        
+        # Attach image if provided
+        if imagePath and os.path.exists(imagePath):
+            with open(imagePath, 'rb') as img_file:
+                img_data = img_file.read()
+                
+            # Determine image MIME type
+            mime = guessMimeType(imagePath)
+                
+            # Create APIC frame for album artwork
+            audio['APIC'] = APIC(
+                encoding=3,         # UTF-8 encoding
+                mime=mime,          # MIME type of the image
+                type=3,             # 3 means 'Cover (front)'
+                desc='Cover',       # Description
+                data=img_data       # The image data
+            )
+                
+        # Save changes to the file
+        audio.save(fn)
+        return True
+    
+    except Exception as e:
+        print(f"Error writing metadata to {fn}: {e}")
+        return False
 
 
 def deleteFile(filePath:str, v:bool = False) -> bool:
@@ -86,6 +222,47 @@ def deleteFile(filePath:str, v:bool = False) -> bool:
     
     return deleted
 
+def deletePath(path:str, v:bool = False) -> bool:
+    '''
+    Delete a directory
+
+    path: directory
+    v: verbose (default is True)
+
+    return: True if the directory is deleted, False otherwise
+    '''
+    deleted = False
+    if os.path.exists(path):
+        try:
+            shutil.rmtree(path)
+            deleted = True
+        except:
+            print(f'! Could not delete {path}')
+            deleted = False
+        if v:
+            print(f'> {path} deleted')
+    else:
+        if v:
+            print(f'! {path} does not exist')
+        deleted = False
+
+
+def mergeRasterTiles(tileList:list, outFile:str) -> str:
+    '''
+    Merge raster tiles into one raster file
+    tileList: list of raster files
+    outFile: output raster file
+    '''
+    gdal.Warp(outFile, tileList)
+    return outFile
+
+def mergeRasterFiles(tileList:list, outFile:str) -> str:
+    '''
+    this function is an alias for mergeRasterTiles
+    '''
+    return mergeRasterTiles(tileList, outFile)
+
+
 def systemPlatform() -> str:
     '''
     Get the system platform
@@ -112,6 +289,55 @@ def fileCount(path:str = "./", extension:str = ".*", v:bool = True) -> int:
         print(f'> there are {count} {extension if not extension ==".*" else ""} files in {path}')
     return count
 
+def resampleRaster(inFile:str, outFile:str, resolution:float, dstSRS = None, resamplingMethod = 'bilinear', replaceOutput:bool = True, v:bool = True) -> str:
+    '''
+    Resample a raster file
+    inFile: input raster file
+    outFile: output raster file
+    resolution: resolution in the same units as the input raster
+    v: verbose (default is True)
+    available resample types:
+        'nearest', 'bilinear', 'cubic', 'cubicspline', 'lanczos', 'average', 'mode', 'max', 'min', 'med', 'q1', 'q3'
+    
+    return: output raster file path
+    '''
+
+    resamleTypes = {
+        'nearest': gdal.GRA_NearestNeighbour,
+        'bilinear': gdal.GRA_Bilinear,
+        'cubic': gdal.GRA_Cubic,
+        'cubicspline': gdal.GRA_CubicSpline,
+        'lanczos': gdal.GRA_Lanczos,
+        'average': gdal.GRA_Average,
+        'mode': gdal.GRA_Mode,
+        'max': gdal.GRA_Max,
+        'min': gdal.GRA_Min,
+        'med': gdal.GRA_Med,
+        'q1': gdal.GRA_Q1,
+        'q3': gdal.GRA_Q3
+    }
+
+    if not os.path.exists(inFile):
+        print(f'! {inFile} does not exist')
+        return None
+    
+    if os.path.exists(outFile):
+        if replaceOutput:
+            os.remove(outFile)
+        else:
+            print(f'! {outFile} already exists')      
+            return None
+    
+    if v:
+        print(f'> resampling {inFile} to {outFile} at {resolution}')
+    
+    ds = gdal.Open(inFile)
+    if dstSRS is None: gdal.Warp(outFile, ds, xRes=resolution, yRes=resolution, resampleAlg=resamleTypes[resamplingMethod])
+    else: gdal.Warp(outFile, ds, xRes=resolution, yRes=resolution, resampleAlg=resamleTypes[resamplingMethod], dstSRS=dstSRS)
+
+    ds = None
+    return outFile
+
 def watchFileCount(path:str="./", extension:str = ".*", interval:float = 0.2, duration = 3, v:bool = True) -> None:
     '''
     Watch the number of files in a directory with a specific extension
@@ -346,8 +572,11 @@ def moveDirectoryFiles(srcDir: str, destDir: str, v: bool = False) -> bool:
             src_file = os.path.join(root, file)
             dest_file = os.path.join(dest_root, file)
             if v:
-                print(f"\t> Moving file \n\t - {src_file}\n\t - to {dest_file}")
-            shutil.move(src_file, dest_file)
+                print(f"\t> Moving file \n\t - {src_file}\n\t     to {dest_file}")
+            try:
+                shutil.move(src_file, dest_file)
+            except Exception as e:
+                print(f"! Error moving file: {e}")
 
     return True
 
@@ -639,7 +868,7 @@ def netcdfExportTif(ncFile: str, variable: str, outputFile: str = None, band: in
     return dataset
 
 
-def getFileBaseName(filePath:str, extension:bool = False) -> str:
+def getFileBaseName(filePath:str, extension:bool = True) -> str:
     '''
     Get the base name of a file
     filePath: file path
@@ -710,12 +939,64 @@ def copyFile(source:str, destination:str, v:bool = True) -> None:
     source: source file
     destination: destination file
     '''
+    if not exists(os.path.dirname(destination)): createPath(f"{os.path.dirname(destination)}/")
     with open(source, 'rb') as src:
         with open(destination, 'wb') as dest: dest.write(src.read())
     
     if v: print(f'> {source} copied to \t - {destination}')
 
 
+def copyDirectory(source:str, destination:str, recursive = True, v:bool = True, filter = []) -> None:
+    '''
+    Copy a directory from source to destination
+    source: source directory
+    destination: destination directory
+    recursive: copy subdirectories (default is True)
+    v: verbose (default is True)
+    filter: list of file extensions to filter out
+    '''
+    if not exists(destination): os.makedirs(destination)
+
+    itemCount = None
+    counter = 1
+
+    if recursive:
+        if len(filter) > 0:
+            itemCount = len([fn for fn in listAllFiles(source) if not getExtension(fn) in filter])
+        else:
+            itemCount = len(listAllFiles(source))
+    else:
+        if len(filter) > 0:
+            itemCount = len([fn for fn in listFiles(source) if not getExtension(fn) in filter])
+        else:
+            itemCount = len(listFiles(source))
+
+
+    for item in os.listdir(source):
+        s = os.path.join(source, item)
+        d = os.path.join(destination, item)
+        if os.path.isdir(s):
+            if recursive: copyDirectory(s, d, recursive, v, filter)
+        else:
+            if len(filter) > 0:
+                if not getExtension(s) in filter:
+                    copyFile(s, d, v = False)
+                    counter += 1
+                    if v: showProgress(counter, itemCount, f'copying {getFileBaseName(item)}\t\t', barLength=50)
+            else:
+                copyFile(s, d, v = False)
+                if v: showProgress(counter, itemCount, f'copying {getFileBaseName(item)}\t\t', barLength=50)
+                counter += 1
+    print()
+
+
+def copyFolder(source:str, destination:str, v:bool = True) -> None:
+    '''
+    this function is an alias for copyDirectory
+    '''
+    copyDirectory(source, destination, v)
+
+
 def convertCoordinates(lon, lat, srcEPSG, dstCRS) -> tuple:
     """
     this function converts coordinates from one CRS to another
@@ -806,7 +1087,9 @@ def showProgress(count: int, end: int, message: str, barLength: int = 100) -> No
     filled = int(barLength * count / end)
     bar = '█' * filled + '░' * (barLength - filled)
     print(f'\r{bar}| {percentStr}% [{count}/{end}] | {message}       ', end='', flush=True)
-    if count == end: print()
+    if count == end:
+        print(f'\r{bar}| {percentStr}% [{count}/{end}]                          ', end='', flush=True)
+        print()
 
 
 def listAllFiles(folder, extension="*"):
@@ -854,4 +1137,338 @@ def createPointGeometry(coords: list, proj: str = "EPSG:4326") -> geopandas.GeoD
     gdf.reset_index(inplace=True)
     return gdf
 
+def calculateTimeseriesStats(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> dict:
+    '''
+    Calculate statistics for a timeseries
+
+    the assumed dataframe structure is:
+        date - DateTime
+        observed - float
+        simulated - float
+        
+    Parameters:
+        data: pandas.DataFrame
+            DataFrame containing the timeseries data
+        observed: str
+            name of the observed column
+        simulated: str
+            name of the simulated column
+        resample: str
+            if specified, the data will be resampled to the specified frequency
+            available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    Returns:
+        dict: Dictionary containing the following statistics:
+            NSE: Nash-Sutcliffe Efficiency
+            KGE: Kling-Gupta Efficiency
+            PBIAS: Percent Bias
+            LNSE: Log Nash-Sutcliffe Efficiency
+            R2: R-squared
+            RMSE: Root Mean Square Error
+            MAE: Mean Absolute Error
+            MSE: Mean Square Error
+            MAPE: Mean Absolute Percentage Error
+            alpha: Ratio of standard deviations
+            beta: Ratio of means
+    '''
+
+    options = {'H': '1H', 'D': '1D', 'M': '1M', 'Y': '1Y'}
+
+    if resample:
+        if resample not in options:
+            raise ValueError(f"Invalid resample option. Choose from {list(options.keys())}")
+        if not 'date' in data.columns:
+            for col in data.columns:
+                if data[col].dtype == 'datetime64[ns]':
+                    data = data.set_index(col).resample(options[resample]).mean()
+                    break
+            else:
+                raise ValueError("No datetime column found for resampling.")
+        else:
+            data = data.set_index('date').resample(options[resample]).mean()
+
+    # Auto-detect columns if not specified
+    if not observed and not simulated:
+        datetime_cols = [col for col in data.columns if data[col].dtype == 'datetime64[ns]']
+        if datetime_cols:
+            data = data.drop(datetime_cols, axis=1)
+        
+        if len(data.columns) == 2:
+            observed = data.columns[0]
+            simulated = data.columns[1]
+        else:
+            raise ValueError("Could not automatically detect observed and simulated columns")
+    elif not observed or not simulated:
+        raise ValueError("Both observed and simulated columns must be specified if one is specified")
+
+    # Extract data
+    obs = data[observed].values
+    sim = data[simulated].values
+
+    # Remove any rows where either observed or simulated is NaN
+    mask = ~(numpy.isnan(obs) | numpy.isnan(sim))
+    obs = obs[mask]
+    sim = sim[mask]
+
+    if len(obs) == 0:
+        raise ValueError("No valid data points after removing NaN values")
+
+    # Calculate statistics with error handling
+    try:
+        # Nash-Sutcliffe Efficiency (NSE)
+        denominator = numpy.sum((obs - numpy.mean(obs)) ** 2)
+        nse = 1 - numpy.sum((obs - sim) ** 2) / denominator if denominator != 0 else numpy.nan
+
+        # Kling-Gupta Efficiency (KGE) components
+        r = numpy.corrcoef(obs, sim)[0, 1]
+        obs_std = numpy.std(obs)
+        sim_std = numpy.std(sim)
+        obs_mean = numpy.mean(obs)
+        sim_mean = numpy.mean(sim)
+        
+        alpha = sim_std / obs_std if obs_std != 0 else numpy.nan
+        beta = sim_mean / obs_mean if obs_mean != 0 else numpy.nan
+        
+        # KGE calculation
+        if not any(numpy.isnan([r, alpha, beta])):
+            kge = 1 - numpy.sqrt((r - 1) ** 2 + (alpha - 1) ** 2 + (beta - 1) ** 2)
+        else:
+            kge = numpy.nan
+
+        # Percent Bias (PBIAS)
+        pbias = 100 * numpy.sum(sim - obs) / numpy.sum(obs) if numpy.sum(obs) != 0 else numpy.nan
+
+        # Log Nash-Sutcliffe Efficiency (LNSE)
+        eps = 0.0001
+        log_obs = numpy.log(obs + eps)
+        log_sim = numpy.log(sim + eps)
+        log_denominator = numpy.sum((log_obs - numpy.mean(log_obs)) ** 2)
+        lnse = 1 - numpy.sum((log_obs - log_sim) ** 2) / log_denominator if log_denominator != 0 else numpy.nan
+
+        # R-squared (R2)
+        r2 = r ** 2 if not numpy.isnan(r) else numpy.nan
+
+        # Root Mean Square Error (RMSE)
+        rmse = numpy.sqrt(numpy.mean((obs - sim) ** 2))
+
+        # Mean Absolute Error (MAE)
+        mae = numpy.mean(numpy.abs(obs - sim))
+
+        # Mean Square Error (MSE)
+        mse = numpy.mean((obs - sim) ** 2)
+
+        # Mean Absolute Percentage Error (MAPE)
+        with numpy.errstate(divide='ignore', invalid='ignore'):
+            mape = numpy.mean(numpy.abs((obs - sim) / obs) * 100)
+            mape = numpy.nan if numpy.isinf(mape) else mape
+
+    except Exception as e:
+        print(f"Warning: Error in statistical calculations: {str(e)}")
+        return {stat: numpy.nan for stat in ['NSE', 'KGE', 'PBIAS', 'LNSE', 'R2', 'RMSE', 'MAE', 'MSE', 'MAPE', 'alpha', 'beta']}
+
+    return {
+        'NSE': nse,
+        'KGE': kge,
+        'PBIAS': pbias,
+        'LNSE': lnse,
+        'R2': r2,
+        'RMSE': rmse,
+        'MAE': mae,
+        'MSE': mse,
+        'MAPE': mape,
+        'alpha': alpha,
+        'beta': beta
+    }
+
+
+def getNSE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the NSE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        NSE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['NSE']
+
+def getKGE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the KGE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        KGE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['KGE']
+
+def getPBIAS(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the PBIAS
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        PBIAS value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['PBIAS']
+
+
+def getLNSE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the LNSE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        LNSE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['LNSE']
+
+def getR2(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the R2
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        R2 value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['R2']
+
+def getRMSE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the RMSE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        RMSE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['RMSE']
+
+def getMAE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the MAE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        MAE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['MAE']
+
+def getMSE(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> float:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return the MSE
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: float
+        MSE value
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats['MSE']
+
+def getTimeseriesStats(data:pandas.DataFrame, observed:str = None, simulated:str = None, resample:str = None ) -> dict:
+    '''
+    this function is a wrapper for calculateTimeseriesStats specifically to return all stats
+
+    data: pandas.DataFrame
+        DataFrame containing the timeseries data
+    observed: str
+        name of the observed column
+    simulated: str
+        name of the simulated column
+    resample: str
+        if specified, the data will be resampled to the specified frequency
+        available options: 'H' (hourly), 'D' (daily), 'M' (monthly), 'Y' (yearly)
+
+    return: dict
+        dictionary containing all stats
+    '''
+    stats = calculateTimeseriesStats(data, observed, simulated, resample)
+
+    return stats
+
 ignoreWarnings()

{ccfx-0.3.0.dist-info → ccfx-0.5.0.dist-info}/METADATA

@@ -1,146 +1,148 @@
-Metadata-Version: 2.1
-Name: ccfx
-Version: 0.3.0
-Summary: Your package description here
-Author-email: Celray James CHAWANDA <celray@chawanda.com>
-License: MIT
-Project-URL: Homepage, https://github.com/celray/ccfx
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: netCDF4
-Requires-Dist: gdal
-Requires-Dist: numpy
-Requires-Dist: shapely
-Requires-Dist: geopandas
-Requires-Dist: pandas
-Requires-Dist: xlsxwriter
-Requires-Dist: pyodbc
-Requires-Dist: sqlalchemy
-Requires-Dist: python-docx
-Requires-Dist: py7zr
-
-# ccfx
-
-`ccfx` is a comprehensive Python package designed to streamline file and data management, geospatial analysis, and NetCDF file processing for quick prototyping. The library provides versatile tools for file handling, raster and vector manipulation, database connectivity, and data export for geospatial and scientific computing projects.
-
-## Features
-
-1. **File Management**:
-   - List, delete, move, and count files within directories.
-   - Monitor file count over time in a specific directory.
-   - Save, load, and manage Python variables via pickle serialization.
-
-2. **Geospatial Data Processing**:
-   - Read, write, and manage raster and vector geospatial data.
-   - Clip rasters by bounding boxes and extract raster values at specified coordinates.
-   - Create grids of polygons based on shapefile boundaries with user-defined resolutions.
-   - Convert coordinates between coordinate reference systems (CRS).
-   - Write NumPy arrays to GeoTIFF files with projection and geotransform settings.
-
-3. **NetCDF File Handling**:
-   - List available variables and dimensions in NetCDF files.
-   - Export NetCDF variables to GeoTIFF format.
-   - Calculate sum and average maps from NetCDF data across multiple files.
-
-4. **Database Connectivity**:
-   - Access and interact with databases using ODBC and SQLAlchemy for flexible database management.
-   - Connect to both SQL Server and SQLite databases.
-
-5. **Progress Tracking and System Info**:
-   - Display dynamic progress bars for long-running operations.
-   - Check the system’s platform information.
-   - Enable or disable warnings programmatically.
-
-6. **Excel and Word File Handling**:
-   - Create and modify Excel files using xlsxwriter.
-   - Generate Word documents with advanced formatting options using python-docx.
-
-## Installation
-
-Install `ccfx` via pip:
-```bash
-pip install ccfx
-```
-
-## Dependencies
-
-`ccfx` relies on the following libraries:
-
-- **netCDF4**: For working with NetCDF files.
-- **gdal**: Required for geospatial raster data manipulation.
-- **numpy**: For array processing and numerical operations.
-- **pandas**: For data manipulation and analysis.
-- **shapely**: Provides geometric operations for spatial data.
-- **geopandas**: Extends pandas to handle geospatial data.
-- **xlsxwriter**: For creating and writing Excel files.
-- **pyodbc**: Enables connectivity to databases through ODBC.
-- **sqlalchemy**: Provides SQL toolkit and ORM features for database access.
-- **python-docx**: Enables creation and manipulation of Word documents.
-
-These dependencies will be installed automatically when `ccfx` is installed.
-
-## API Reference
-
-### `listFiles(path: str, ext: str = None) -> list`
-Lists all files in a directory with a specified extension.
-
-- **Parameters**:
-  - `path` (str): The directory to search.
-  - `ext` (str, optional): File extension to filter by, e.g., `'txt'`, `'.txt'`, `'*txt'`, or `'*.txt'`.
-
-- **Returns**:
-  - `list`: A list of file paths matching the criteria.
-
-### `deleteFile(filePath: str, v: bool = False) -> bool`
-Deletes a specified file with optional verbose output.
-
-- **Parameters**:
-  - `filePath` (str): Path to the file to be deleted.
-  - `v` (bool, optional): If `True`, prints a confirmation message. Defaults to `False`.
-
-- **Returns**:
-  - `bool`: `True` if deletion was successful; `False` otherwise.
-
-### `createGrid(shapefile_path: str, resolution: float, useDegree: bool = True) -> tuple`
-Generates a grid of polygons from a shapefile at a given resolution.
-
-- **Parameters**:
-  - `shapefile_path` (str): Path to the shapefile.
-  - `resolution` (float): Resolution of the grid.
-  - `useDegree` (bool, optional): If `True`, coordinates are in degrees. Defaults to `True`.
-
-- **Returns**:
-  - `tuple`: Contains grid coordinates and metadata.
-
-### `clipRasterByExtent(inFile: str, outFile: str, bounds: tuple) -> str`
-Clips a raster to specified bounding box coordinates.
-
-- **Parameters**:
-  - `inFile` (str): Path to the input raster file.
-  - `outFile` (str): Path to the output clipped raster file.
-  - `bounds` (tuple): Bounding box as `(minx, miny, maxx, maxy)`.
-
-- **Returns**:
-  - `str`: Path to the clipped raster file.
-
-### `netcdfVariablesList(ncFile: str) -> list`
-Lists all variables in a NetCDF file.
-
-- **Parameters**:
-  - `ncFile` (str): Path to the NetCDF file.
-
-- **Returns**:
-  - `list`: A list of variable names in the file.
-
-### ... And More ...
-
-## Contributing
-
-Contributions are welcome! Please fork the repository, make your changes, and submit a pull request.
-
-## License
-This project is licensed under the MIT License.
+Metadata-Version: 2.4
+Name: ccfx
+Version: 0.5.0
+Summary: This package simplifies regular common actions for quick prototyping in a user friendly way
+Author-email: Celray James CHAWANDA <celray@chawanda.com>
+License: MIT
+Project-URL: Homepage, https://github.com/celray/ccfx
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: netCDF4
+Requires-Dist: gdal
+Requires-Dist: numpy
+Requires-Dist: shapely
+Requires-Dist: geopandas
+Requires-Dist: pandas
+Requires-Dist: xlsxwriter
+Requires-Dist: pyodbc
+Requires-Dist: sqlalchemy
+Requires-Dist: python-docx
+Requires-Dist: py7zr
+Requires-Dist: mutagen
+Dynamic: license-file
+
+# ccfx
+
+`ccfx` is a comprehensive Python package designed to streamline file and data management, geospatial analysis, and NetCDF file processing for quick prototyping. The library provides versatile tools for file handling, raster and vector manipulation, database connectivity, and data export for geospatial and scientific computing projects.
+
+## Features
+
+1. **File Management**:
+   - List, delete, move, and count files within directories.
+   - Monitor file count over time in a specific directory.
+   - Save, load, and manage Python variables via pickle serialization.
+
+2. **Geospatial Data Processing**:
+   - Read, write, and manage raster and vector geospatial data.
+   - Clip rasters by bounding boxes and extract raster values at specified coordinates.
+   - Create grids of polygons based on shapefile boundaries with user-defined resolutions.
+   - Convert coordinates between coordinate reference systems (CRS).
+   - Write NumPy arrays to GeoTIFF files with projection and geotransform settings.
+
+3. **NetCDF File Handling**:
+   - List available variables and dimensions in NetCDF files.
+   - Export NetCDF variables to GeoTIFF format.
+   - Calculate sum and average maps from NetCDF data across multiple files.
+
+4. **Database Connectivity**:
+   - Access and interact with databases using ODBC and SQLAlchemy for flexible database management.
+   - Connect to both SQL Server and SQLite databases.
+
+5. **Progress Tracking and System Info**:
+   - Display dynamic progress bars for long-running operations.
+   - Check the system’s platform information.
+   - Enable or disable warnings programmatically.
+
+6. **Excel and Word File Handling**:
+   - Create and modify Excel files using xlsxwriter.
+   - Generate Word documents with advanced formatting options using python-docx.
+
+## Installation
+
+Install `ccfx` via pip:
+```bash
+pip install ccfx
+```
+
+## Dependencies
+
+`ccfx` relies on the following libraries:
+
+- **netCDF4**: For working with NetCDF files.
+- **gdal**: Required for geospatial raster data manipulation.
+- **numpy**: For array processing and numerical operations.
+- **pandas**: For data manipulation and analysis.
+- **shapely**: Provides geometric operations for spatial data.
+- **geopandas**: Extends pandas to handle geospatial data.
+- **xlsxwriter**: For creating and writing Excel files.
+- **pyodbc**: Enables connectivity to databases through ODBC.
+- **sqlalchemy**: Provides SQL toolkit and ORM features for database access.
+- **python-docx**: Enables creation and manipulation of Word documents.
+
+These dependencies will be installed automatically when `ccfx` is installed.
+
+## API Reference
+
+### `listFiles(path: str, ext: str = None) -> list`
+Lists all files in a directory with a specified extension.
+
+- **Parameters**:
+  - `path` (str): The directory to search.
+  - `ext` (str, optional): File extension to filter by, e.g., `'txt'`, `'.txt'`, `'*txt'`, or `'*.txt'`.
+
+- **Returns**:
+  - `list`: A list of file paths matching the criteria.
+
+### `deleteFile(filePath: str, v: bool = False) -> bool`
+Deletes a specified file with optional verbose output.
+
+- **Parameters**:
+  - `filePath` (str): Path to the file to be deleted.
+  - `v` (bool, optional): If `True`, prints a confirmation message. Defaults to `False`.
+
+- **Returns**:
+  - `bool`: `True` if deletion was successful; `False` otherwise.
+
+### `createGrid(shapefile_path: str, resolution: float, useDegree: bool = True) -> tuple`
+Generates a grid of polygons from a shapefile at a given resolution.
+
+- **Parameters**:
+  - `shapefile_path` (str): Path to the shapefile.
+  - `resolution` (float): Resolution of the grid.
+  - `useDegree` (bool, optional): If `True`, coordinates are in degrees. Defaults to `True`.
+
+- **Returns**:
+  - `tuple`: Contains grid coordinates and metadata.
+
+### `clipRasterByExtent(inFile: str, outFile: str, bounds: tuple) -> str`
+Clips a raster to specified bounding box coordinates.
+
+- **Parameters**:
+  - `inFile` (str): Path to the input raster file.
+  - `outFile` (str): Path to the output clipped raster file.
+  - `bounds` (tuple): Bounding box as `(minx, miny, maxx, maxy)`.
+
+- **Returns**:
+  - `str`: Path to the clipped raster file.
+
+### `netcdfVariablesList(ncFile: str) -> list`
+Lists all variables in a NetCDF file.
+
+- **Parameters**:
+  - `ncFile` (str): Path to the NetCDF file.
+
+- **Returns**:
+  - `list`: A list of variable names in the file.
+
+### ... And More ...
+
+## Contributing
+
+Contributions are welcome! Please fork the repository, make your changes, and submit a pull request.
+
+## License
+This project is licensed under the MIT License.

ccfx-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ccfx/__init__.py,sha256=VmBeF3oj6JTJ_793d4i8PvhyF8_FxaxA1L_FmHWqitc,142
+ccfx/ccfx.py,sha256=A61uV0bKlusLAcLlgNVhKaMQ4KutWxB7hzEQnitJpus,51808
+ccfx/excel.py,sha256=cQ4TQW49XqbMB3sSS0IOhO3-WArIolEBIrvOvhFyPtI,4757
+ccfx/mssqlConnection.py,sha256=TwyZXhHHI7zy6BSfH1pszuHVJ5cmndRC5dVxvEtSTks,7904
+ccfx/sqliteConnection.py,sha256=jEJ94D5ySt84N7AeDpa27Rclt1NaKhkX6nYzidwApIg,11104
+ccfx/word.py,sha256=AGa64jX5Zl5qotZh5L0QmrsjTnktIBhmj_ByRKZ88vw,3061
+ccfx-0.5.0.dist-info/licenses/LICENSE,sha256=2-M3fBUS3FmrSIrqd3cZDmxXxojWVJtZY-SHSRE6RxM,1098
+ccfx-0.5.0.dist-info/METADATA,sha256=6tpyj3FwWBdkm8BCvU26J9rZFsP_mCIoZUxTb71GYRA,5381
+ccfx-0.5.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+ccfx-0.5.0.dist-info/top_level.txt,sha256=_cSvSA1WX2K8TgoV3iBJUdUZZqMKJbOPLNnKLYSLHaw,5
+ccfx-0.5.0.dist-info/RECORD,,

{ccfx-0.3.0.dist-info → ccfx-0.5.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.3.0)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ccfx-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-ccfx/__init__.py,sha256=VmBeF3oj6JTJ_793d4i8PvhyF8_FxaxA1L_FmHWqitc,142
-ccfx/ccfx.py,sha256=lB6hTCywvbMpHH6lMgw0UJuoiU-7vA22yvttvKFG5Gc,28450
-ccfx/excel.py,sha256=cQ4TQW49XqbMB3sSS0IOhO3-WArIolEBIrvOvhFyPtI,4757
-ccfx/mssqlConnection.py,sha256=TwyZXhHHI7zy6BSfH1pszuHVJ5cmndRC5dVxvEtSTks,7904
-ccfx/sqliteConnection.py,sha256=jEJ94D5ySt84N7AeDpa27Rclt1NaKhkX6nYzidwApIg,11104
-ccfx/word.py,sha256=AGa64jX5Zl5qotZh5L0QmrsjTnktIBhmj_ByRKZ88vw,3061
-ccfx-0.3.0.dist-info/LICENSE,sha256=2-M3fBUS3FmrSIrqd3cZDmxXxojWVJtZY-SHSRE6RxM,1098
-ccfx-0.3.0.dist-info/METADATA,sha256=9C2wcPC02QWli3N8GPc0_80K4LZ-YI2ZpNPlMadHGjw,5419
-ccfx-0.3.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
-ccfx-0.3.0.dist-info/top_level.txt,sha256=_cSvSA1WX2K8TgoV3iBJUdUZZqMKJbOPLNnKLYSLHaw,5
-ccfx-0.3.0.dist-info/RECORD,,