Metadata-Version: 2.1
Name: carbonium
Version: 0.10.1
Summary: manage a list of names with several properties and (overlapping) order criteria
Home-page: https://github.com/pietrogiuffrida/carbonium/
Author: Pietro Giuffrida
Author-email: pietro.giuffri@gmail.com
License: MIT
Description: # carbonium
        
        Easily manage a list of names with several
        properties and (overlapping) order criteria.
        
        ## Installation
        
        Install carbonium is as easy as run 
        ```pip install carbonium```.
        
        ## Usage
        
        As first step you should define a name list:
        
        ```python
        name_list = [
            {
                "domains": ["raw", "output"],
                "name": "var1",
                "alias": "column_1_name",
                "output_order": 1,
                "filling_value": 10,
            },
            {
                "domains": ["raw"],
                "name": "var2",
                "alias": "column_2_name",
                "output_order": 2,
            },
            {
                "domains": ["new", "output"],
                "name": "new_var",
                "alias": "new_column_name",
            },
        ]
        ```
        
        Each *name definition* is a dictionary that
        contains some common, mandatory key, and some
        other keys, domain-specific or name-specific.
        
        Mandatory keys are only three:
        
        - domains, a list of string, each representing a *domain*
        - name, a string, uniquely identifiers of a *name*
        - alias, a string that can be used to refers to
            the name in context where it is named with
            this alternative string.
            
        Then, each name belongs to some domains. Domains
        are used to perfom names selection (give me all
        names belonging to *domain*). Names that belongs
        to the same domain should have the same optional
        attributes.
        
        After *name list* definition, you can instantiate
        the structure class:
        
        ```python
        from carbonium import Structure
        
        structure = Structure(name_list)
        ```
        
        Internally, the Structure class iteratively instantiate a
        Name class for each *name definition*. After this
        step you can access to each Name and its properties
        through ```c``` object, but you can also use one of
        property or method of the class.
        
        ```python
        print(structure.names)
        # returns:  ['var1', 'var2', 'new_var']
        
        print(structure.domains)
        # returns: {'new', 'output', 'raw'}
        
        print(
            structure.var1.name,
            structure.var1.domains,
            structure.var1.output_order
        )
        ```
        
        Calling *structure.var1.name* you have access to the
        string associated to var1... and so on.
        
        ```python
        ordered_raw_columns = [
                (
                    i,
                    structure.get(i).output_order,
                    structure.get(i).get("filling_value")
                )
                for i in structure.get_names('raw')
        ]
        
        ordered_raw_columns = sorted(
            ordered_raw_columns,
            key=lambda x: x[1]
        )
        ```
        
        In this example all the names belonging to *raw*
        domain are extracted with some other properties.
        In this way the same name can be used in different
        domains or contexts by referring to contexctual
        relevant properties.
        
        ```python
        import pandas as pd
        df = pd.DataFrame([
            {"var1": 100, "var2": 200},
            {"var2": 220},
        ])
        
        for name in structure.get_names('raw'):
            alias = structure.get(name).alias
            filling = structure.get(name).get("filling_value")
            if filling:
                df[alias].fillna(filling, inplace=True)
        
        for name in structure.get_names('new'):
            alias = structure.get(name).alias
            df[alias] = "arbitrary"    
        
        output_columns = structure.get_names('new')
        df[output_columns].to_parquet('output.parquet')
        ```
        
        As you can see, whithout modify the code but only the
        taxonomy described in *name_list*, you can affect
        different columns.
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
